@aiwg/cli 2026.10.9 → 2026.10.10

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

@@ -57,11 +57,9 @@
  * performs no live-qualification recording and requires no evidence files.
  */
 import { tmpdir } from 'node:os';
+import { advisoryStatus, allConfiguredCliIds, checkDispatchEligibility, describeConfigContext, isCliRequired, memberLabels, memberReferences, resolveDirectBinding, SMOKE_NOTE, } from './worker-direct-readiness-policy.js';
 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 = '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;
@@ -100,214 +98,6 @@ export async function probeDirectWorkerVersion(executable, versionArgv, options
         return { ok: false, reason: error?.code === 'ENOENT' ? 'not-installed' : 'probe-failed' };
     }
 }
-const ADAPTER_REFERENCE = /^(providers|workerAdapters):(.+)$/;
-/**
- * Resolve the configured binding by exact, case-sensitive namespace:id
- * lookup — the same shape `resolveWorkerAdapter` (provider-policy.ts) uses
- * for dispatch and `validateParallelismConfig` uses for config validation.
- * No alias normalization happens for either namespace, so a binding this
- * accepts is also a binding the public config validator accepts, and a
- * custom `workerAdapters:<id>` reference resolves against
- * `registry.workerAdapters`, never against the provider-alias registry.
- *
- * For the `providers` namespace this falls back from `workerAdapter` to
- * `workerHealthAdapter` when no direct-dispatch binding is pinned yet — the
- * install/version metadata is identical either way, and that is exactly
- * what lets install readiness and dispatch eligibility disagree honestly
- * (installed and in range, but the resolver still has no workerAdapter to
- * dispatch through).
- */
-function resolveDirectBinding(registry, configuredAdapter, cli) {
-    let namespace;
-    let id;
-    if (configuredAdapter !== undefined) {
-        const match = ADAPTER_REFERENCE.exec(configuredAdapter.trim());
-        if (!match)
-            return { error: `Invalid worker adapter reference '${configuredAdapter}'` };
-        [, namespace, id] = match;
-    }
-    else {
-        namespace = 'providers';
-        id = cli;
-    }
-    if (namespace === 'providers') {
-        const entry = registry.providers[id];
-        const adapter = entry?.workerAdapter ?? entry?.workerHealthAdapter;
-        if (!adapter)
-            return { error: `No direct worker profile is registered for binding 'providers:${id}'` };
-        return { adapter, adapterRef: `providers:${id}` };
-    }
-    const adapter = registry.workerAdapters?.[id];
-    if (!adapter)
-        return { error: `Unknown worker adapter reference 'workerAdapters:${id}'` };
-    return { adapter, adapterRef: `workerAdapters:${id}` };
-}
-/** Every group member referencing this cli, including disabled ones (for context). */
-function memberReferences(parallelism, cli) {
-    const refs = [];
-    for (const [groupId, group] of Object.entries(parallelism.groups ?? {})) {
-        for (const member of group?.members ?? []) {
-            if (member.cli !== cli)
-                continue;
-            refs.push({ groupId, memberId: member.id, member,
-                enabled: member.enabled !== false && parallelism.clis?.[cli]?.enabled !== false });
-        }
-    }
-    return refs.sort((a, b) => `${a.groupId}/${a.memberId}`.localeCompare(`${b.groupId}/${b.memberId}`));
-}
-function memberLabels(refs) {
-    return refs.map(ref => `${ref.groupId}/${ref.memberId}${ref.enabled ? '' : ' (disabled)'}`);
-}
-function describeConfigContext(members) {
-    return members.length ? `members: ${members.join(', ')}` : 'members: no group member references this cli';
-}
-/**
- * Union of every cli id a readiness pass must consider: explicit
- * `parallelism.clis` entries plus any cli id referenced only implicitly by a
- * group member (canonical default binding, no explicit installation entry).
- */
-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].filter(id => cli === undefined || id === cli).sort();
-}
-/**
- * A cli is "required" only when an enabled group member referencing it also
- * covers a role its group lists in `requiredRoles`. Every other configured
- * cli is optional: installation failures stay advisory (never 'error', so
- * they never flip doctor's exit code) until something actually requires it.
- */
-function isCliRequired(parallelism, cli) {
-    for (const group of Object.values(parallelism.groups ?? {})) {
-        const required = new Set(group?.requiredRoles ?? []);
-        if (!required.size)
-            continue;
-        for (const member of group?.members ?? []) {
-            if (member.cli !== cli || member.enabled === false)
-                continue;
-            if (parallelism.clis?.[cli]?.enabled === false)
-                continue;
-            if (member.roles.some(role => required.has(role)))
-                return true;
-        }
-    }
-    return false;
-}
-/** Cap a status at 'warn' for optional (non-required) clis so an unreferenced
- * or not-yet-wired profile never flips doctor's exit code. */
-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 });
-/**
- * Dispatch eligibility from the actual offline dispatch resolver
- * (`resolveWorkerPlan`): called once per role for every group member
- * referencing this cli, never re-derived. A resolvable binding alone is not
- * reported as eligible — eligibility requires the resolver to actually place
- * at least one referencing member in its eligible/alternatives set. Refusals
- * are member-specific and name the resolver's own missing-evidence or policy
- * diagnostics.
- */
-function resolveEligibilityFromDispatchResolver(resolverSnapshot, registry, cli, refs) {
-    const snapshot = {
-        config: resolverSnapshot.config, models: resolverSnapshot.models, modelDigests: resolverSnapshot.modelDigests,
-        catalog: resolverSnapshot.catalog, registry, installations: {},
-    };
-    const diagnostics = new Map();
-    const uncovered = [];
-    for (const ref of refs) {
-        if (!ref.enabled)
-            continue;
-        const matches = (tuple) => tuple.group === ref.groupId && tuple.member === ref.memberId;
-        const seen = [];
-        let eligibleHere = false;
-        for (const role of ref.member.roles) {
-            const plan = resolveWorkerPlan(snapshot, {
-                role: role, group: ref.groupId, member: ref.memberId,
-                now: resolverSnapshot.now, context: offlineDirectContext(),
-            });
-            if ([plan.selected, ...plan.alternatives].some(tuple => tuple && matches(tuple))) {
-                eligibleHere = true;
-                break;
-            }
-            const exclusion = plan.exclusions.find(matches);
-            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}` };
-        }
-        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 (!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}` };
-    }
-    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}` };
-}
-/**
- * Binding-only fallback used only when the caller has not supplied a
- * `resolverSnapshot` (for example a direct unit-level call that never
- * resolved the wider model config/catalog). States plainly that this is a
- * binding-level result, not the dispatch resolver's verdict.
- */
-function resolveEligibilityFromBindingOnly(parallelism, registry, cli, installReady) {
-    try {
-        const resolved = resolveWorkerGroupInstallation(parallelism, cli, registry);
-        return { eligibility: 'eligible',
-            detail: `Resolver accepts cli '${cli}' (binding '${resolved.installation.adapter}'). Dispatch eligibility: eligible at binding level only — `
-                + `no resolver snapshot was supplied, so group/member qualification was not evaluated. `
-                + `Launch additionally requires current installation evidence and model observation under the dispatch resolver's gates. `
-                + `${SMOKE_NOTE}` };
-    }
-    catch (error) {
-        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. ${SMOKE_NOTE}`
-            : ` ${SMOKE_NOTE}`;
-        return { eligibility: 'blocked',
-            detail: `Resolver refuses cli '${cli}': ${reason}. Dispatch eligibility: blocked.${readyNote}` };
-    }
-}
-function checkDispatchEligibility(parallelism, registry, cli, installReady, resolverSnapshot, refs) {
-    if (resolverSnapshot && refs.length)
-        return resolveEligibilityFromDispatchResolver(resolverSnapshot, registry, cli, refs);
-    return resolveEligibilityFromBindingOnly(parallelism, registry, cli, installReady);
-}
 /**
  * Read-only readiness for every configured worker. Starts no process unless
  * `probe` is supplied; without a prober each cli gets a config-only install
@@ -325,14 +115,15 @@ export async function diagnoseDirectWorkerReadiness(input) {
         findings: [],
     };
     if (!report.enabled) {
+        const members = allConfiguredCliIds(parallelism, input.cli).flatMap(cli => memberLabels(memberReferences(parallelism, cli)));
         report.findings.push({ cli: '*', kind: 'dispatch', profile: null, executable: null, installedVersion: null,
             status: 'info', code: 'WORKER_DIRECT_DISABLED',
-            message: `Group dispatch is disabled (config ${configFile} key /parallelism/worker_dispatch); install/version checks do not apply and onboarding cannot proceed.`,
+            message: `Group dispatch is disabled (config ${configFile} key /parallelism/worker_dispatch); install/version checks do not apply and onboarding cannot proceed. (${describeConfigContext(members)})`,
             nextAction: 'enable-worker-dispatch-to-onboard',
             configFile, configKey: '/parallelism/worker_dispatch',
             readiness: null, eligibility: 'blocked',
             eligibilityDetail: 'Dispatch eligibility: blocked — group dispatch is disabled.',
-            members: [] });
+            members });
         return report;
     }
     const cliIds = allConfiguredCliIds(parallelism, input.cli);
@@ -363,9 +154,9 @@ export async function diagnoseDirectWorkerReadiness(input) {
                 status: 'info', code: 'WORKER_DIRECT_CLI_DISABLED',
                 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 });
+                configFile, configKey: `${configKey}/enabled`, readiness: 'skipped', members });
             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);
+            pushDispatch(cli, configured.invocationProfile ?? null, 'info', 'WORKER_DIRECT_DISPATCH_BLOCKED', eligibility, detail, `${configKey}/enabled`, members, 'enable-cli-to-onboard', diagnostics);
             return;
         }
         const resolved = resolveDirectBinding(registry, configured?.adapter, cli);
@@ -399,9 +190,9 @@ export async function diagnoseDirectWorkerReadiness(input) {
                 status: advisoryStatus('error', required), code: 'WORKER_DIRECT_PROFILE_UNKNOWN',
                 message: configured?.invocationProfile
                     ? `Configured invocation profile '${configured.invocationProfile}' is not registered for binding '${adapterRef}' (config ${configFile} key ${configKey}/invocationProfile). Installation readiness: not-ready. (${describeConfigContext(members)})`
-                    : `Cli '${cli}' binding '${adapterRef}' has no single direct profile to check (config ${configFile} key ${configKey}); configure invocationProfile explicitly. Installation readiness: not-ready. (${describeConfigContext(members)})`,
+                    : `Cli '${cli}' binding '${adapterRef}' has no single direct profile to check (config ${configFile} key ${configKey}/invocationProfile); configure invocationProfile explicitly. Installation readiness: not-ready. (${describeConfigContext(members)})`,
                 nextAction: 'review-worker-configuration',
-                configFile, configKey, readiness: 'not-ready', members });
+                configFile, configKey: `${configKey}/invocationProfile`, readiness: 'not-ready', members });
             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;
@@ -435,7 +226,7 @@ export async function diagnoseDirectWorkerReadiness(input) {
                     ? `CLI '${executable}' is not installed (version probe failed to start; config ${configFile} key ${configKey}/executable); install it before onboarding cli '${cli}'. Installation readiness: not-ready. (${describeConfigContext(members)})`
                     : `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 });
+                configFile, configKey: notInstalled ? `${configKey}/executable` : configKey, readiness: 'not-ready', members });
             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;

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

@@ -1,5 +1,8 @@
 /** Offline S1 health readiness projection; never launch authority or a probe. */
-import { validateParallelismConfig, resolveWorkerGroupInstallation, workerConfigDigest } from '../config/aiwg-config.js';
+import { homedir } from 'node:os';
+import { collectLocalOnlyPaths } from './conductor-data-policy.mjs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { resolveParallelism, validateParallelismConfig, resolveWorkerGroupInstallation, workerConfigDigest } from '../config/aiwg-config.js';
 import { assertWorkerHealthQualification } from './provider-policy.js';
 import { resolveWorkerPlan } from './resolver.js';
 import { resolveWorkerEffectiveHealth } from '../serve/worker-invocation.js';
@@ -18,11 +21,86 @@ const repairAction = (code, pointer) => {
         return 'qualify-installation-and-profile';
     return 'review-worker-configuration';
 };
-export function diagnoseWorkerHealthReadiness(snapshot, request) {
-    const p = snapshot.config.parallelism;
+/** Preserve the same repair context in human-readable doctor output and JSON. */
+export function formatWorkerHealthReadinessFinding(finding) {
+    return `${finding.code}: ${finding.message} (config ${finding.configFile} key ${finding.configKey}; members: ${finding.members.join(', ') || 'none'}) [next: ${finding.nextAction}]`;
+}
+/** Build offline configuration repair findings before model/catalog loading is possible. */
+export function workerHealthConfigurationFindings(parallelism, errors, paths = {}) {
+    return errors.map(message => {
+        const pointer = message.match(/^OG_CONFIG_REFERENCE (\/[^:]*):/)?.[1] ?? '/parallelism';
+        const parts = pointer.split('/');
+        const members = Object.entries(parallelism?.groups ?? {}).flatMap(([group, value]) => (Array.isArray(value?.members) ? value.members : []).filter((member, index) => {
+            if (!member || typeof member.id !== 'string')
+                return false;
+            if (parts[2] === 'groups')
+                return group === parts[3]
+                    && (parts[4] !== 'members' || member.id === parts[5] || String(index) === parts[5]);
+            return parts[2] !== 'clis' || member.cli === parts[3];
+        }).map(member => `${group}/${member.id}`));
+        return { code: 'OG_CONFIG_REFERENCE', status: 'error', pointer,
+            configFile: paths.configFile ?? resolve('.aiwg/aiwg.config'), configKey: pointer,
+            members, message, nextAction: 'review-worker-configuration', role: null };
+    });
+}
+export function diagnoseWorkerHealthReadiness(snapshot, request, paths = {}) {
+    let p = snapshot.config.parallelism;
     const report = { enabled: p?.worker_dispatch === true,
         ready: true, contextDigest: null, findings: [], thresholds: [] };
-    const add = (finding) => { report.findings.push(finding); };
+    const configFile = paths.configFile ?? resolve('.aiwg/aiwg.config');
+    const modelsFile = paths.modelsFile ?? resolve('models.json');
+    const catalogFile = paths.catalogFile ?? join(homedir(), '.cache/aiwg/model-catalog.v1.json');
+    const errors = validateParallelismConfig(p);
+    if (!errors.length && p?.worker_dispatch)
+        p = resolveParallelism(p, snapshot.config.providers[0]);
+    const allMembers = Object.entries(p?.groups ?? {}).flatMap(([group, value]) => (value.members ?? []).map(member => ({ group, member, label: `${group}/${member.id}` })));
+    const membersFor = (pointer, role) => {
+        const parts = pointer.split('/');
+        const groups = role ? snapshot.models.defaults.workerSelection?.roleGuidance?.[role]?.groups : undefined;
+        return allMembers.filter(row => {
+            if (parts[1] === 'parallelism' && parts[2] === 'groups')
+                return row.group === parts[3]
+                    && (parts[4] !== 'members' || row.member.id === parts[5])
+                    && (parts[4] !== 'requiredRoles' || !role || row.member.roles.includes(role));
+            if (parts[1] === 'parallelism' && parts[2] === 'clis')
+                return row.member.cli === parts[3];
+            return !groups || groups.includes(row.group);
+        }).map(row => row.label);
+    };
+    const contextualize = (finding, members) => {
+        let file = configFile;
+        let key = finding.pointer;
+        if (key.startsWith('/defaults/') || key.startsWith('/agentOverrides')) {
+            const origins = Object.entries(snapshot.models.workerPolicyOrigins ?? {})
+                .filter(([pointer]) => pointer === key || pointer.startsWith(`${key}/`))
+                .flatMap(([, values]) => values).filter(origin => isAbsolute(origin.source))
+                .sort((a, b) => ['builtin', 'user', 'project'].indexOf(a.authority)
+                - ['builtin', 'user', 'project'].indexOf(b.authority));
+            file = origins.at(-1)?.source ?? modelsFile;
+        }
+        else if (key.startsWith('/catalog/')) {
+            file = catalogFile;
+            key = key.slice('/catalog'.length);
+        }
+        else if (key === '/worker' || key.startsWith('/worker/')) {
+            file = catalogFile;
+            const affected = allMembers.find(row => row.label === members[0]);
+            const cli = affected?.member.cli;
+            const index = cli ? snapshot.catalog.discovery?.instances?.[cli]?.models.findIndex(row => row.id === affected.member.model || row.apiModelId === affected.member.model) : undefined;
+            if (cli && index !== undefined && index >= 0)
+                key = `/discovery/instances/${cli}/models/${index}${key}`;
+        }
+        return { ...finding, configFile: file, configKey: key, members: [...new Set(members)] };
+    };
+    const add = (finding, members = membersFor(finding.pointer, finding.role)) => {
+        report.findings.push(contextualize(finding, members));
+    };
+    const localOnlyPaths = collectLocalOnlyPaths(snapshot.models.defaults.workerSelection, p);
+    if (localOnlyPaths.length)
+        add({ code: 'CONDUCTOR_LOCAL_ONLY_PATHS', status: 'info',
+            pointer: '/defaults/workerSelection/dataPolicy/localOnlyPaths', role: null,
+            message: `Declared local-only conductor inputs: ${localOnlyPaths.join(', ')}. Deploy provider guards before opening task inputs; shell coverage is limited.`,
+            nextAction: 'deploy-provider-data-guards' });
     if (!report.enabled) {
         add({ code: 'WORKER_HEALTH_DISABLED', status: 'info', pointer: '/parallelism/worker_dispatch',
             message: 'Group dispatch is disabled; legacy execution has no worker health readiness requirement.',
@@ -30,12 +108,9 @@ export function diagnoseWorkerHealthReadiness(snapshot, request) {
         return report;
     }
     report.contextDigest = workerConfigDigest({ context: request.context, modelDigests: snapshot.modelDigests });
-    const errors = validateParallelismConfig(p);
     if (errors.length) {
         report.ready = false;
-        for (const message of errors)
-            add({ code: 'OG_CONFIG_REFERENCE', status: 'error',
-                pointer: '/parallelism', message, nextAction: 'review-worker-configuration', role: null });
+        report.findings.push(...workerHealthConfigurationFindings(p, errors, { configFile }));
         return report;
     }
     if (p?.worker_mode === 'managed') {
@@ -53,7 +128,7 @@ export function diagnoseWorkerHealthReadiness(snapshot, request) {
             message: 'No worker role guidance is configured; onboarding cannot offer a qualified route.',
             nextAction: 'configure-role-guidance', role: null });
     }
-    const installations = new Set(enabledGroups.flatMap(group => group.members.filter(member => member.enabled !== false).map(member => member.cli)));
+    const installations = new Set(enabledGroups.flatMap(group => (group.members ?? []).filter(member => member.enabled !== false).map(member => member.cli)));
     for (const cli of installations) {
         if (!p?.clis?.[cli]?.quotaScope)
             add({ code: 'WORKER_QUOTA_SCOPE_UNKNOWN', status: 'warn', role: null,
@@ -65,26 +140,30 @@ export function diagnoseWorkerHealthReadiness(snapshot, request) {
     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 diagnostics = [
+            ...plan.diagnostics.map(diagnostic => ({ diagnostic, members: membersFor(diagnostic.pointer, role) })),
+            ...plan.exclusions.flatMap(item => item.diagnostics.map(diagnostic => ({ diagnostic,
+                members: [`${item.group}/${item.member}`] }))),
+        ];
+        for (const { diagnostic, members } of diagnostics) {
             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);
-            const finding = { ...diagnostic,
+            const finding = contextualize({ ...diagnostic,
                 status: diagnostic.blocking === false ? 'info' : 'warn', role,
-                nextAction: repairAction(diagnostic.code, diagnostic.pointer) };
+                nextAction: repairAction(diagnostic.code, diagnostic.pointer) }, members);
+            const key = JSON.stringify([diagnostic.code, diagnostic.pointer, diagnostic.message, diagnostic.blocking,
+                diagnostic.origins, finding.configFile, finding.configKey]);
             const shared = sharedDiagnostics.get(key);
             if (shared) {
-                shared.roles = [...new Set([...(shared.roles ?? [shared.role]), role])];
-                shared.role = null;
+                shared.members = [...new Set([...shared.members, ...finding.members])];
+                if (shared.role !== role) {
+                    shared.roles = [...new Set([...(shared.roles ?? [shared.role]), role])];
+                    shared.role = null;
+                }
             }
             else {
                 sharedDiagnostics.set(key, finding);
-                add(finding);
+                report.findings.push(finding);
             }
         }
         if (!plan.selected) {
@@ -111,11 +190,11 @@ export function diagnoseWorkerHealthReadiness(snapshot, request) {
                 add({ code: 'WORKER_STEP_CAP_NOT_READY', status: isRequired ? 'error' : 'warn', role,
                     pointer: '/parallelism/health/requireStepCap',
                     message: 'Required step cap lacks native enforcement or qualified runtime pre-step admission evidence.',
-                    nextAction: 'qualify-step-enforcement' });
+                    nextAction: 'qualify-step-enforcement' }, [`${tuple.group}/${tuple.member}`]);
                 continue;
             }
             // External admission needs runtime gate evidence; a config declaration alone cannot prove it.
-            const health = resolveWorkerEffectiveHealth(p?.health, { role, effort: tuple.effort,
+            const health = resolveWorkerEffectiveHealth(p?.health, { role: plan.policy?.roleGuidance?.[role]?.baseRole ?? role, effort: tuple.effort,
                 modelKey: tuple.modelKey, profileRef: tuple.profile, wallSeconds: plan.ceilings.wallSeconds ?? 1800,
                 stepEnforcement: nativeSteps ? 'native' : 'unavailable' });
             report.thresholds.push({ role, group: tuple.group, member: tuple.member, health });
@@ -123,12 +202,12 @@ export function diagnoseWorkerHealthReadiness(snapshot, request) {
                 add({ code: 'WORKER_HEALTH_DEGRADED', status: 'warn', role,
                     pointer: `/parallelism/clis/${tuple.cli}/invocationProfile`,
                     message: 'Profile has degraded or unobserved health coverage; progress and stop evidence may be unavailable.',
-                    nextAction: 'qualify-health-signals' });
+                    nextAction: 'qualify-health-signals' }, [`${tuple.group}/${tuple.member}`]);
             }
             add({ code: 'WORKER_ROLE_ELIGIBLE', status: 'ok', role,
                 pointer: `/defaults/workerSelection/roleGuidance/${role}`,
                 message: 'Policy route is eligible; launch still requires current installation and task qualification.',
-                nextAction: 'resolve-current-task' });
+                nextAction: 'resolve-current-task' }, [`${tuple.group}/${tuple.member}`]);
         }
         catch {
             if (isRequired)
@@ -136,7 +215,7 @@ export function diagnoseWorkerHealthReadiness(snapshot, request) {
             add({ code: 'WORKER_HEALTH_UNQUALIFIED', status: isRequired ? 'error' : 'warn', role,
                 pointer: `/parallelism/clis/${tuple.cli}/invocationProfile`,
                 message: 'Health profile scope or effective settings are invalid; requalify the exact version/account/model/effort.',
-                nextAction: 'qualify-health-signals' });
+                nextAction: 'qualify-health-signals' }, [`${tuple.group}/${tuple.member}`]);
         }
     }
     return report;

package/dist/src/models/worker-installation.mjs

@@ -1,5 +1,6 @@
 /** Shared installed-worker qualification owner, also used by the Ralph compatibility facade. */
 import { spawn } from 'node:child_process';
+import { buildInstalledWorkerTransport } from './worker-artifact-binding.mjs';
 import { constants } from 'node:fs';
 import { open, realpath, lstat, mkdir, rename, writeFile, unlink } from 'node:fs/promises';
 import path from 'node:path';
@@ -207,11 +208,11 @@ export async function prepareInstalledWorkerInvocation(instance, invocation, qua
         || result.stdin !== qualification.adapter.invocation.stdin) {
         throw new WorkerPolicyError('OG_PIN_MISMATCH', 'Worker argv/stdin differs from the authorized driver mapping');
       }
-      // Shell plans contain names, never credential values. Recheck the named
-      // launch environment now; the conductor must repeat preparation if it
-      // changes before copying the command into its shell.
+      // Shell plans contain names, never values. PATH is host plumbing; its
+      // allowlisted name stays bound, while the executable is pinned separately.
+      // Other launch values must still match qualification.
       if (JSON.stringify([...result.envNames].sort()) !== JSON.stringify(Object.keys(installation.environment ?? {}).sort())
-        || result.envNames.some(name => process.env[name] !== installation.environment[name])) {
+        || result.envNames.some(name => name !== 'PATH' && process.env[name] !== installation.environment[name])) {
         throw new WorkerPolicyError('OG_PIN_MISMATCH', 'Worker launch environment differs from qualification');
       }
     }
@@ -345,13 +346,13 @@ export async function inspectWorkerInstallation(instance, request) {
   return { binary, cwd: canonicalCwd, inputRoots, outputRoots, scopeDigest: qualificationDigest({ metadata, profileId, cliVersion, platform, binary, modules, runtimeFiles,
     permissionRequirements, controlArgv, fixtureDigest: await workerNegativeFixtureDigest(),
     requiredControls: [...requiredControls].sort(), effectiveConfigDigest, accountScope, boundary, cwd: canonicalCwd,
-    workerWritableRoots: canonicalWritableRoots, inputRoots, outputRoots, environmentDigest: qualificationDigest(environment), endpoints, mcp: request.mcp ?? null,
+    workerWritableRoots: canonicalWritableRoots, inputRoots, outputRoots, environmentDigest: qualificationDigest(Object.fromEntries(Object.entries(environment).filter(([name]) => name !== 'PATH'))), endpoints, mcp: request.mcp ?? null,
     mcpServerDigest: request.mcpServerDigest ?? null }) };
 }
 
 /** Restricted whole-banner regex: one capture, no branching, assertions,
  * backreferences, wildcards, unbounded repetition or repeated groups. Bounded
- * at most two atom repetitions, each capped at 128; banners are capped at 4096 bytes. */
+ * at most two atom repetitions capped at 128, or a final [\s\S] banner tail capped at 4096 bytes. */
 export function compileWorkerVersionPattern(pattern) {
   if (typeof pattern !== 'string' || pattern.length > 256 || !pattern.startsWith('^') || !pattern.endsWith('$')) throw new Error('Invalid worker version pattern');
   let captures = 0, depth = 0, repetitions = 0, atom = false;
@@ -376,7 +377,7 @@ export function compileWorkerVersionPattern(pattern) {
       depth--; atom = false; // groups cannot be repeated
     } else if (c === '{') {
       const match = /^\{([0-9]+),([0-9]+)\}/.exec(pattern.slice(i));
-      if (++repetitions > 2 || !atom || !match || +match[1] < 1 || +match[2] < +match[1] || +match[2] > 128) throw new Error('Unsafe worker version repetition');
+      if (++repetitions > 2 || !atom || !match || +match[1] < 1 || +match[2] < +match[1] || +match[2] > (captures === 1 && depth === 0 && pattern.slice(i - 6) === '[\\s\\S]{1,4096}$' ? 4096 : 128)) throw new Error('Unsafe worker version repetition');
       i += match[0].length - 1; atom = false;
     } else {
       if ('.*+?|^$}'.includes(c)) throw new Error('Unsafe worker version pattern');
@@ -1141,13 +1142,10 @@ export async function loadRecordedWorkerInstallations({ registry, cwd, policy, p
           platform: process.platform, installation, stdinFramerBinding: { storePath: filename, storeDigest: digest },
           ...(profile.transport === 'mcp' ? { mcp: binding.mcp, mcpSchemas: record.mcpSchemas } : {}) },
         ...(typeof instance.buildWorkerStdinFrame === 'function'
-          ? { buildWorkerStdinFrame: brief => instance.buildWorkerStdinFrame(brief) } : {}),
-        buildInvocation: async input => profile.transport === 'shell' ? {
-          argv: [scope.binary.realpath, ...instance.buildWorkerArgs(input, profile, input.permissions)],
-          stdin: adapter.invocation.stdin, envNames: Object.keys(installation.environment),
-          ...(typeof instance.buildWorkerArtifacts === 'function'
-            ? { artifacts: instance.buildWorkerArtifacts(input) } : {}),
-        } : instance.buildInvocation(input),
+          ? { buildWorkerStdinFrame: (brief, invocation) => instance.buildWorkerStdinFrame(brief, invocation) } : {}),
+        buildInvocation: async input => profile.transport === 'shell'
+          ? buildInstalledWorkerTransport(instance, input, profile, adapter.invocation, scope.binary.realpath, installation.environment)
+          : instance.buildInvocation(input),
         prepareWorkerInvocation: (invocation, qualification) => prepareInstalledWorkerInvocation(instance, invocation, qualification),
         ...(mcpRegistry ? { mcpRegistry, mcpProfile: record.mcpProfile } : {}),
       };

package/dist/src/models/worker-member-references.js

@@ -0,0 +1,64 @@
+import { expandWorkerGroupTemplates } from '../config/worker-group-templates.js';
+/** Every group member referencing this cli, including disabled ones (for context). */
+export function memberReferences(parallelism, cli) {
+    parallelism = expandWorkerGroupTemplates(parallelism).parallelism;
+    const refs = [];
+    for (const [groupId, group] of Object.entries(parallelism.groups ?? {})) {
+        for (const member of group?.members ?? []) {
+            if (member.cli !== cli)
+                continue;
+            refs.push({ groupId, memberId: member.id, member,
+                enabled: member.enabled !== false && parallelism.clis?.[cli]?.enabled !== false });
+        }
+    }
+    return refs.sort((a, b) => `${a.groupId}/${a.memberId}`.localeCompare(`${b.groupId}/${b.memberId}`));
+}
+export function memberLabels(refs) {
+    return refs.map(ref => `${ref.groupId}/${ref.memberId}${ref.enabled ? '' : ' (disabled)'}`);
+}
+export function describeConfigContext(members) {
+    return members.length ? `members: ${members.join(', ')}` : 'members: no group member references this cli';
+}
+/**
+ * Union of every cli id a readiness pass must consider: explicit
+ * `parallelism.clis` entries plus any cli id referenced only implicitly by a
+ * group member (canonical default binding, no explicit installation entry).
+ */
+export function allConfiguredCliIds(parallelism, cli) {
+    parallelism = expandWorkerGroupTemplates(parallelism).parallelism;
+    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].filter(id => cli === undefined || id === cli).sort();
+}
+/**
+ * A cli is "required" only when an enabled group member referencing it also
+ * covers a role its group lists in `requiredRoles`. Every other configured
+ * cli is optional: installation failures stay advisory (never 'error', so
+ * they never flip doctor's exit code) until something actually requires it.
+ */
+export function isCliRequired(parallelism, cli) {
+    parallelism = expandWorkerGroupTemplates(parallelism).parallelism;
+    for (const group of Object.values(parallelism.groups ?? {})) {
+        const required = new Set(group?.requiredRoles ?? []);
+        if (!required.size)
+            continue;
+        for (const member of group?.members ?? []) {
+            if (member.cli !== cli || member.enabled === false)
+                continue;
+            if (parallelism.clis?.[cli]?.enabled === false)
+                continue;
+            if (member.roles.some(role => required.has(role)))
+                return true;
+        }
+    }
+    return false;
+}
+/** Cap a status at 'warn' for optional (non-required) clis so an unreferenced
+ * or not-yet-wired profile never flips doctor's exit code. */
+export function advisoryStatus(status, required) {
+    return required || status !== 'error' ? status : 'warn';
+}
+//# sourceMappingURL=worker-member-references.js.map