@aiwg/cli 2026.10.1 → 2026.10.4

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

@@ -4,9 +4,21 @@
  * Implements `aiwg init` — the first-run wizard that creates
  * `.aiwg/aiwg.config` for the current project.
  *
- * Prompts:
- *   1. Which AI provider toolchains does this project target?
- *   2. Would you like to add any scripts? (optional)
+ * Prompts, and the argument that answers each one directly (#3062):
+ *   1. Which AI provider toolchains does this project target? → `--providers <list>`
+ *   2. Would you like to add default scripts (deploy/doctor/sync)? → `--default-scripts true|false`
+ *   3. Add a custom script (name + command)? → `--script <name>=<command>` (repeatable;
+ *      implies yes) or `--custom-scripts true|false` (answers the question directly
+ *      without supplying a script; `false` declines it outright)
+ *   4. Enable direct worker dispatch? → `--worker-dispatch enable|decline`
+ *
+ * With a terminal attached, any of these given directly skips that
+ * question — only genuinely missing values are still asked. Without one,
+ * omitted inputs fall back to their documented defaults (`claude`, default
+ * scripts on) rather than erroring, since those defaults are always safe to
+ * apply headless. `--non-interactive`/`--yes` force the non-interactive
+ * path even with a terminal attached. `--dry-run` never writes anything,
+ * including the baseline config itself.
  *
  * Runs automatically on first `aiwg use` when no config exists.
  * Can also be run explicitly to reconfigure.
@@ -16,10 +28,14 @@
 import readline from 'readline';
 import { readAiwgConfig, writeAiwgConfig, emptyConfig, populateDeployedTo, VALID_PROVIDERS, getConfigPath, } from '../../config/aiwg-config.js';
 import * as ui from '../ui.js';
-import { askString as sharedAskString, askYesNo as sharedAskYesNo } from '../prompt-utils.js';
+import { askString as sharedAskString, askYesNo as sharedAskYesNo, askConsent } from '../prompt-utils.js';
 import { normalizeProviderDefinitionId } from '../../providers/provider-definitions.js';
 import { writeNormalizedAiwgMd } from '../../smiths/context-pipeline/finalization.js';
 import { ensureWorkspaceContext } from '../../smiths/context-pipeline/workspace-context.js';
+import { detectInstalledWorkerClis, evaluateWorkerDispatchOffer, workerDispatchOfferQuestion, workerDispatchOfferHintWithArg, parseWorkerDispatchArg, } from '../../models/worker-dispatch-offer.js';
+import { EXIT_CODES } from '../errors.js';
+import { isInteractive } from '../env.js';
+import { requireFlagValue, collectFlagValues, parseBooleanFlagValue, parseListFlagValue, parseKeyValueEntry, MissingFlagValueError, } from '../flag-parsing.js';
 const PROVIDER_LABELS = {
     antigravity: 'Google Antigravity .agents/',
     claude: 'Claude Code       .claude/',
@@ -76,6 +92,89 @@ async function askProviders(rl, signal) {
     }
     return selected.length > 0 ? selected : ['claude'];
 }
+/**
+ * Non-interactive / --yes / no-TTY runs never prompt and never touch the
+ * config (#3050 item 2) — they only print one line naming the enable
+ * command, when two or more worker CLIs are detected and dispatch is not
+ * already on or declined. The hint also names `--worker-dispatch` (#3062):
+ * that argument answers the same question headlessly.
+ */
+function renderWorkerDispatchHintIfApplicable(parallelism, setup) {
+    const offer = evaluateWorkerDispatchOffer(parallelism, setup, detectInstalledWorkerClis());
+    if (offer.shouldOffer)
+        ui.dim(`  ${workerDispatchOfferHintWithArg(offer.detected)}`);
+}
+function parseInitArgInputs(args) {
+    // #3062 second review, finding 4: `precedence: 'first'` matches this
+    // command's pre-existing (and, for `--providers`/`--default-scripts`/
+    // `--script`/`--custom-scripts`, only) convention — see
+    // `parseInitArgInputs`'s module-level callers for why `--worker-dispatch`
+    // specifically needs `rejectEmpty` (an explicit empty choice is never
+    // meaningful and must not silently fall through to "not given").
+    const workerDispatchArg = parseWorkerDispatchArg(requireFlagValue(args, { rejectEmpty: true }, '--worker-dispatch'));
+    const rawProviders = parseListFlagValue(requireFlagValue(args, {}, '--providers'));
+    const providersArg = rawProviders?.map((entry) => {
+        const canonical = normalizeProviderDefinitionId(entry);
+        if (!canonical || canonical === 'generic' || !VALID_PROVIDERS.includes(canonical)) {
+            throw new Error(`--providers: unknown provider '${entry}' (valid: ${VALID_PROVIDERS.join(', ')})`);
+        }
+        return canonical;
+    });
+    if (providersArg && providersArg.length === 0) {
+        throw new Error('--providers requires at least one provider name');
+    }
+    const defaultScriptsArg = parseBooleanFlagValue(requireFlagValue(args, {}, '--default-scripts'), '--default-scripts');
+    const customScriptsArg = parseBooleanFlagValue(requireFlagValue(args, {}, '--custom-scripts'), '--custom-scripts');
+    const scriptPairs = {};
+    for (const entry of collectFlagValues(args, {}, '--script')) {
+        const [name, command] = parseKeyValueEntry(entry, '--script');
+        scriptPairs[name] = command;
+    }
+    return { workerDispatchArg, providersArg, defaultScriptsArg, customScriptsArg, scriptPairs };
+}
+/** One-line description of what an explicit `--worker-dispatch` choice would write. */
+function describeWorkerDispatchWrite(arg) {
+    return arg === 'enable'
+        ? 'enable parallelism.worker_dispatch'
+        : 'record a worker-dispatch decline (setup.worker_dispatch_offer)';
+}
+/**
+ * Resolve an explicit `--worker-dispatch` choice into a decision to apply to
+ * a brand-new config (#3062). Under `--dry-run`, writes nothing — reports
+ * what would be written instead and returns `undefined` so the caller never
+ * applies it to the config it builds.
+ */
+function resolveWorkerDispatchDecisionForNewConfig(arg, dryRun) {
+    if (dryRun) {
+        ui.dim(`  Would ${describeWorkerDispatchWrite(arg)} (--dry-run writes nothing).`);
+        return undefined;
+    }
+    return { kind: arg };
+}
+/**
+ * Interactive-only: asks the one consent question (default/unanswered is
+ * no, strict `y`/`yes` parsing only) when two or more worker CLIs are
+ * detected and dispatch is not already on or declined. Returns the
+ * decision to apply, or `undefined` when there is nothing to offer, or
+ * when the prompt timed out / stdin closed without an answer — only an
+ * actually-answered "no" is recorded as a persistent decline (#3050
+ * review item 4).
+ */
+async function askWorkerDispatchOffer(rl, parallelism, setup, signal) {
+    const offer = evaluateWorkerDispatchOffer(parallelism, setup, detectInstalledWorkerClis());
+    if (!offer.shouldOffer)
+        return undefined;
+    console.log('');
+    const outcome = await askConsent(rl, workerDispatchOfferQuestion(offer.detected), undefined, signal);
+    if (outcome.kind !== 'answered')
+        return undefined;
+    if (outcome.value) {
+        ui.success('  Will enable parallelism.worker_dispatch.');
+        return { kind: 'enable' };
+    }
+    ui.dim('  Noted — enable later with `aiwg config set --project parallelism.worker_dispatch true`.');
+    return { kind: 'decline' };
+}
 export const initHandler = {
     id: 'init',
     name: 'Init',
@@ -84,16 +183,34 @@ export const initHandler = {
     aliases: [],
     async execute(ctx) {
         const force = ctx.args.includes('--force');
-        // Treat a missing stdin TTY as non-interactive so piped/backgrounded
-        // invocations never attempt to create a readline interface. This is a
-        // single authoritative check — downstream code MUST NOT re-derive
+        // `--non-interactive`/`--yes` are this command's own explicit flags for
+        // the one shared interactive decision (#3062 review item 12) — honored
+        // ahead of (and regardless of) the environment-only checks `isInteractive`
+        // otherwise applies (TTY, TERM, CI). Downstream code MUST NOT re-derive
         // interactive-ness from process.stdin.isTTY again.
-        const nonInteractive = ctx.args.includes('--non-interactive') ||
-            ctx.args.includes('--yes') ||
-            !process.stdin.isTTY ||
-            !process.stdout.isTTY ||
-            process.env['CI'] === 'true';
+        const explicitNonInteractive = ctx.args.includes('--non-interactive') || ctx.args.includes('--yes');
+        const nonInteractive = !isInteractive(explicitNonInteractive);
         const projectDir = ctx.cwd;
+        // `--worker-dispatch enable|decline` answers the worker-dispatch offer
+        // directly (#3062), with or without a terminal, and is honored even when
+        // fewer than two worker CLIs are detected — an explicit choice overrides
+        // the presence-only detection gate. `--providers`/`--default-scripts`/
+        // `--script` answer the remaining wizard inputs the same way (review
+        // item 10). Every flag is parsed strictly (review item 11): present
+        // without a usable value is a usage error, raised here before any
+        // preflight check, read, or write.
+        let workerDispatchArg;
+        let providersArg;
+        let defaultScriptsArg;
+        let customScriptsArg;
+        let scriptPairs;
+        try {
+            ({ workerDispatchArg, providersArg, defaultScriptsArg, customScriptsArg, scriptPairs } = parseInitArgInputs(ctx.args));
+        }
+        catch (err) {
+            const message = err instanceof MissingFlagValueError ? `${err.message}.` : err instanceof Error ? err.message : String(err);
+            return { exitCode: EXIT_CODES.USAGE, message };
+        }
         ui.blank();
         console.log(`  ${ui.brandMark()} ${ui.bold('AIWG Baseline Config')}`);
         ui.rule();
@@ -101,7 +218,10 @@ export const initHandler = {
         const existing = await readAiwgConfig(projectDir);
         if (existing && !force) {
             ui.info(`Config already exists: ${getConfigPath(projectDir)}`);
-            await writeNormalizedAiwgMd(projectDir);
+            // #3062 review item 18: `--dry-run` must write nothing at all, not
+            // just skip the worker-dispatch increment below.
+            if (!ctx.dryRun)
+                await writeNormalizedAiwgMd(projectDir);
             console.log(`  Providers: ${existing.providers.join(', ')}`);
             const scriptCount = Object.keys(existing.scripts).length;
             if (scriptCount > 0) {
@@ -111,22 +231,72 @@ export const initHandler = {
             ui.dim('  Ask your AIWG agent to review repo, tracker, delivery, signing, and provider policy.');
             ui.dim('  Agents may use `aiwg setup project --dry-run` as the CLI helper for that review.');
             ui.dim('  Run `aiwg init --force` only when you need to recreate the baseline config.');
+            // #3050: guide users to direct worker dispatch from the setup step they
+            // already run, instead of leaving it undiscoverable. `--dry-run` must
+            // never prompt and never write (review item 1) — it degrades to the
+            // same hint-only behavior as non-interactive runs.
+            // #3062: an explicit `--worker-dispatch` argument always answers the
+            // question directly (bypassing the ask/hint entirely) except under
+            // `--dry-run`, which still writes nothing — it reports what would be
+            // written instead.
+            if (workerDispatchArg) {
+                if (ctx.dryRun) {
+                    ui.dim(`  Would ${describeWorkerDispatchWrite(workerDispatchArg)} (--dry-run writes nothing).`);
+                }
+                else if (workerDispatchArg === 'enable') {
+                    await writeAiwgConfig(projectDir, { ...existing, parallelism: { ...existing.parallelism, worker_dispatch: true } });
+                    ui.success('  Enabled parallelism.worker_dispatch. Next: aiwg doctor --probe-workers --qualify.');
+                }
+                else {
+                    await writeAiwgConfig(projectDir, { ...existing, setup: { ...existing.setup, worker_dispatch_offer: 'declined' } });
+                    ui.success('  Recorded worker-dispatch decline (setup.worker_dispatch_offer).');
+                }
+            }
+            else if (nonInteractive || ctx.dryRun) {
+                renderWorkerDispatchHintIfApplicable(existing.parallelism, existing.setup);
+            }
+            else {
+                const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                try {
+                    const decision = await askWorkerDispatchOffer(rl, existing.parallelism, existing.setup, ctx.signal);
+                    if (decision?.kind === 'enable') {
+                        await writeAiwgConfig(projectDir, { ...existing, parallelism: { ...existing.parallelism, worker_dispatch: true } });
+                        ui.info('Next: aiwg doctor --probe-workers --qualify.');
+                    }
+                    else if (decision?.kind === 'decline') {
+                        await writeAiwgConfig(projectDir, { ...existing, setup: { ...existing.setup, worker_dispatch_offer: 'declined' } });
+                    }
+                }
+                finally {
+                    rl.close();
+                }
+            }
             ui.blank();
             return { exitCode: 0 };
         }
         let providers;
         let scripts = {};
+        let workerDispatchDecision;
+        const DEFAULT_SCRIPTS = { deploy: 'aiwg use all', doctor: 'aiwg doctor', sync: 'aiwg sync' };
         if (nonInteractive) {
-            // Non-interactive: use defaults
-            providers = ['claude'];
-            scripts = {
-                deploy: 'aiwg use all',
-                doctor: 'aiwg doctor',
-                sync: 'aiwg sync',
-            };
+            // Non-interactive: an explicit `--providers`/`--default-scripts`
+            // answers the corresponding wizard input directly (review item 10);
+            // anything not supplied keeps its prior default.
+            providers = providersArg ?? ['claude'];
+            const includeDefaultScripts = defaultScriptsArg ?? true;
+            scripts = { ...(includeDefaultScripts ? DEFAULT_SCRIPTS : {}), ...scriptPairs };
+            if (workerDispatchArg) {
+                workerDispatchDecision = resolveWorkerDispatchDecisionForNewConfig(workerDispatchArg, ctx.dryRun);
+            }
+            else {
+                renderWorkerDispatchHintIfApplicable(undefined, undefined);
+            }
         }
         else {
-            // Interactive wizard
+            // Interactive wizard — skip a prompt whenever its argument already
+            // answered it (review item 10/12: "with a terminal we can skip steps
+            // for any params provided and only provide interaction when we are
+            // missing a value").
             const rl = readline.createInterface({
                 input: process.stdin,
                 output: process.stdout,
@@ -134,16 +304,29 @@ export const initHandler = {
             try {
                 // Thread ctx.signal through every prompt so Ctrl-C during the wizard
                 // cancels cleanly instead of being absorbed by readline (POC #926).
-                providers = await askProviders(rl, ctx.signal);
+                providers = providersArg ?? await askProviders(rl, ctx.signal);
                 console.log('');
-                const addScripts = await askYesNo(rl, '  Add default scripts (deploy, doctor, sync)? [Y/n]: ', true, ctx.signal);
-                if (addScripts) {
-                    scripts = {
-                        deploy: 'aiwg use all',
-                        doctor: 'aiwg doctor',
-                        sync: 'aiwg sync',
-                    };
-                    const addCustom = await askYesNo(rl, '  Add a custom script? [y/N]: ', false, ctx.signal);
+                const includeDefaultScripts = defaultScriptsArg !== undefined
+                    ? defaultScriptsArg
+                    : await askYesNo(rl, '  Add default scripts (deploy, doctor, sync)? [Y/n]: ', true, ctx.signal);
+                scripts = includeDefaultScripts ? { ...DEFAULT_SCRIPTS } : {};
+                if (Object.keys(scriptPairs).length > 0) {
+                    // `--script` already answered "add a custom script?" (implicit
+                    // yes) and its name/command sub-prompts — never ask any of the
+                    // three (#3062 second review, finding 5a).
+                    scripts = { ...scripts, ...scriptPairs };
+                }
+                else {
+                    // `--custom-scripts true|false` answers "add a custom script?"
+                    // directly when `--script` itself was not given — an explicit
+                    // decline (`false`) skips the question entirely, same as every
+                    // other already-supplied input; `true` still asks for the
+                    // name/command, since those were not supplied either.
+                    const addCustom = customScriptsArg !== undefined
+                        ? customScriptsArg
+                        : includeDefaultScripts
+                            ? await askYesNo(rl, '  Add a custom script? [y/N]: ', false, ctx.signal)
+                            : false;
                     if (addCustom) {
                         const name = await askString(rl, '  Script name: ', '', ctx.signal);
                         const cmd = await askString(rl, '  Command: ', '', ctx.signal);
@@ -152,6 +335,21 @@ export const initHandler = {
                         }
                     }
                 }
+                // #3050: offer direct worker dispatch inside the same wizard — but
+                // `--dry-run` must never prompt or write anything from the offer
+                // (review item 1), so it degrades to the hint instead. An explicit
+                // `--worker-dispatch` argument (#3062) always answers the question
+                // directly instead of asking or hinting, still subject to `--dry-run`
+                // writing nothing.
+                if (workerDispatchArg) {
+                    workerDispatchDecision = resolveWorkerDispatchDecisionForNewConfig(workerDispatchArg, ctx.dryRun);
+                }
+                else if (ctx.dryRun) {
+                    renderWorkerDispatchHintIfApplicable(undefined, undefined);
+                }
+                else {
+                    workerDispatchDecision = await askWorkerDispatchOffer(rl, undefined, undefined, ctx.signal);
+                }
             }
             finally {
                 rl.close();
@@ -160,10 +358,30 @@ export const initHandler = {
         // Build config
         let config = emptyConfig(providers);
         config.scripts = scripts;
+        if (workerDispatchDecision?.kind === 'enable') {
+            config.parallelism = { ...config.parallelism, worker_dispatch: true };
+        }
+        else if (workerDispatchDecision?.kind === 'decline') {
+            config.setup = { ...config.setup, worker_dispatch_offer: 'declined' };
+        }
+        // #3062 review item 18: `--dry-run` writes nothing at all — not even
+        // the baseline config — rather than only skipping the worker-dispatch
+        // increment. Report what would be written instead.
+        if (ctx.dryRun) {
+            ui.blank();
+            ui.dim(`  Would create ${getConfigPath(projectDir)} (--dry-run writes nothing).`);
+            ui.dim(`  Providers: ${providers.join(', ')}`);
+            if (Object.keys(scripts).length > 0)
+                ui.dim(`  Scripts: ${Object.keys(scripts).join(', ')}`);
+            ui.blank();
+            return { exitCode: 0 };
+        }
         // Populate deployedTo from disk for entries with empty deployedTo (#721)
         config = await populateDeployedTo(config, projectDir);
         // Write
         await writeAiwgConfig(projectDir, config);
+        if (workerDispatchDecision?.kind === 'enable')
+            ui.info('Next: aiwg doctor --probe-workers --qualify.');
         const normalizedAiwgMdPath = await writeNormalizedAiwgMd(projectDir);
         const workspace = await ensureWorkspaceContext(projectDir);
         ui.blank();

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

@@ -25,6 +25,11 @@ export const lintHandler = {
     description: 'Lint AIWG artifacts against declarative rule sets',
     category: 'utility',
     aliases: ['-lint', '--lint'],
+    async help() {
+        const { main } = await import('../../lint/cli.js');
+        await main(['--help']);
+        return { exitCode: 0 };
+    },
     async execute(ctx) {
         try {
             const { main } = await import('../../lint/cli.js');

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

@@ -15,6 +15,7 @@ import * as ui from '../ui.js';
 import { promises as fs } from 'node:fs';
 import { join } from 'node:path';
 import { createHash, randomBytes } from 'node:crypto';
+import { assertMissionWorkerHandoff } from '../../mission-protocol/codecs.js';
 // ── Constants ────────────────────────────────────────────────
 const MC_ROOT = '.aiwg/ralph-external/mc';
 const SESSIONS_DIR = join(MC_ROOT, 'sessions');
@@ -378,6 +379,18 @@ async function mcDispatch(ctx) {
         ui.error(sessionId ? `Session not found: ${sessionId}` : 'No active session. Run `aiwg mc start` first.');
         return { exitCode: 1 };
     }
+    // mission-dispatch accepts only the frozen objective envelope. Worker
+    // bindings can arrive through its existing session, so inspect that payload.
+    try {
+        assertMissionWorkerHandoff(selected, 'mc-cli');
+        for (const mission of selected.missions)
+            assertMissionWorkerHandoff(mission, 'mc-cli');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        ui.error(message);
+        return { exitCode: 1, message };
+    }
     // #1361: Check project-level parallelism cap. Active missions = running or
     // queued; if at cap, warn but still queue (FIFO behavior — the mission goes
     // into the session as 'queued' and will run when a slot frees up).
@@ -560,6 +573,16 @@ async function mcRun(ctx) {
         return { exitCode: 1 };
     }
     const queued = session.missions.filter((m) => m.status === 'queued');
+    try {
+        assertMissionWorkerHandoff(session, 'mc-cli');
+        for (const mission of queued)
+            assertMissionWorkerHandoff(mission, 'mc-cli');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        ui.error(message);
+        return { exitCode: 1, message };
+    }
     if (queued.length === 0) {
         ui.info(`No queued missions in session ${session.id}. Run \`aiwg mc dispatch ${session.id} "<objective>"\` to add one.`);
         return { exitCode: 0 };

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

@@ -4,16 +4,114 @@
  */
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
+import { isDeepStrictEqual } from 'node:util';
 import path from 'node:path';
 import { glob } from 'glob';
 import { load as loadYaml } from 'js-yaml';
-import { compileModelPolicy, validateCanonicalModelPolicy, validateUserProjectModelConfig, } from '../../models/provider-policy.js';
+import { compileModelPolicy, validateCanonicalModelPolicy, validateUserProjectModelConfig, loadProviderModelCapabilities, WorkerPolicyError, } from '../../models/provider-policy.js';
 import { resolveGrokBuildRoleModel } from '../../models/grok-build-models.js';
+import { readAiwgConfig, emptyConfig } from '../../config/aiwg-config.js';
+import { ConfigLoader } from '../../models/config-loader.js';
+import { loadRecordedWorkerInstallations, normalizeWorkerVersionBanner } from '../../models/worker-installation.mjs';
+import { parseWorkerCommandArgs, resolveWorkerInvocation, workerInvocationDiagnostic } from '../../serve/worker-invocation.js';
+/** Compare selection facts without observation times or approval/provenance metadata. */
+function approvalFacts(row) {
+    if (!row.worker)
+        return null;
+    const { observedAt, verifiedAt, firstObservedAt, fetchedAt, retiredAt, evidenceDigest, provenance, qualification, ...facts } = row.worker;
+    return { id: row.id, apiModelId: row.apiModelId, llmProvider: row.llmProvider,
+        hidden: row.hidden, reasoningEfforts: row.reasoningEfforts, facts };
+}
+/**
+ * #2892: exported so the MCP worker-invoke bridge can resolve a direct worker
+ * plan in-process (same snapshot/driver construction as `aiwg models resolve`),
+ * without shelling out to the CLI. No new loader is introduced; this is the
+ * CLI's own existing default `ModelsWorkerServices.load`.
+ */
+export async function loadWorkerInputs(ctx) {
+    const config = await readAiwgConfig(ctx.cwd) ?? emptyConfig();
+    const loader = new ConfigLoader(ctx.cwd);
+    const models = await loader.load(config.parallelism);
+    const catalog = await effectiveCatalog(ctx, ctx.cwd, false, parseArgs(['resolve']));
+    const registry = loadProviderModelCapabilities();
+    // Let the resolver explain the dispatch gate before requiring host qualification (#3070).
+    if (!config.parallelism?.worker_dispatch) {
+        return { snapshot: { config, models, modelDigests: loader.getInputDigests(), catalog,
+                registry, installations: {} }, drivers: {} };
+    }
+    const { registry: qualifiedRegistry, installations, drivers, observations } = await loadRecordedWorkerInstallations({
+        registry, cwd: ctx.cwd, policy: models.defaults.workerSelection, parallelism: config.parallelism,
+    });
+    catalog.discovery ??= { source: 'static', fetchedAt: new Date().toISOString(), providers: {} };
+    catalog.discovery.instances = { ...catalog.discovery.instances };
+    for (const [cli, approved] of Object.entries(observations)) {
+        const cached = catalog.discovery.instances[cli] ?? catalog.discovery.providers[approved.provider];
+        // Discovery stores the CLI banner; qualification stores its parsed version.
+        const invocation = drivers[cli]?.qualification.adapter.invocation;
+        const versionPattern = invocation?.kind === 'process' ? invocation.versionPattern : undefined;
+        const version = (value) => {
+            if (value === undefined)
+                return value;
+            try {
+                return normalizeWorkerVersionBanner(value, versionPattern);
+            }
+            catch {
+                return value;
+            } // A changed or invalid banner must still fail closed.
+        };
+        const current = cached ? { ...cached, runtimeVersion: version(cached.runtimeVersion),
+            accountBinding: cached.accountBinding ?? cached.accountScope,
+            models: cached.models.map(row => row.worker ? { ...row,
+                worker: { ...row.worker, runtimeVersion: version(row.worker.runtimeVersion) } } : row) } : undefined;
+        // Stale discovery must not replace a newer approved observation.
+        if (!current || Date.parse(approved.observedAt) > Date.parse(current.observedAt)) {
+            catalog.discovery.instances[cli] = approved;
+            continue;
+        }
+        catalog.discovery.instances[cli] = { ...current, models: current.models.map(row => {
+                const prior = approved.models.find(model => model.id === row.id);
+                if (!row.worker || !prior?.worker)
+                    return row;
+                if (Date.parse(prior.worker.observedAt) > Date.parse(row.worker.observedAt))
+                    return prior;
+                // New retirement/conflict/visibility evidence always requires requalification.
+                const safe = !row.hidden && row.worker.visibility !== 'hidden'
+                    && row.worker.lifecycle !== 'retired' && !row.worker.conflicts?.length;
+                return safe && isDeepStrictEqual(approvalFacts(row), approvalFacts(prior))
+                    ? { ...row, worker: { ...row.worker, qualification: prior.worker.qualification } } : row;
+            }) };
+    }
+    return { snapshot: { config, models, modelDigests: loader.getInputDigests(), catalog,
+            registry: qualifiedRegistry, installations }, drivers };
+}
+async function resolveDirect(ctx, services) {
+    let shell = false;
+    try {
+        const request = parseWorkerCommandArgs(ctx.args.slice(1));
+        shell = request.format === 'shell';
+        const { snapshot, drivers } = await services.load(ctx);
+        const plan = await resolveWorkerInvocation(snapshot, request, drivers, services.now?.());
+        const runnable = plan.invocation?.readiness === 'launchable';
+        if (shell && !runnable)
+            console.error(JSON.stringify({ status: 'blocked', diagnostics: plan.diagnostics }, null, 2));
+        else if (shell && plan.invocation?.transport === 'shell')
+            print(plan.invocation.shellCommand, false);
+        else
+            print(plan, true);
+        return { exitCode: runnable ? 0 : 2 };
+    }
+    catch (error) {
+        const diagnostic = { status: 'blocked', diagnostics: [workerInvocationDiagnostic(error, error instanceof WorkerPolicyError
+                    && error.code === 'OG_ADAPTER_UNQUALIFIED' ? '/parallelism/clis' : '/request')] };
+        if (shell)
+            console.error(JSON.stringify(diagnostic, null, 2));
+        else
+            print(diagnostic, true);
+        return { exitCode: 2 };
+    }
+}
 const TIERS = new Set(['economy', 'standard', 'premium', 'max-quality']);
-const PROVIDERS = new Set([
-    'antigravity', 'claude', 'codex', 'copilot', 'cursor', 'deepseek-harness', 'factory', 'grok-build', 'grokbot', 'hermes',
-    'opencode', 'openclaw', 'openhuman', 'omp', 'pi', 'warp', 'windsurf',
-]);
+const PROVIDERS = new Set(Object.keys(loadProviderModelCapabilities().providers));
 function parseArgs(args) {
     const [subcommand = 'help', ...rest] = args;
     const flags = new Map();
@@ -222,18 +320,75 @@ function replaceFrontmatter(raw, item, tier) {
     }
     return `---\n${frontmatter}\n---\n${match[2]}`;
 }
-async function execute(ctx) {
+const MODELS_HELP = `Usage: aiwg models <subcommand> [options]
+
+Subcommands:
+  list                         List discovered agent and skill model policies
+  audit                        Compile selected policies and report diagnostics
+  resolve                      Resolve artifact policies, or a direct worker invocation
+  validate                     Validate selected artifact policies (not worker configuration)
+  sources                      Show the effective model catalog without network refresh
+  refresh                      Refresh model discovery (may access the network)
+  set-default <TIER>           Write defaults.tier to models.json
+  set --tier <TIER>            Update selected agent/skill frontmatter; requires a selector or --all
+  migrate                      Add canonical role/tier hints to legacy skills
+
+Artifact selectors and options:
+  --agent <name>  --skill <name>  --glob <pattern>  --role <role>
+  --tier <tier>  --framework <name>  --all
+  --provider <provider>         Provider for artifact compilation (default: claude)
+  --model <id>                  Explicit Grok Build model for artifact resolve
+  --target <directory>         Artifact/project root (default: current directory)
+  --scope project|user         set-default destination (default: project)
+  --dry-run                    Preview mutations without writing
+  --json                       Emit JSON
+  --drift                      Include catalog drift for sources/refresh
+  --url <url>                  Remote catalog URL for refresh
+  --help, -h                   Show this reference
+  TIER: economy | standard | premium | max-quality
+
+Direct worker resolution (plans an invocation; does not launch it):
+  aiwg models resolve --role <role> --task <class> --group <group>
+    --brief <file> --workdir <tree> --final-output <file>
+    [--transport shell|mcp] [--format json|shell] [--authorize-premium]
+  --role                       efficiency | coding | reasoning
+  --task                       Task class from defaults.workerSelection.taskClasses
+                               Built-ins: inventory, implementation, architecture, review
+  --group                      Group from parallelism.groups and the role's guidance
+  --brief                      Absolute path to the task brief
+  --workdir                    Absolute path to the worker tree
+  --final-output               Absolute path for the final result
+  --transport                  Must match group execution transport (default: shell)
+  --format                     JSON plan or POSIX shell command (default: json)
+  --json                       Alias for --format json
+  --authorize-premium          Authorize premium for this resolution only
+                               Agents require explicit human confirmation of escalation
+
+Worker groups live in .aiwg/aiwg.config; role guidance lives in project-root models.json.
+Configure both, then run aiwg doctor --probe-workers --qualify.
+See docs/getting-started/worker-dispatch.md for a complete example.`;
+async function execute(ctx, services = { load: loadWorkerInputs }) {
+    if (ctx.args.length === 0 || ctx.args[0] === 'help' || ctx.args.includes('--help') || ctx.args.includes('-h')) {
+        print(MODELS_HELP, false);
+        return { exitCode: 0 };
+    }
+    // Preserve artifact/native resolve when direct-only flags are absent.
+    if (ctx.args[0] === 'resolve' && ctx.args.slice(1).some(arg => /^--(?:task|group|brief|workdir|final-output|transport|format|authorize-premium)(?:=|$)/.test(arg))) {
+        return resolveDirect(ctx, services);
+    }
     const parsed = parseArgs(ctx.args);
+    if (parsed.subcommand === 'resolve') {
+        const supported = new Set(['agent', 'skill', 'glob', 'role', 'tier', 'framework', 'all', 'target', 'provider', 'model', 'json', 'help', 'dry-run']);
+        for (const key of parsed.flags.keys())
+            if (!supported.has(key))
+                return { exitCode: 2, message: `Unsupported models resolve flag: --${key}` };
+    }
     const json = parsed.flags.has('json');
     const dryRun = parsed.flags.has('dry-run') || ctx.dryRun === true;
     const target = path.resolve(flagString(parsed, 'target') ?? ctx.cwd);
     const provider = flagString(parsed, 'provider') ?? 'claude';
     if (!PROVIDERS.has(provider))
         return { exitCode: 2, message: `Unknown provider: ${provider}` };
-    if (parsed.subcommand === 'help' || parsed.flags.has('help')) {
-        print('Usage: aiwg models <audit|list|resolve|sources|refresh|set-default|set|validate|migrate> [selectors] [--provider P] [--dry-run] [--json]', json);
-        return { exitCode: 0 };
-    }
     if (parsed.subcommand === 'sources' || parsed.subcommand === 'refresh') {
         const { diffModelCatalog } = await import('../../models/model-discovery.js');
         const catalog = await effectiveCatalog(ctx, target, parsed.subcommand === 'refresh', parsed, provider);
@@ -378,6 +533,10 @@ export const modelsHandler = {
     description: 'Audit, resolve, validate, and safely update model policy',
     category: 'catalog',
     aliases: [],
+    help: async () => ({ exitCode: 0, message: MODELS_HELP, rawOutput: true }),
     execute,
 };
+export function createModelsHandler(services) {
+    return { ...modelsHandler, execute: ctx => execute(ctx, services) };
+}
 //# sourceMappingURL=models.js.map

package/dist/src/cli/handlers/ralph-launcher.js

@@ -296,6 +296,8 @@ export function saveLauncherRegistry(projectRoot, registry) {
  * Check if a process is still running
  */
 export function isProcessAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
     try {
         process.kill(pid, 0);
         return true;

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

@@ -336,6 +336,9 @@ export class RalphStatusHandler {
     category = 'ralph';
     aliases = ['agent-loop-status', 'ralph-status'];
     async execute(ctx) {
+        if (ctx.args.includes('--workers')) {
+            return createScriptRunner(ctx.frameworkRoot).run('tools/ralph-external/index.mjs', ['--status', ...ctx.args]);
+        }
         const showAll = ctx.args.includes('--all') || ctx.args.includes('-a');
         const statuses = getLoopStatuses(process.cwd());
         if (statuses.length === 0) {