@aiwg/cli 2026.10.3 → 2026.10.5

package/dist/src/models/provider-policy.js

@@ -64,6 +64,7 @@ export const WorkerAdapterSchema = z.custom().superRefine((value, context) => {
     }
 });
 const CapabilityEntrySchema = z.object({
+    sessionEnvAllowlist: z.array(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/)).optional(),
     agent: OutcomeSchema,
     skill: OutcomeSchema,
     globalChild: OutcomeSchema,
@@ -497,12 +498,68 @@ export function requiredWorkerControls(context) {
 }
 /** The same sandbox requirement governs inspection, resolution and rendering. */
 export function requiresWorkerExternalBoundary(adapter, selection) {
+    if (hasOperatorWorkerNativeRenderer(adapter) && selection.permissions?.sandbox !== 'external')
+        return false;
     const providers = [adapter.id, adapter.provider].map(normalizeProviderDefinitionId);
     return requiredWorkerControls(selection).includes('sandbox')
         && (providers.some(provider => provider && ['claude', 'muse', 'hermes'].includes(provider))
             || adapter.invocationProfiles?.[selection.profile]?.controls.sandbox?.support === 'external'
             || selection.permissions?.sandbox === 'external');
 }
+/** Explicit local operator approval for the direct CLI baseline (decision 17).
+ * This is not backend attestation or a live negative-fixture result. */
+export const WORKER_OPERATOR_APPROVAL = 'aiwg doctor --probe-workers --qualify';
+export function isOperatorQualifiedWorkerAdapter(adapter) {
+    return adapter.qualification.status === 'qualified'
+        && adapter.qualification.evidenceRef === WORKER_OPERATOR_APPROVAL;
+}
+/** Only this bundled renderer has an independently checked native direct baseline. */
+export function hasOperatorWorkerNativeRenderer(adapter) {
+    return isOperatorQualifiedWorkerAdapter(adapter) && adapter.provider === 'codex'
+        && adapter.invocation.kind === 'process';
+}
+/** Check the actual argv before granting the direct renderer exception. */
+export function assertOperatorWorkerNativeArgv(adapter, argv, selected, permissions) {
+    if (!hasOperatorWorkerNativeRenderer(adapter))
+        return;
+    const args = argv.slice(1);
+    const requirePair = (flag, value) => {
+        if (args.filter(token => token === flag).length !== 1 || args[args.indexOf(flag) + 1] !== value) {
+            throw new Error(`Requested native worker control is absent or ambiguous: ${flag}`);
+        }
+    };
+    const sandbox = permissions?.sandbox ?? 'workspace-write';
+    if (!['read-only', 'workspace-write'].includes(sandbox))
+        throw new Error('Requested sandbox has no verified native renderer');
+    requirePair('-m', selected.model);
+    requirePair('-s', sandbox);
+    for (const [name, value] of [['model_reasoning_effort', selected.effort.value], ['approval_policy', permissions?.approval ?? 'never']]) {
+        const overrides = args.flatMap((token, index) => token === '-c' ? [args[index + 1]] : [])
+            .filter(token => token?.split('=')[0] === name);
+        if (value === null || overrides.length !== 1 || overrides[0] !== `${name}=${JSON.stringify(value)}`) {
+            throw new Error(`Requested native worker control is absent or ambiguous: ${name}`);
+        }
+    }
+    // Permit only the bounded native command grammar. Alternate/combined flags,
+    // profiles and additional config overrides must not undo the checked pairs.
+    if (args[0] !== '--no-daemon' || args[1] !== 'exec' || !args.includes('--ignore-user-config')) {
+        throw new Error('Native worker controls could be overridden');
+    }
+    for (let index = 2; index < args.length; index++) {
+        const flag = args[index];
+        if (['--ignore-user-config', '--skip-git-repo-check', '--json'].includes(flag))
+            continue;
+        if (flag === '-' && index === args.length - 1)
+            continue;
+        if (!['-m', '-s', '-c', '-C', '-o'].includes(flag) || index + 1 >= args.length) {
+            throw new Error('Native worker controls could be overridden');
+        }
+        const value = args[++index];
+        if (flag === '-c' && !['model_reasoning_effort', 'approval_policy'].includes(value.split('=')[0])) {
+            throw new Error('Native worker controls could be overridden');
+        }
+    }
+}
 /** Inspect declared controls before installation evidence can be produced. This
  * does not authorize invocation; consumers must use qualifyWorkerInvocationProfile. */
 export function inspectWorkerInvocationProfile(adapter, selection) {
@@ -517,6 +574,23 @@ export function inspectWorkerInvocationProfile(adapter, selection) {
     if (workerVersionRangeMismatch(selection.cliVersion, [adapter.supportedVersions, profile.supportedVersions]) !== null) {
         throw new Error('Worker CLI version is outside qualified profile');
     }
+    // The direct CLI baseline trusts the installed driver's bounded renderer.
+    // Explicit extra controls still require the existing qualified mappings.
+    if (hasOperatorWorkerNativeRenderer(adapter) && profile.transport === 'shell') {
+        if (selection.permissions?.sandbox && !['read-only', 'workspace-write'].includes(selection.permissions.sandbox)) {
+            throw new Error('Requested sandbox has no verified native renderer');
+        }
+        if (selection.permissions?.sandbox === 'external' && (!selection.boundary
+            || !['os', 'executor'].includes(selection.boundary.kind) || !selection.boundary.controls.includes('sandbox'))) {
+            throw new Error('Requested external sandbox requires an enforcing boundary');
+        }
+        for (const name of selection.requiredControls ?? []) {
+            if (!['native', 'external'].includes(profile.controls[name]?.support)) {
+                throw new Error(`Required worker control is unqualified: ${name}`);
+            }
+        }
+        return profile;
+    }
     const requiredControls = requiredWorkerControls(selection);
     if (requiresWorkerExternalBoundary(adapter, selection)
         && (!selection.boundary || !['os', 'executor'].includes(selection.boundary.kind)
@@ -546,6 +620,10 @@ export function inspectWorkerInvocationProfile(adapter, selection) {
  * installation scope, including this boundary, against the recorded digest. */
 export function qualifyWorkerInvocationProfile(adapter, selection) {
     const profile = inspectWorkerInvocationProfile(adapter, selection);
+    if (isOperatorQualifiedWorkerAdapter(adapter) && selection.policy?.guards?.denySelfDelegation !== false
+        && !adapter.capabilities.nestedAgentsControllable) {
+        throw new Error('Required worker control is unqualified: children');
+    }
     if (requiresWorkerExternalBoundary(adapter, selection) && !profile.installationQualification) {
         throw new Error('Required worker control sandbox needs matching installation qualification for its external boundary');
     }
@@ -817,7 +895,7 @@ export function validateWorkerPolicyRoute(input) {
     const guards = input.policy.guards ?? DEFAULT_WORKER_SELECTION.guards;
     const guidance = input.policy.roleGuidance?.[input.role];
     if (observation.qualification.status !== 'qualified' || !observation.qualification.roles.includes(input.role))
-        deny('OG_ADAPTER_UNQUALIFIED', '/worker/qualification', 'Role lacks qualified evidence');
+        deny('OG_ADAPTER_UNQUALIFIED', '/worker/qualification', 'Role lacks qualified evidence. Run aiwg doctor --probe-workers --qualify.');
     if (!guidance)
         deny('OG_CONFIG_REFERENCE', `/defaults/workerSelection/roleGuidance/${input.role}`, 'Role guidance is unavailable');
     const substitution = input.substitution?.model === input.selectedModel
@@ -855,13 +933,22 @@ export function validateWorkerPolicyRoute(input) {
     else {
         const effort = observation.efforts.find(e => e.id === input.effort);
         if (observation.effortSupport !== 'explicit' || !effort || !(input.effort === 'none' ? guidance?.initialEffort === 'none' && guidance.effortLadder.length === 0 : guidance?.effortLadder.includes(input.effort)) || isWorkerEffortDenied(input.effort, input.policy) || (guards.denySelfDelegation !== false && effort.selfDelegates !== false))
-            deny('OG_EFFORT_DENIED', '/worker/efforts', 'Unsupported, denied or self-delegating effort');
+            deny('OG_EFFORT_DENIED', '/worker/efforts', 'Unsupported, denied or self-delegating effort. Check catalog effort evidence and models.json defaults.workerSelection.roleGuidance, guards.deniedEfforts and guards.denySelfDelegation.');
     }
     const { data, unknownDataClass } = workerRouteDataPolicy(input.policy, input.dataClass);
     if (unknownDataClass)
         deny('OG_DATA_POLICY', '/defaults/workerSelection/dataClasses', 'Unknown data class');
-    if (isWorkerDataUseDenied(observation.dataUse, data))
-        deny('OG_DATA_POLICY', '/worker/dataUse', 'Execution path data facts do not satisfy policy');
+    if (isWorkerDataUseDenied(observation.dataUse, data)) {
+        const facts = observation.dataUse;
+        const keys = [
+            ...((facts.processing === 'unknown' || facts.productImprovement === null
+                || data.maxRetentionDays !== undefined && facts.retentionDays === null) && data.allowUnknown !== true ? ['allowUnknown'] : []),
+            ...(facts.processing !== 'unknown' && !data.allowedProcessing?.includes(facts.processing) ? ['allowedProcessing'] : []),
+            ...(facts.productImprovement === true && data.allowProductImprovement !== true ? ['allowProductImprovement'] : []),
+            ...(data.maxRetentionDays !== undefined && facts.retentionDays !== null && facts.retentionDays > data.maxRetentionDays ? ['maxRetentionDays'] : []),
+        ];
+        deny('OG_DATA_POLICY', '/worker/dataUse', `Execution path data facts do not satisfy policy. Review models.json ${keys.map(key => `defaults.workerSelection.dataPolicy.${key}`).join(', ')}${input.dataClass ? ` and defaults.workerSelection.dataClasses.${input.dataClass}` : ''}; unknown facts remain unknown.`);
+    }
     const now = (input.now ?? new Date()).getTime();
     if (observation.retiredAt != null && Date.parse(observation.retiredAt) <= now
         || observation.sunsetAt && Date.parse(observation.sunsetAt) <= now) {
@@ -873,7 +960,14 @@ export function validateWorkerPolicyRoute(input) {
         diagnostics.push({ code: 'OG_ADAPTER_UNQUALIFIED', pointer: '/worker/observedAt', blocking: false, message: 'Model observation exceeds the freshness warning threshold' });
     }
     if (input.context && !workerContextHeadroom(input.context, observation).fits) {
-        deny('OG_MODEL_UNAPPROVED', '/worker/contextTokens', 'Bounded context and output do not fit qualified limits');
+        const missing = [observation.contextTokens === null ? 'contextTokens' : ''].filter(Boolean);
+        deny('OG_MODEL_UNAPPROVED', '/worker/contextTokens', missing.length
+            ? `Bounded context and output cannot be checked: catalog does not report a qualified ${missing.join(', ')} limit. Refresh discovery with reported limits; operator approval does not invent limits.`
+            : 'Bounded context and output do not fit qualified limits; reduce the request context or reserved output.');
+    }
+    if (input.context && observation.contextTokens !== null && observation.maxOutputTokens === null) {
+        diagnostics.push({ code: 'OG_MODEL_UNAPPROVED', pointer: '/worker/maxOutputTokens', blocking: false,
+            message: 'Output limit is unreported; only the context window was checked.' });
     }
     return diagnostics;
 }
@@ -883,8 +977,8 @@ export function workerContextHeadroom(estimate, observation) {
     const total = terms.reduce((sum, value) => sum + value, 0);
     const fits = Boolean(estimate.estimator.trim()) && terms.every(value => Number.isSafeInteger(value) && value >= 0)
         && (estimate.safetyMargin === undefined || Number.isSafeInteger(estimate.safetyMargin) && estimate.safetyMargin >= 0)
-        && Number.isSafeInteger(total) && observation.contextTokens !== null && observation.maxOutputTokens !== null
-        && total <= observation.contextTokens && estimate.reservedOutput <= observation.maxOutputTokens;
+        && Number.isSafeInteger(total) && observation.contextTokens !== null
+        && total <= observation.contextTokens && (observation.maxOutputTokens === null || estimate.reservedOutput <= observation.maxOutputTokens);
     return { ...estimate, safetyMargin, total, qualifiedContextTokens: observation.contextTokens,
         qualifiedMaxOutputTokens: observation.maxOutputTokens, fits };
 }

package/dist/src/models/qualification-digest.d.mts

@@ -0,0 +1,2 @@
+/** Canonical JSON binding with a sha256: prefix; shared by TS and runtime ESM. */
+export function qualificationDigest(value: unknown): string;

package/dist/src/models/resolver.js

@@ -7,8 +7,8 @@
  */
 import { ConfigLoader } from './config-loader.js';
 import { WORKER_DISPATCH_ENABLE_COMMAND, WORKER_DISPATCH_READINESS_COMMAND } from './worker-dispatch-offer.js';
-import { resolveWorkerGroupInstallation, resolveParallelism, validateWorkerGroupReferences, validateWorkerBudgetEnforcement, workerActivationDigests, workerConfigDigest, } from '../config/aiwg-config.js';
-import { qualifyWorkerInvocationProfile, validateWorkerPolicyRoute, validateWorkerModelObservation, hasSelectionRelevantConflicts, workerContextHeadroom, workerModelKey, isCanonicalWorkerModelKey, WorkerSelectionPolicySchema, validateWorkerCatalogDiscovery, } from './provider-policy.js';
+import { resolveWorkerGroupInstallation, resolveParallelism, validateWorkerGroupQualifications, validateWorkerGroupReferences, validateWorkerBudgetEnforcement, workerActivationDigests, workerConfigDigest, } from '../config/aiwg-config.js';
+import { qualifyWorkerInvocationProfile, validateWorkerPolicyRoute, validateWorkerModelObservation, hasOperatorWorkerNativeRenderer, hasSelectionRelevantConflicts, workerContextHeadroom, workerModelKey, isCanonicalWorkerModelKey, WorkerSelectionPolicySchema, validateWorkerCatalogDiscovery, } from './provider-policy.js';
 import { MODEL_WRAPPERS } from './provider-models.js';
 import { routeModelTier } from './router.js';
 /**
@@ -344,8 +344,9 @@ export function resolveWorkerPlan(snapshot, request) {
                 ? observed.qualification.roles.filter(role => policy.roleGuidance?.[role]?.groups.includes(groupId)) : [];
         }
     }
-    for (const message of validateWorkerGroupReferences(parallelism, policy, qualifiedRoles))
-        block('OG_ADAPTER_UNQUALIFIED', '/parallelism/groups', message);
+    plan.diagnostics.push(...validateWorkerGroupQualifications(parallelism, qualifiedRoles).map(diagnostic => ({
+        ...diagnostic, message: `${diagnostic.message}. Run aiwg doctor --probe-workers --qualify.`,
+    })));
     const taskRole = request.taskClass ? policy.taskClasses?.[request.taskClass] : undefined;
     const role = request.role ?? taskRole;
     plan.role = role ?? null;
@@ -397,7 +398,7 @@ export function resolveWorkerPlan(snapshot, request) {
                 if (pinMismatch && !substitution)
                     deny('OG_PIN_MISMATCH', pointer, 'Exact request or wrapper pin requires explicit substitution');
                 if (!observation || !binding || !row?.llmProvider || !row.apiModelId)
-                    deny('OG_ADAPTER_UNQUALIFIED', pointer, 'Missing exact model, inference provider, observation or current installation evidence');
+                    deny('OG_ADAPTER_UNQUALIFIED', pointer, 'Missing exact model, inference provider, observation or current installation evidence. Run aiwg doctor --probe-workers --qualify.');
                 if (observation && binding && row?.llmProvider && row.apiModelId) {
                     const shapeErrors = validateWorkerModelObservation(observation);
                     if (shapeErrors.length) {
@@ -424,12 +425,13 @@ export function resolveWorkerPlan(snapshot, request) {
                         const configuredServer = parallelism.clis?.[member.cli]?.mcpServerRef;
                         if (transport === 'mcp' && configuredServer && configuredServer !== binding.mcp?.serverRef)
                             throw new Error('Configured MCP server changed');
-                        if (adapter.capabilities.modelPin === 'unsupported' || !adapter.capabilities.nativeFallbackControllable
-                            || policy.guards?.denySelfDelegation !== false && !adapter.capabilities.nestedAgentsControllable)
-                            throw new Error('Exact model or child/fallback control is unqualified');
+                        if (!hasOperatorWorkerNativeRenderer(adapter) && (adapter.capabilities.modelPin === 'unsupported' || !adapter.capabilities.nativeFallbackControllable))
+                            throw new Error('Exact model or fallback control is unqualified; qualify an adapter with these controls');
+                        if (policy.guards?.denySelfDelegation !== false && !adapter.capabilities.nestedAgentsControllable)
+                            throw new Error('Child-agent control is unqualified. Review models.json defaults.workerSelection.guards.denySelfDelegation; false permits uncontrolled child agents without qualifying their behavior.');
                         if (binding.identityEvidence === 'backend-attested' && adapter.capabilities.modelPin !== 'observed')
                             throw new Error('Requested-only mapping cannot attest backend identity');
-                        if (group.execution?.sandbox && !adapter.capabilities.sandboxModes.includes(group.execution.sandbox))
+                        if (!hasOperatorWorkerNativeRenderer(adapter) && group.execution?.sandbox && !adapter.capabilities.sandboxModes.includes(group.execution.sandbox))
                             throw new Error('Requested sandbox mode is unqualified');
                         qualifyWorkerInvocationProfile(adapter, { profile: binding.profile, transport, cliVersion: binding.cliVersion,
                             policy, permissions, effort, boundary: binding.boundary,
@@ -460,7 +462,7 @@ export function resolveWorkerPlan(snapshot, request) {
                     const authority = routeModelTier({ ...request.authority, deterministic: false, routine: false,
                         defaultTier: guidance.tier === 'economy' ? 1 : 2, requestedPremium: premium || request.authority?.requestedPremium });
                     if (authority.requiresConfirmation)
-                        deny('OG_MODEL_UNAPPROVED', '/request/authority', authority.rationale.join('; '));
+                        deny('OG_MODEL_UNAPPROVED', '/request/authority', `${authority.rationale.join('; ')}; agents may pass --authorize-premium only after the human explicitly confirmed the premium escalation (escalation-discipline rule)`);
                     const installation = parallelism.clis?.[member.cli];
                     const caps = [parallelism.max_parallel_subagents, group.maxParallel, parallelism.admission?.groupCaps?.[groupId],
                         parallelism.admission?.memberCaps?.[`${groupId}/${member.id}`], parallelism.admission?.cliCaps?.[member.cli],

package/dist/src/models/worker-direct-readiness.js

@@ -47,8 +47,8 @@
  * is a binding the public config validator also accepts, and vice versa.
  *
  * The shipped direct profiles are declarations, not live qualification: no
- * finding ever calls a profile "qualified". Profiles stay unqualified until
- * an authenticated smoke run (tracker #3005), and an installed, in-range CLI
+ * finding ever calls a profile "qualified". Explicit operator approval uses `aiwg doctor --probe-workers --qualify`;
+ * a probe alone does not qualify a profile, and an installed, in-range CLI
  * can still be refused by the resolver — the dispatch finding says so
  * plainly with the resolver's own reason.
  *
@@ -61,7 +61,7 @@ import { isAbsolute, resolve as resolvePath } from 'node:path';
 import { boundedVersionProbe, normalizeWorkerVersionBanner, workerVersionProbeDefaults, workerVersionProbeEnvironment, workerVersionRangeMismatch, } from './worker-installation.mjs';
 import { resolveWorkerGroupInstallation } from '../config/aiwg-config.js';
 import { resolveWorkerPlan } from './resolver.js';
-const SMOKE_NOTE = 'Profiles are unqualified until an authenticated smoke run (see #3005).';
+const SMOKE_NOTE = 'A version probe alone leaves profiles unqualified. To record direct CLI operator approval, run aiwg doctor --probe-workers --qualify; a version probe is not an authenticated smoke run (see #3005).';
 function truncateBanner(banner, limit = 200) {
     const singleLine = banner.replace(/[\r\n]+/g, '\\n');
     return singleLine.length > limit ? `${singleLine.slice(0, limit)}…` : singleLine;
@@ -166,13 +166,13 @@ function describeConfigContext(members) {
  * `parallelism.clis` entries plus any cli id referenced only implicitly by a
  * group member (canonical default binding, no explicit installation entry).
  */
-function allConfiguredCliIds(parallelism) {
+function allConfiguredCliIds(parallelism, cli) {
     const ids = new Set(Object.keys(parallelism.clis ?? {}));
     for (const group of Object.values(parallelism.groups ?? {})) {
         for (const member of group?.members ?? [])
             ids.add(member.cli);
     }
-    return [...ids].sort();
+    return [...ids].filter(id => cli === undefined || id === cli).sort();
 }
 /**
  * A cli is "required" only when an enabled group member referencing it also
@@ -202,12 +202,6 @@ function advisoryStatus(status, required) {
     return required || status !== 'error' ? status : 'warn';
 }
 const offlineDirectContext = () => ({ estimator: 'doctor-offline-direct-context-v1', briefTokens: 0, inputTokens: 0, toolOutputAllowance: 0, reservedOutput: 0 });
-function formatDiagnostics(diagnostics) {
-    const seen = new Map();
-    for (const diagnostic of diagnostics)
-        seen.set(`${diagnostic.code}:${diagnostic.pointer}:${diagnostic.message}`, diagnostic);
-    return [...seen.values()].map(diagnostic => `${diagnostic.code} ${diagnostic.pointer}: ${diagnostic.message}`).join('; ');
-}
 /**
  * Dispatch eligibility from the actual offline dispatch resolver
  * (`resolveWorkerPlan`): called once per role for every group member
@@ -222,7 +216,8 @@ function resolveEligibilityFromDispatchResolver(resolverSnapshot, registry, cli,
         config: resolverSnapshot.config, models: resolverSnapshot.models, modelDigests: resolverSnapshot.modelDigests,
         catalog: resolverSnapshot.catalog, registry, installations: {},
     };
-    const refusals = [];
+    const diagnostics = new Map();
+    const uncovered = [];
     for (const ref of refs) {
         if (!ref.enabled)
             continue;
@@ -239,23 +234,48 @@ function resolveEligibilityFromDispatchResolver(resolverSnapshot, registry, cli,
                 break;
             }
             const exclusion = plan.exclusions.find(matches);
-            seen.push(...(exclusion?.diagnostics ?? plan.diagnostics));
+            for (const diagnostic of exclusion?.diagnostics ?? plan.diagnostics) {
+                // Only an exact member pointer is generalized; other config pointers
+                // remain distinct even when their diagnostic text happens to match.
+                const memberPointer = `/parallelism/groups/${ref.groupId}/members/${ref.memberId}`;
+                const pointer = diagnostic.pointer === memberPointer || diagnostic.pointer.startsWith(`${memberPointer}/`)
+                    ? `/parallelism/groups/${ref.groupId}/members${diagnostic.pointer.slice(memberPointer.length)}`
+                    : diagnostic.pointer;
+                seen.push({ ...diagnostic, pointer, members: [`${ref.groupId}/${ref.memberId}`],
+                    roles: diagnostic.roles ?? [role] });
+            }
         }
         if (eligibleHere) {
             return { eligibility: 'eligible',
                 detail: `Dispatch resolver accepts cli '${cli}' for group '${ref.groupId}' member '${ref.memberId}'. `
                     + `Dispatch eligibility: eligible. ${SMOKE_NOTE}` };
         }
-        const reasons = formatDiagnostics(seen);
-        refusals.push(`group '${ref.groupId}' member '${ref.memberId}'${reasons ? `: ${reasons}` : ' (no qualified route)'}`);
+        if (!seen.length)
+            uncovered.push(`${ref.groupId}/${ref.memberId}`);
+        for (const diagnostic of seen) {
+            const key = JSON.stringify([diagnostic.code, diagnostic.pointer, diagnostic.message,
+                diagnostic.blocking, diagnostic.origins]);
+            const shared = diagnostics.get(key);
+            if (shared) {
+                shared.members = [...new Set([...shared.members, ...diagnostic.members])];
+                shared.roles = [...new Set([...shared.roles, ...diagnostic.roles])];
+            }
+            else
+                diagnostics.set(key, diagnostic);
+        }
     }
-    if (!refusals.length) {
+    if (!diagnostics.size && !uncovered.length) {
         return { eligibility: 'blocked',
             detail: `Dispatch resolver has no enabled group member to evaluate for cli '${cli}'. `
                 + `Dispatch eligibility: blocked. ${SMOKE_NOTE}` };
     }
-    return { eligibility: 'blocked',
-        detail: `Dispatch resolver refuses cli '${cli}': ${refusals.join('; ')}. `
+    const distinct = [...diagnostics.values()];
+    const reasons = distinct.map(diagnostic => `${diagnostic.code} ${diagnostic.pointer}: ${diagnostic.message}`
+        + ` [roles: ${diagnostic.roles.join(', ')}; members: ${diagnostic.members.join(', ')}]`);
+    if (uncovered.length)
+        reasons.push(`No qualified route [members: ${uncovered.join(', ')}]`);
+    return { eligibility: 'blocked', diagnostics: distinct,
+        detail: `Dispatch resolver refuses cli '${cli}': ${reasons.join('; ')}. `
             + `Dispatch eligibility: blocked. ${SMOKE_NOTE}` };
 }
 /**
@@ -277,7 +297,7 @@ function resolveEligibilityFromBindingOnly(parallelism, registry, cli, installRe
         const reason = error instanceof Error ? error.message : String(error);
         const readyNote = installReady
             ? ' The CLI is installed with an in-range version, but dispatch stays refused for the reason above; '
-                + 'an authenticated smoke run (see #3005) alone does not satisfy the resolver gates.'
+                + `an authenticated smoke run (see #3005) alone does not satisfy the resolver gates. ${SMOKE_NOTE}`
             : ` ${SMOKE_NOTE}`;
         return { eligibility: 'blocked',
             detail: `Resolver refuses cli '${cli}': ${reason}. Dispatch eligibility: blocked.${readyNote}` };
@@ -300,7 +320,7 @@ export async function diagnoseDirectWorkerReadiness(input) {
     const { parallelism, registry, probe, announce, timeoutMs = workerVersionProbeDefaults.timeoutMs, probeCwd = tmpdir(), configFile = '.aiwg/aiwg.config', projectRoot = process.cwd(), resolverSnapshot } = input;
     const report = {
         enabled: parallelism.worker_dispatch === true,
-        workersConfigured: allConfiguredCliIds(parallelism).length > 0,
+        workersConfigured: allConfiguredCliIds(parallelism, input.cli).length > 0,
         ready: true,
         findings: [],
     };
@@ -315,7 +335,7 @@ export async function diagnoseDirectWorkerReadiness(input) {
             members: [] });
         return report;
     }
-    const cliIds = allConfiguredCliIds(parallelism);
+    const cliIds = allConfiguredCliIds(parallelism, input.cli);
     if (!cliIds.length) {
         // No workers configured: no findings at all so doctor stays silent.
         return report;
@@ -325,11 +345,11 @@ export async function diagnoseDirectWorkerReadiness(input) {
         if (finding.status === 'error' || finding.status === 'warn')
             report.ready = false;
     };
-    const pushDispatch = (cli, profile, status, code, eligibility, detail, configKey, members, nextAction) => {
+    const pushDispatch = (cli, profile, status, code, eligibility, detail, configKey, members, nextAction, diagnostics) => {
         report.findings.push({ cli, kind: 'dispatch', profile, executable: null, installedVersion: null,
             status, code, message: `${detail} (config ${configFile} key ${configKey}; ${describeConfigContext(members)})`,
             nextAction, configFile, configKey,
-            readiness: null, eligibility, eligibilityDetail: detail, members });
+            readiness: null, eligibility, eligibilityDetail: detail, members, ...(diagnostics ? { diagnostics } : {}) });
     };
     await Promise.all(cliIds.map(async (cli) => {
         const configured = parallelism.clis?.[cli];
@@ -344,8 +364,8 @@ export async function diagnoseDirectWorkerReadiness(input) {
                 message: `Dispatch is disabled for cli '${cli}' (config ${configFile} key ${configKey}/enabled); the version probe was skipped. Installation readiness: skipped. (${describeConfigContext(members)})`,
                 nextAction: 'enable-cli-to-onboard',
                 configFile, configKey, readiness: 'skipped', members });
-            const { eligibility, detail } = checkDispatchEligibility(parallelism, registry, cli, false, resolverSnapshot, refs);
-            pushDispatch(cli, configured.invocationProfile ?? null, 'info', 'WORKER_DIRECT_DISPATCH_BLOCKED', eligibility, detail, configKey, members, 'enable-cli-to-onboard');
+            const { eligibility, detail, diagnostics } = checkDispatchEligibility(parallelism, registry, cli, false, resolverSnapshot, refs);
+            pushDispatch(cli, configured.invocationProfile ?? null, 'info', 'WORKER_DIRECT_DISPATCH_BLOCKED', eligibility, detail, configKey, members, 'enable-cli-to-onboard', diagnostics);
             return;
         }
         const resolved = resolveDirectBinding(registry, configured?.adapter, cli);
@@ -355,8 +375,8 @@ export async function diagnoseDirectWorkerReadiness(input) {
                 message: `${resolved.error} (config ${configFile} key ${configKey}/adapter); the profile cannot be onboarded. Installation readiness: not-ready. (${describeConfigContext(members)})`,
                 nextAction: 'review-worker-configuration',
                 configFile, configKey: `${configKey}/adapter`, readiness: 'not-ready', members });
-            const { eligibility, detail } = checkDispatchEligibility(parallelism, registry, cli, false, resolverSnapshot, refs);
-            pushDispatch(cli, configured?.invocationProfile ?? null, 'warn', 'WORKER_DIRECT_DISPATCH_BLOCKED', eligibility, detail, configKey, members, 'review-worker-configuration');
+            const { eligibility, detail, diagnostics } = checkDispatchEligibility(parallelism, registry, cli, false, resolverSnapshot, refs);
+            pushDispatch(cli, configured?.invocationProfile ?? null, 'warn', 'WORKER_DIRECT_DISPATCH_BLOCKED', eligibility, detail, configKey, members, 'review-worker-configuration', diagnostics);
             return;
         }
         const { adapter, adapterRef } = resolved;
@@ -366,8 +386,8 @@ export async function diagnoseDirectWorkerReadiness(input) {
                 message: `Cli '${cli}' binds '${adapterRef}' (config ${configFile} key ${configKey}/adapter), which uses an HTTP adapter; there is no CLI version probe — check endpoint health instead. Installation readiness: skipped. (${describeConfigContext(members)})`,
                 nextAction: 'check-endpoint-health',
                 configFile, configKey, readiness: 'skipped', members });
-            const { eligibility, detail } = checkDispatchEligibility(parallelism, registry, cli, false, resolverSnapshot, refs);
-            pushDispatch(cli, null, eligibility === 'eligible' ? 'ok' : 'warn', eligibility === 'eligible' ? 'WORKER_DIRECT_DISPATCH_ELIGIBLE' : 'WORKER_DIRECT_DISPATCH_BLOCKED', eligibility, detail, configKey, members, eligibility === 'eligible' ? 'check-endpoint-health' : 'review-worker-configuration');
+            const { eligibility, detail, diagnostics } = checkDispatchEligibility(parallelism, registry, cli, false, resolverSnapshot, refs);
+            pushDispatch(cli, null, eligibility === 'eligible' ? 'ok' : 'warn', eligibility === 'eligible' ? 'WORKER_DIRECT_DISPATCH_ELIGIBLE' : 'WORKER_DIRECT_DISPATCH_BLOCKED', eligibility, detail, configKey, members, eligibility === 'eligible' ? 'check-endpoint-health' : 'review-worker-configuration', diagnostics);
             return;
         }
         const profileIds = Object.keys(adapter.invocationProfiles ?? {});
@@ -382,8 +402,8 @@ export async function diagnoseDirectWorkerReadiness(input) {
                     : `Cli '${cli}' binding '${adapterRef}' has no single direct profile to check (config ${configFile} key ${configKey}); configure invocationProfile explicitly. Installation readiness: not-ready. (${describeConfigContext(members)})`,
                 nextAction: 'review-worker-configuration',
                 configFile, configKey, readiness: 'not-ready', members });
-            const { eligibility, detail } = checkDispatchEligibility(parallelism, registry, cli, false, resolverSnapshot, refs);
-            pushDispatch(cli, configured?.invocationProfile ?? null, 'warn', 'WORKER_DIRECT_DISPATCH_BLOCKED', eligibility, detail, configKey, members, 'review-worker-configuration');
+            const { eligibility, detail, diagnostics } = checkDispatchEligibility(parallelism, registry, cli, false, resolverSnapshot, refs);
+            pushDispatch(cli, configured?.invocationProfile ?? null, 'warn', 'WORKER_DIRECT_DISPATCH_BLOCKED', eligibility, detail, configKey, members, 'review-worker-configuration', diagnostics);
             return;
         }
         const profile = adapter.invocationProfiles[profileRef];
@@ -394,8 +414,8 @@ export async function diagnoseDirectWorkerReadiness(input) {
                 message: `Cli '${cli}' binds '${adapterRef}' profile '${profileRef}' (config ${configFile} key ${configKey}); version probe not run — no subprocess was started. Installation readiness: unprobed. Rerun with probes to check install/version. (${describeConfigContext(members)})`,
                 nextAction: 'rerun-with-probe-workers',
                 configFile, configKey, readiness: 'unprobed', members });
-            const { eligibility, detail } = checkDispatchEligibility(parallelism, registry, cli, false, resolverSnapshot, refs);
-            pushDispatch(cli, profileRef, eligibility === 'eligible' ? 'ok' : 'warn', eligibility === 'eligible' ? 'WORKER_DIRECT_DISPATCH_ELIGIBLE' : 'WORKER_DIRECT_DISPATCH_BLOCKED', eligibility, detail, configKey, members, eligibility === 'eligible' ? 'rerun-with-probe-workers' : 'review-worker-configuration');
+            const { eligibility, detail, diagnostics } = checkDispatchEligibility(parallelism, registry, cli, false, resolverSnapshot, refs);
+            pushDispatch(cli, profileRef, eligibility === 'eligible' ? 'ok' : 'warn', eligibility === 'eligible' ? 'WORKER_DIRECT_DISPATCH_ELIGIBLE' : 'WORKER_DIRECT_DISPATCH_BLOCKED', eligibility, detail, configKey, members, eligibility === 'eligible' ? 'rerun-with-probe-workers' : 'review-worker-configuration', diagnostics);
             return;
         }
         announce?.(cli, executable, adapter.invocation.versionArgv);
@@ -416,8 +436,8 @@ export async function diagnoseDirectWorkerReadiness(input) {
                     : `Version probe for cli '${cli}' ('${executable}', config ${configFile} key ${configKey}) failed; retry once, then check PATH and execute permission. Installation readiness: not-ready. (${describeConfigContext(members)})`,
                 nextAction: notInstalled ? 'install-cli' : 'retry-version-probe',
                 configFile, configKey, readiness: 'not-ready', members });
-            const { eligibility, detail } = checkDispatchEligibility(parallelism, registry, cli, false, resolverSnapshot, refs);
-            pushDispatch(cli, profileRef, 'warn', 'WORKER_DIRECT_DISPATCH_BLOCKED', eligibility, detail, configKey, members, notInstalled ? 'install-cli' : 'retry-version-probe');
+            const { eligibility, detail, diagnostics } = checkDispatchEligibility(parallelism, registry, cli, false, resolverSnapshot, refs);
+            pushDispatch(cli, profileRef, 'warn', 'WORKER_DIRECT_DISPATCH_BLOCKED', eligibility, detail, configKey, members, notInstalled ? 'install-cli' : 'retry-version-probe', diagnostics);
             return;
         }
         const rawBanner = outcome.rawBanner.trim();
@@ -431,8 +451,8 @@ export async function diagnoseDirectWorkerReadiness(input) {
                 message: `CLI '${executable}' banner ${JSON.stringify(truncateBanner(rawBanner))} does not match the registered version pattern (config ${configFile} key ${configKey}); the install is unexpected — reinstall a supported release. Installation readiness: not-ready. (${describeConfigContext(members)})`,
                 nextAction: 'reinstall-supported-cli',
                 configFile, configKey, readiness: 'not-ready', members });
-            const { eligibility, detail } = checkDispatchEligibility(parallelism, registry, cli, false, resolverSnapshot, refs);
-            pushDispatch(cli, profileRef, 'warn', 'WORKER_DIRECT_DISPATCH_BLOCKED', eligibility, detail, configKey, members, 'reinstall-supported-cli');
+            const { eligibility, detail, diagnostics } = checkDispatchEligibility(parallelism, registry, cli, false, resolverSnapshot, refs);
+            pushDispatch(cli, profileRef, 'warn', 'WORKER_DIRECT_DISPATCH_BLOCKED', eligibility, detail, configKey, members, 'reinstall-supported-cli', diagnostics);
             return;
         }
         const mismatch = workerVersionRangeMismatch(installedVersion, [profile.supportedVersions, adapter.supportedVersions]);
@@ -442,17 +462,17 @@ export async function diagnoseDirectWorkerReadiness(input) {
                 message: `CLI '${executable}' version ${installedVersion} is outside supported range '${mismatch}' for cli '${cli}' (profile '${profileRef}', config ${configFile} key ${configKey}); upgrade or pin a supported release. Installation readiness: not-ready. (${describeConfigContext(members)})`,
                 nextAction: 'upgrade-or-pin-cli',
                 configFile, configKey, readiness: 'not-ready', members });
-            const { eligibility, detail } = checkDispatchEligibility(parallelism, registry, cli, false, resolverSnapshot, refs);
-            pushDispatch(cli, profileRef, 'warn', 'WORKER_DIRECT_DISPATCH_BLOCKED', eligibility, detail, configKey, members, 'upgrade-or-pin-cli');
+            const { eligibility, detail, diagnostics } = checkDispatchEligibility(parallelism, registry, cli, false, resolverSnapshot, refs);
+            pushDispatch(cli, profileRef, 'warn', 'WORKER_DIRECT_DISPATCH_BLOCKED', eligibility, detail, configKey, members, 'upgrade-or-pin-cli', diagnostics);
             return;
         }
         pushInstall({ cli, profile: profileRef, executable, installedVersion,
             status: 'ok', code: 'WORKER_DIRECT_READY',
             message: `CLI '${executable}' version ${installedVersion} matches profile '${profileRef}' for cli '${cli}' (config ${configFile} key ${configKey}). Installation readiness: ready. ${SMOKE_NOTE} See the dispatch finding for whether the resolver would dispatch. (${describeConfigContext(members)})`,
-            nextAction: 'run-authenticated-smoke-run',
+            nextAction: 'qualify-installed-cli',
             configFile, configKey, readiness: 'ready', members });
-        const { eligibility, detail } = checkDispatchEligibility(parallelism, registry, cli, true, resolverSnapshot, refs);
-        pushDispatch(cli, profileRef, eligibility === 'eligible' ? 'ok' : 'warn', eligibility === 'eligible' ? 'WORKER_DIRECT_DISPATCH_ELIGIBLE' : 'WORKER_DIRECT_DISPATCH_BLOCKED', eligibility, detail, configKey, members, 'run-authenticated-smoke-run');
+        const { eligibility, detail, diagnostics } = checkDispatchEligibility(parallelism, registry, cli, true, resolverSnapshot, refs);
+        pushDispatch(cli, profileRef, eligibility === 'eligible' ? 'ok' : 'warn', eligibility === 'eligible' ? 'WORKER_DIRECT_DISPATCH_ELIGIBLE' : 'WORKER_DIRECT_DISPATCH_BLOCKED', eligibility, detail, configKey, members, 'qualify-installed-cli', diagnostics);
     }));
     report.findings.sort((a, b) => a.cli.localeCompare(b.cli) || a.kind.localeCompare(b.kind));
     return report;
@@ -478,7 +498,7 @@ export async function diagnoseDirectWorkerReadiness(input) {
  */
 export async function buildDirectWorkerDoctorSection(input) {
     const { parallelism, registry, probeWorkers } = input;
-    const cliIds = allConfiguredCliIds(parallelism ?? {});
+    const cliIds = allConfiguredCliIds(parallelism ?? {}, input.cli);
     if (!cliIds.length)
         return { lines: [], probed: false, workersConfigured: false, installFindings: [] };
     const lines = [];
@@ -493,6 +513,7 @@ export async function buildDirectWorkerDoctorSection(input) {
     const report = await diagnoseDirectWorkerReadiness({
         parallelism: parallelism,
         registry,
+        cli: input.cli,
         ...(probeWorkers ? { probe: input.probe ?? probeDirectWorkerVersion, ...(input.announce ? { announce: input.announce } : {}) } : {}),
         ...(input.configFile ? { configFile: input.configFile } : {}),
         ...(input.projectRoot ? { projectRoot: input.projectRoot } : {}),
@@ -509,7 +530,7 @@ export async function buildDirectWorkerDoctorSection(input) {
     }
     if (probeWorkers && !report.findings.some(finding => finding.code === 'WORKER_DIRECT_READY')) {
         lines.push({ name: 'Direct Worker', status: 'info',
-            message: 'no profile is onboarded; profiles are unqualified until an authenticated smoke run (see #3005)' });
+            message: `no profile is onboarded; ${SMOKE_NOTE}` });
     }
     return {
         lines,

package/dist/src/models/worker-dispatch-offer.js

@@ -32,7 +32,7 @@ import { loadProviderModelCapabilities } from './provider-policy.js';
  */
 export const WORKER_DISPATCH_ENABLE_COMMAND = 'aiwg config set --project parallelism.worker_dispatch true';
 /** Readiness check shared by setup hints and dispatch refusals. */
-export const WORKER_DISPATCH_READINESS_COMMAND = 'aiwg doctor --probe-workers';
+export const WORKER_DISPATCH_READINESS_COMMAND = 'aiwg doctor --probe-workers --qualify';
 /**
  * Dotted config path a decline is recorded at. A setup/onboarding
  * preference, not worker policy — kept out of `parallelism`, which is a
@@ -117,7 +117,7 @@ export function evaluateWorkerDispatchOffer(parallelism, setup, detected) {
  */
 export function workerDispatchOfferQuestion(detected) {
     return `  Detected worker CLIs (${detected.join(', ')}). Enable direct worker dispatch so AIWG `
-        + `can dispatch tasks to them directly, using their own accounts' quota? [y/N]: `;
+        + `can dispatch tasks to them directly, using their own accounts' quota? After enabling, run aiwg doctor --probe-workers --qualify. [y/N]: `;
 }
 /**
  * One-line non-interactive / regenerate / refresh / doctor hint. Never
@@ -127,7 +127,7 @@ export function workerDispatchOfferQuestion(detected) {
  */
 export function workerDispatchOfferHint(detected) {
     return `Direct worker dispatch is off; detected worker CLIs: ${detected.join(', ')}. `
-        + `Enable with \`${WORKER_DISPATCH_ENABLE_COMMAND}\` (then check readiness with \`${WORKER_DISPATCH_READINESS_COMMAND}\`).`;
+        + `Enable with \`${WORKER_DISPATCH_ENABLE_COMMAND}\` (then qualify installed CLIs with \`${WORKER_DISPATCH_READINESS_COMMAND}\`).`;
 }
 /**
  * Accepted values for the `--worker-dispatch` argument (#3062). Only

package/dist/src/models/worker-health-readiness.js

@@ -61,18 +61,31 @@ export function diagnoseWorkerHealthReadiness(snapshot, request) {
                 message: 'No explicit quota/account correlation scope; shared aliases cannot establish independent upstream capacity.',
                 nextAction: 'configure-qualified-quota-scope' });
     }
+    const sharedDiagnostics = new Map();
     for (const role of roles) {
         const plan = resolveWorkerPlan(snapshot, { ...request, role: role });
         const isRequired = required.has(role);
         const diagnostics = [...plan.diagnostics, ...plan.exclusions.flatMap(item => item.diagnostics)];
         const seen = new Set();
         for (const diagnostic of diagnostics) {
-            const key = `${diagnostic.code}:${diagnostic.pointer}:${diagnostic.message}`;
+            if (diagnostic.roles && !diagnostic.roles.includes(role))
+                continue;
+            const key = JSON.stringify([diagnostic.code, diagnostic.pointer, diagnostic.message, diagnostic.blocking, diagnostic.origins]);
             if (seen.has(key))
                 continue;
             seen.add(key);
-            add({ ...diagnostic, status: diagnostic.blocking === false ? 'info' : 'warn', role,
-                nextAction: repairAction(diagnostic.code, diagnostic.pointer) });
+            const finding = { ...diagnostic,
+                status: diagnostic.blocking === false ? 'info' : 'warn', role,
+                nextAction: repairAction(diagnostic.code, diagnostic.pointer) };
+            const shared = sharedDiagnostics.get(key);
+            if (shared) {
+                shared.roles = [...new Set([...(shared.roles ?? [shared.role]), role])];
+                shared.role = null;
+            }
+            else {
+                sharedDiagnostics.set(key, finding);
+                add(finding);
+            }
         }
         if (!plan.selected) {
             if (isRequired)

package/dist/src/models/worker-installation.d.mts

@@ -0,0 +1,39 @@
+import type { ProviderModelCapabilityRegistry } from './provider-policy.js';
+import type { WorkerSelectionPolicy } from './types.js';
+import type { WorkerResolutionBinding } from './resolver.js';
+import type { WorkerInvocationDriver } from '../serve/worker-invocation.js';
+export function loadRecordedWorkerInstallations(input: {
+  registry: ProviderModelCapabilityRegistry;
+  cwd: string;
+  policy?: WorkerSelectionPolicy;
+  parallelism?: import('../config/aiwg-config.js').ParallelismConfig;
+  storePath?: string;
+  storeDigest?: string;
+}): Promise<{ registry: ProviderModelCapabilityRegistry; installations: Record<string, WorkerResolutionBinding>; drivers: Record<string, WorkerInvocationDriver>; observations: Record<string, import('./model-discovery.js').ProviderModelDiscovery> }>;
+
+export function hasProvider(name: string): boolean;
+
+export function compileWorkerVersionPattern(pattern: string): RegExp;
+export function normalizeWorkerVersionBanner(banner: string, pattern?: string): string;
+export const workerVersionProbeEnvAllowlist: readonly string[];
+export function workerVersionProbeEnvironment(source?: Record<string, string | undefined>): Record<string, string>;
+export const workerVersionProbeDefaults: { readonly timeoutMs: number; readonly maxBytes: number };
+export function workerVersionRangeMismatch(version: string, ranges: string[]): string | null;
+export function boundedVersionProbe(
+  executable: string,
+  argv: string[],
+  environment: Record<string, string>,
+  cwd: string,
+  timeoutMs: number,
+  maxBytes: number,
+  versionPattern: string | undefined,
+): Promise<{ rawBanner: string; version: string }>;
+
+export interface WorkerRecoveryCapabilities {
+  canVerifyAttempt?: boolean;
+  parseWorkerAttemptFinal?(output: string | Uint8Array, options: Record<string, unknown>): Promise<unknown>;
+}
+export function registerWorkerRecoveryCapabilities<T extends object>(driver: T, capabilities: WorkerRecoveryCapabilities): T;
+export function getWorkerRecoveryCapabilities(driver: object | undefined | null): Readonly<WorkerRecoveryCapabilities> | null;
+
+export function prepareWorkerInstallationStore(input: { workerWritableRoots: string[]; apply?: boolean }): Promise<{ path: string; action: string }[]>;