@aiwg/cli 2026.10.8 → 2026.10.10

package/dist/src/models/worker-plan.js

@@ -0,0 +1,317 @@
+// Resolves eligible worker tuples against current config, catalog and installation snapshots.
+import { ownWorkerRoleGuidance } from './worker-selection-policy.js';
+import { mergeGroupWorkerPolicy } from '../config/worker-group-templates.js';
+import { WORKER_DISPATCH_ENABLE_COMMAND, WORKER_DISPATCH_READINESS_COMMAND } from './worker-dispatch-offer.js';
+import { resolveWorkerGroupInstallation, resolveParallelism, validateWorkerGroupQualifications, validateWorkerGroupReferences, validateWorkerBudgetEnforcement, workerActivationDigests, workerConfigDigest, } from '../config/aiwg-config.js';
+import { qualifyWorkerInvocationProfile, validateWorkerPolicyRoute, validateWorkerModelObservation, assertWorkerLaunchMode, hasOperatorWorkerNativeRenderer, hasSelectionRelevantConflicts, workerContextHeadroom, workerModelKey, isCanonicalWorkerModelKey, WorkerSelectionPolicySchema, validateWorkerCatalogDiscovery, } from './provider-policy.js';
+import { MODEL_WRAPPERS } from './provider-models.js';
+import { routeModelTier } from './router.js';
+const matchesChoice = (tuple, choice) => tuple.group === choice.group && tuple.member === choice.member && tuple.model === choice.model && tuple.effort === choice.effort;
+function findWorkerModelRow(rows, model) {
+    const matches = rows?.filter(row => row.id === model || row.apiModelId === model) ?? [];
+    return matches.length === 1 ? matches[0] : undefined;
+}
+function workerCatalogDigest(catalog) {
+    if (!catalog.discovery)
+        return workerConfigDigest(catalog);
+    // Offline loads synthesize fetchedAt. Keep catalog facts and persisted
+    // observation/qualification times pinned, independent of the load clock.
+    const { fetchedAt, ...discovery } = catalog.discovery;
+    return workerConfigDigest({ ...catalog, discovery });
+}
+/** Pure S1 resolution. No probing, launch, activation, admission, or writes.
+ * Recheck against freshly loaded snapshots before preparing an invocation. */
+export function resolveWorkerPlan(snapshot, request) {
+    let parallelism = snapshot.config.parallelism ?? {};
+    const policy = snapshot.models.defaults.workerSelection;
+    const digests = {
+        ...snapshot.modelDigests,
+        configDigest: workerActivationDigests(snapshot.config).configDigest,
+        resolvedModelsDigest: workerConfigDigest(snapshot.models),
+        catalogDigest: workerCatalogDigest(snapshot.catalog),
+        profileDigest: workerConfigDigest([snapshot.registry, snapshot.installations]),
+        constraintsDigest: workerConfigDigest(snapshot.constraints),
+    };
+    const plan = {
+        mode: parallelism.worker_mode ?? 'direct', status: 'blocked', role: null, selected: null,
+        eligible: [], alternatives: [], exclusions: [], diagnostics: [], digests,
+        policy: structuredClone(policy), origins: structuredClone(snapshot.models.workerPolicyOrigins),
+        choice: null, capacity: 'conductor-guidance-only', ceilings: {},
+    };
+    const diagnostic = (code, pointer, message) => ({ code, pointer, message });
+    const block = (code, pointer, message) => {
+        plan.diagnostics.push(diagnostic(code, pointer, message));
+    };
+    if (!parallelism.worker_dispatch) {
+        plan.status = 'disabled';
+        block('OG_CONFIG_REFERENCE', '/parallelism/worker_dispatch', `Direct worker dispatch is off (parallelism.worker_dispatch). Enable with \`${WORKER_DISPATCH_ENABLE_COMMAND}\` `
+            + `(then check readiness with \`${WORKER_DISPATCH_READINESS_COMMAND}\`).`);
+        return plan;
+    }
+    const now = new Date(request.now);
+    if (!Number.isFinite(now.getTime()))
+        block('OG_CONFIG_REFERENCE', '/request/now', 'A valid current clock is required');
+    if (!request.context || typeof request.context.estimator !== 'string')
+        block('OG_CONFIG_REFERENCE', '/request/context', 'A named, bounded context estimate is required');
+    if (snapshot.constraints?.revokedModels?.some(key => !isCanonicalWorkerModelKey(key)))
+        block('OG_CONFIG_REFERENCE', '/constraints/revokedModels', 'Revocations require canonical inference model keys');
+    if (request.expectedDigests && (Object.keys(request.expectedDigests).length !== Object.keys(digests).length
+        || Object.entries(digests).some(([key, value]) => request.expectedDigests[key] !== value))) {
+        block('OG_CONFIG_REFERENCE', '/request/expectedDigests', 'Current input digests changed; resolve again');
+    }
+    if (Object.values(snapshot.modelDigests).length !== 3 || Object.values(digests).some(value => !/^sha256:[a-f0-9]{64}$/.test(value))) {
+        block('OG_CONFIG_REFERENCE', '/models', 'Current loader input digests are required');
+    }
+    if (plan.mode === 'managed') {
+        const activation = parallelism.activation;
+        if (!activation || ['configDigest', 'projectModelsDigest', 'userModelsDigest', 'builtinModelsDigest'].some(key => activation[key] !== digests[key])) {
+            block('OG_CONFIG_REFERENCE', '/parallelism/activation', 'Managed activation is missing or stale');
+        }
+    }
+    if (!policy)
+        block('OG_CONFIG_REFERENCE', '/defaults/workerSelection', 'Current merged worker policy is required');
+    const catalogErrors = validateWorkerCatalogDiscovery(snapshot.catalog.discovery);
+    if (catalogErrors.length)
+        block('OG_ADAPTER_UNQUALIFIED', '/catalog/discovery', catalogErrors.join('; '));
+    if (plan.diagnostics.length || !policy)
+        return plan;
+    const policyShape = WorkerSelectionPolicySchema.safeParse(policy);
+    if (!policyShape.success) {
+        block('OG_CONFIG_REFERENCE', '/defaults/workerSelection', policyShape.error.message);
+        return plan;
+    }
+    for (const message of validateWorkerGroupReferences(parallelism, policy))
+        block('OG_CONFIG_REFERENCE', '/parallelism', message);
+    if (plan.diagnostics.length)
+        return plan;
+    parallelism = resolveParallelism(parallelism, snapshot.config.providers?.[0]);
+    const ceilingLayers = [parallelism.budgets?.perRun, parallelism.budgets?.perTask,
+        { maxAttempts: parallelism.retry?.maxAttempts ?? 3 }, snapshot.constraints?.ceilings, request.ceilings];
+    for (const key of ['tokens', 'costUsd', 'wallSeconds', 'maxAttempts']) {
+        const values = ceilingLayers.map(layer => layer?.[key]).filter((value) => value !== undefined);
+        if (values.some(value => !Number.isFinite(value) || value < 0 || key !== 'costUsd' && !Number.isSafeInteger(value))) {
+            block('OG_CONFIG_REFERENCE', `/request/ceilings/${key}`, 'Ceilings must be finite nonnegative values; counts must be integers');
+        }
+        else if (values.length)
+            plan.ceilings[key] = Math.min(...values);
+    }
+    if (plan.ceilings.maxAttempts === 0)
+        block('OG_BUDGET_UNMEASURABLE', '/request/ceilings/maxAttempts', 'No task attempts remain');
+    const qualifiedRoles = {};
+    for (const [groupId, group] of Object.entries(parallelism.groups ?? {})) {
+        for (const member of group.members ?? []) {
+            const observed = findWorkerModelRow(snapshot.catalog.discovery?.instances?.[member.cli]?.models, member.model)?.worker;
+            qualifiedRoles[`${groupId}/${member.id}`] = observed?.qualification.status === 'qualified'
+                ? observed.qualification.roles.filter(role => ownWorkerRoleGuidance(policy, role)?.groups.includes(groupId)) : [];
+        }
+    }
+    // Qualification gaps are group-scoped: an unqualified group must not block a
+    // request that never considers it. Gaps are applied once the candidates are known.
+    const qualificationGaps = validateWorkerGroupQualifications(parallelism, qualifiedRoles).map(diagnostic => ({
+        ...diagnostic, message: `${diagnostic.message}. Run aiwg doctor --probe-workers --qualify.`,
+    }));
+    const gapGroup = (diagnostic) => diagnostic.pointer.split('/')[3] ?? '';
+    const taskRole = request.taskClass && policy.taskClasses && Object.hasOwn(policy.taskClasses, request.taskClass) ? policy.taskClasses[request.taskClass] : undefined;
+    const role = request.role ?? taskRole;
+    plan.role = role ?? null;
+    if (request.taskClass && (!taskRole || request.role && taskRole !== request.role))
+        block('OG_CONFIG_REFERENCE', '/request/taskClass', 'Unknown task class or conflicting role');
+    const guidance = role ? ownWorkerRoleGuidance(policy, role) : undefined;
+    if (!role || !guidance)
+        block('OG_CONFIG_REFERENCE', '/defaults/workerSelection/roleGuidance', 'Requested role has no guidance');
+    if (request.member && !request.group)
+        block('OG_CONFIG_REFERENCE', '/request/member', 'Group-local member pins require a group');
+    if (request.group && !guidance?.groups.includes(request.group))
+        block('OG_CONFIG_REFERENCE', '/request/group', 'Group is outside role guidance');
+    if ([request.maxParallel, snapshot.constraints?.maxParallel].some(value => value !== undefined && (!Number.isSafeInteger(value) || value < 0)))
+        block('OG_CONFIG_REFERENCE', '/request/maxParallel', 'Capacity ceilings must be nonnegative integers');
+    if (request.requireDifferentFamily && (!request.reviewOf || validateWorkerModelObservation(request.reviewOf).length
+        || hasSelectionRelevantConflicts(request.reviewOf) || !request.reviewOf.family || request.reviewOf.family === 'unknown')) {
+        block('OG_MODEL_UNAPPROVED', '/request/reviewOf', 'Required review needs unambiguous observed source lineage');
+    }
+    const candidateGroups = request.group ? [request.group] : guidance?.groups ?? [];
+    const unqualifiedGroups = new Set(qualificationGaps.map(gapGroup));
+    const qualifiedGroups = candidateGroups.filter(groupId => !unqualifiedGroups.has(groupId));
+    if (!qualifiedGroups.length) {
+        plan.diagnostics.push(...qualificationGaps.filter(gap => candidateGroups.includes(gapGroup(gap))));
+    }
+    else {
+        // Unpinned requests skip an unqualified guidance group visibly instead of failing the role.
+        for (const groupId of candidateGroups.filter(groupId => unqualifiedGroups.has(groupId))) {
+            const gaps = qualificationGaps.filter(gap => gapGroup(gap) === groupId);
+            for (const member of parallelism.groups?.[groupId]?.members ?? []) {
+                plan.exclusions.push({ group: groupId, member: member.id, model: member.model, effort: null, diagnostics: gaps });
+            }
+        }
+    }
+    if (plan.diagnostics.length || !role || !guidance)
+        return plan;
+    const baseRole = guidance.baseRole ?? role;
+    const wrapperPin = snapshot.models.agentOverrides[MODEL_WRAPPERS[baseRole]]?.['model-override'];
+    const groupPolicies = new Map();
+    const groups = qualifiedGroups;
+    for (const groupId of groups) {
+        const group = parallelism.groups[groupId];
+        const narrowed = mergeGroupWorkerPolicy(policy, group);
+        groupPolicies.set(groupId, narrowed.policy);
+        if (narrowed.diagnostics.length) {
+            plan.diagnostics.push(...narrowed.diagnostics);
+            continue;
+        }
+        const groupPolicy = narrowed.policy;
+        const permissions = { ...group.execution, transport: group.execution?.transport ?? 'shell' };
+        const transport = permissions.transport;
+        if (request.transport === 'mcp' && permissions.launchMode === 'native-sandbox') {
+            const reason = diagnostic('OG_POLICY_RELAXATION', `/parallelism/groups/${groupId}/execution/launchMode`, 'MCP worker-invoke does not support native-sandbox isolation. Use models resolve --transport shell and the shell launcher, or select a group with systemd-unit isolation.');
+            for (const member of group.members ?? [])
+                plan.exclusions.push({ group: groupId, member: member.id, model: member.model, effort: null, diagnostics: [reason] });
+            if (request.group === groupId)
+                plan.diagnostics.push(reason);
+            continue;
+        }
+        // Priority is guidance only. Preserve declaration order for ties; fallback order stays explicit.
+        const members = (group.members ?? []).map((member, index) => ({ member, index })).sort((a, b) => (a.member.priority ?? 100) - (b.member.priority ?? 100) || a.index - b.index);
+        for (const { member } of members) {
+            const binding = snapshot.installations[member.cli];
+            const discovery = snapshot.catalog.discovery?.instances?.[member.cli];
+            const row = findWorkerModelRow(discovery?.models, member.model);
+            const observation = row?.worker;
+            const efforts = request.effort !== undefined ? [request.effort]
+                : [...new Set([guidance.initialEffort, ...guidance.effortLadder])];
+            for (const effort of efforts) {
+                const tuple = { group: groupId, member: member.id, model: member.model, effort };
+                const reasons = [];
+                const deny = (code, pointer, message) => { reasons.push(diagnostic(code, pointer, message)); };
+                const pointer = `/parallelism/groups/${groupId}/members/${member.id}`;
+                if (request.transport !== undefined && request.transport !== transport)
+                    deny('OG_POLICY_RELAXATION', '/request/transport', 'Requested transport differs from resolved group permissions');
+                if (member.enabled === false || parallelism.clis?.[member.cli]?.enabled === false)
+                    deny('OG_CONFIG_REFERENCE', pointer, 'Member or installation is disabled');
+                if (!member.roles.includes(baseRole))
+                    deny('OG_CONFIG_REFERENCE', pointer, 'Member does not cover requested role');
+                const pinMismatch = request.member && request.member !== member.id || request.model && request.model !== member.model || wrapperPin && wrapperPin !== member.model;
+                const substitution = request.substitution && matchesChoice(tuple, request.substitution) && request.substitution.rationale.trim();
+                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. Run aiwg doctor --probe-workers --qualify.');
+                if (observation && binding && row?.llmProvider && row.apiModelId) {
+                    const shapeErrors = validateWorkerModelObservation(observation);
+                    if (shapeErrors.length) {
+                        deny('OG_ADAPTER_UNQUALIFIED', '/worker', shapeErrors.join('; '));
+                        plan.exclusions.push({ ...tuple, diagnostics: reasons });
+                        continue;
+                    }
+                    if (observation.cliId !== member.cli || observation.runtimeVersion !== binding.cliVersion
+                        || observation.accountScope !== binding.accountScope || observation.endpointFingerprint !== binding.endpointFingerprint
+                        || discovery?.accountBinding !== binding.accountScope || discovery?.runtimeVersion !== binding.cliVersion
+                        || parallelism.clis?.[member.cli]?.accountScope && parallelism.clis[member.cli].accountScope !== binding.accountScope) {
+                        deny('OG_ADAPTER_UNQUALIFIED', pointer, 'Catalog and current installation scope differ');
+                    }
+                    if (group.efforts && (effort === null || !group.efforts.includes(effort)))
+                        deny('OG_EFFORT_DENIED', pointer, 'Effort is outside group ceiling');
+                    reasons.push(...validateWorkerPolicyRoute({ policy: groupPolicy, role, inferenceProvider: row.llmProvider, apiModelId: row.apiModelId,
+                        selectedModel: member.model, effort, identityEvidence: binding.identityEvidence, observation,
+                        wrapperPin, ...(substitution ? { substitution: request.substitution } : {}), dataClass: request.dataClass, now, context: request.context }));
+                    if (request.requireDifferentFamily && (observation.family === 'unknown' || observation.family === request.reviewOf.family))
+                        deny('OG_MODEL_UNAPPROVED', '/worker/family', 'Required review must use a different observed family');
+                    try {
+                        const { adapter } = resolveWorkerGroupInstallation(parallelism, member.cli, snapshot.registry);
+                        const configuredProfile = parallelism.clis?.[member.cli]?.invocationProfile;
+                        const profilePointer = `/parallelism/clis/${member.cli}/invocationProfile`;
+                        if (configuredProfile && !Object.hasOwn(adapter.invocationProfiles ?? {}, configuredProfile)) {
+                            deny('OG_CONFIG_REFERENCE', profilePointer, 'Configured invocation profile is not registered for this adapter; select a registered profile.');
+                        }
+                        else if (configuredProfile && configuredProfile !== binding.profile) {
+                            deny('OG_PIN_MISMATCH', profilePointer, 'Configured invocation profile differs from installation qualification; qualify the selected profile again.');
+                        }
+                        const configuredServer = parallelism.clis?.[member.cli]?.mcpServerRef;
+                        if (transport === 'mcp' && configuredServer && configuredServer !== binding.mcp?.serverRef)
+                            throw new Error('Configured MCP server changed');
+                        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 (!hasOperatorWorkerNativeRenderer(adapter) && group.execution?.sandbox && !adapter.capabilities.sandboxModes.includes(group.execution.sandbox))
+                            throw new Error('Requested sandbox mode is unqualified');
+                        assertWorkerLaunchMode(adapter, permissions);
+                        qualifyWorkerInvocationProfile(adapter, { profile: binding.profile, transport, cliVersion: binding.cliVersion,
+                            policy, permissions, effort, boundary: binding.boundary,
+                            requiredControls: request.requiredControls, mcp: binding.mcp });
+                        if (hasOperatorWorkerNativeRenderer(adapter) && transport === 'shell' && permissions.sandbox === 'external') {
+                            reasons.push({ code: 'OG_SANDBOX_EXTERNAL', blocking: false,
+                                pointer: `/parallelism/groups/${groupId}/execution/sandbox`,
+                                message: `${adapter.provider} CLI's own sandbox is disabled by explicit external policy; isolation relies on the per-task worktree and launcher resource scope.` });
+                        }
+                        const { maxAttempts: _maxAttempts, ...budgetLimits } = plan.ceilings;
+                        const budgetDimensions = { tokens: 'tokens', cost: 'costUsd', 'wall-time': 'wallSeconds' };
+                        const enforceable = adapter.capabilities.hardBudget.map(key => budgetDimensions[key]);
+                        for (const message of validateWorkerBudgetEnforcement({ ...parallelism.budgets, perTask: budgetLimits }, enforceable))
+                            deny('OG_BUDGET_UNMEASURABLE', '/parallelism/budgets', message);
+                    }
+                    catch (error) {
+                        deny('OG_ADAPTER_UNQUALIFIED', pointer, String(error));
+                    }
+                    let key;
+                    try {
+                        key = workerModelKey(row.llmProvider, row.apiModelId);
+                    }
+                    catch {
+                        plan.exclusions.push({ ...tuple, diagnostics: reasons });
+                        continue;
+                    }
+                    if (snapshot.constraints?.revokedModels?.includes(key))
+                        deny('OG_MODEL_UNAPPROVED', '/constraints/revokedModels', 'Current model revocation');
+                    if (snapshot.constraints?.unavailableMembers?.includes(`${groupId}/${member.id}`))
+                        deny('OG_ADAPTER_UNQUALIFIED', pointer, 'Member is currently unavailable');
+                    const premium = ['premium', 'max-quality'].includes(guidance.tier) || observation.pricing.costClass === 'premium';
+                    // Worker candidates always invoke a model; deterministic/routine hints must not bypass premium authority.
+                    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('; ')}; 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],
+                        parallelism.admission?.modelCaps?.[key], installation && parallelism.admission?.quotaCaps?.[installation.quotaScope],
+                        snapshot.constraints?.maxParallel, request.maxParallel].filter((value) => value !== undefined);
+                    const effectiveMaxParallel = caps.length ? Math.min(...caps) : null;
+                    if (effectiveMaxParallel === 0)
+                        deny('OG_ADAPTER_UNQUALIFIED', '/constraints/maxParallel', 'Current capacity ceiling is zero');
+                    if (!reasons.some(reason => reason.blocking !== false))
+                        plan.eligible.push({ ...tuple, cli: member.cli,
+                            inferenceProvider: row.llmProvider, modelKey: key, family: observation.family, identityEvidence: binding.identityEvidence,
+                            profile: binding.profile, transport,
+                            permissions: structuredClone(permissions), context: workerContextHeadroom(request.context, observation),
+                            observedAt: observation.observedAt, verifiedAt: observation.verifiedAt, observationRef: observation.recordId,
+                            effectiveMaxParallel, diagnostics: reasons });
+                }
+                if (reasons.some(reason => reason.blocking !== false))
+                    plan.exclusions.push({ ...tuple, diagnostics: reasons });
+            }
+        }
+    }
+    if (request.choice) {
+        if (!request.choice.rationale.trim())
+            block('OG_CONFIG_REFERENCE', '/request/choice/rationale', 'Conductor choice requires a rationale');
+        plan.selected = plan.eligible.find(tuple => matchesChoice(tuple, request.choice)) ?? null;
+        if (!plan.selected)
+            block('OG_MODEL_UNAPPROVED', '/request/choice', 'Conductor choice is outside the eligible set');
+    }
+    else
+        plan.selected = plan.eligible[0] ?? null;
+    if (plan.diagnostics.length)
+        plan.selected = null;
+    if (plan.selected) {
+        plan.policy = groupPolicies.get(plan.selected.group);
+        plan.status = 'eligible';
+        plan.diagnostics.push(...plan.selected.diagnostics.filter(item => item.code === 'OG_SANDBOX_EXTERNAL'));
+        plan.choice = { source: request.choice ? 'conductor' : 'default', rationale: request.choice?.rationale ?? 'Role group order, member priority/declaration order, then qualified effort ladder',
+            ...(request.substitution && matchesChoice(plan.selected, request.substitution) ? { substitution: structuredClone(request.substitution) } : {}) };
+    }
+    plan.alternatives = plan.eligible.filter(tuple => tuple !== plan.selected);
+    return plan;
+}
+//# sourceMappingURL=worker-plan.js.map

package/dist/src/models/worker-selection-policy.js

@@ -0,0 +1,217 @@
+// Validates and merges worker selection restrictions and constrained role aliases.
+import { z } from 'zod';
+import { validLocalOnlyPath } from './conductor-data-policy.mjs';
+import { integer } from '../schema/zod-validation.mjs';
+const uniqueStrings = z.array(z.string().min(1)).refine(values => new Set(values).size === values.length, 'Duplicate entries');
+const WorkerDataPolicySchema = z.strictObject({
+    localOnlyPaths: uniqueStrings.refine(values => values.every(validLocalOnlyPath), 'Expected literal project-relative paths').optional(),
+    allowedProcessing: z.array(z.enum(['local', 'remote'])).refine(values => new Set(values).size === values.length).optional(),
+    allowProductImprovement: z.boolean().optional(),
+    allowUnknown: z.boolean().optional(),
+    maxRetentionDays: integer().nonnegative().optional(),
+});
+const baseRoles = ['efficiency', 'coding', 'reasoning'];
+const WorkerRoleSchema = z.strictObject({
+    baseRole: z.enum(baseRoles).optional(),
+    groups: uniqueStrings.refine(values => values.length > 0),
+    tier: z.enum(['economy', 'standard', 'premium', 'max-quality']),
+    initialEffort: z.string().min(1).nullable(),
+    effortLadder: uniqueStrings,
+    escalateAfter: integer().positive().optional(),
+    maxEscalations: integer().nonnegative().optional(),
+    deescalateAfter: integer().positive().optional(),
+    allowNotApplicableEffort: z.boolean().optional(),
+});
+const reservedRoleKey = (key) => key === 'prototype' || Object.hasOwn(Object.prototype, key);
+const roleGuidanceSchema = z.preprocess((input, context) => {
+    if (input !== null && typeof input === 'object')
+        for (const role of Object.keys(input)) {
+            if (reservedRoleKey(role))
+                context.addIssue({ code: 'custom', path: [role], message: `Reserved worker role alias key: ${role}` });
+        }
+    return input;
+}, z.record(z.string().regex(/^[a-z][a-z0-9-]{0,62}$/), WorkerRoleSchema));
+/** Inherited object members never constitute configured role guidance. */
+export function ownWorkerRoleGuidance(policy, role) {
+    return policy?.roleGuidance && Object.hasOwn(policy.roleGuidance, role) ? policy.roleGuidance[role] : undefined;
+}
+export const WorkerSelectionPolicySchema = z.strictObject({
+    roleGuidance: roleGuidanceSchema.optional(),
+    guards: z.strictObject({
+        deniedEfforts: uniqueStrings.optional(),
+        deniedModels: uniqueStrings.optional(),
+        denySelfDelegation: z.boolean().optional(),
+        requireExactModel: z.boolean().optional(),
+        allowedVisibility: z.array(z.enum(['listed', 'hidden'])).refine(v => new Set(v).size === v.length).optional(),
+        allowedLifecycle: z.array(z.enum(['active', 'deprecated'])).refine(v => new Set(v).size === v.length).optional(),
+        minimumIdentityEvidence: z.enum(['runtime-configured', 'backend-attested']).optional(),
+    }).optional(),
+    dataPolicy: WorkerDataPolicySchema.optional(),
+    dataClasses: z.record(z.string().regex(/^[a-z][a-z0-9-]{0,62}$/), WorkerDataPolicySchema).optional(),
+    freshness: z.strictObject({
+        warnHours: integer().positive().optional(),
+        blockHours: integer().positive().optional(),
+        policyDays: integer().positive().optional(),
+    }).optional(),
+    taskClasses: z.record(z.string().regex(/^[a-z][a-z0-9-]{0,62}$/), z.string().min(1)).optional(),
+}).superRefine((policy, context) => {
+    for (const [role, guidance] of Object.entries(policy.roleGuidance ?? {})) {
+        if (baseRoles.includes(role) ? guidance.baseRole !== undefined : guidance.baseRole === undefined)
+            context.addIssue({ code: 'custom', path: ['roleGuidance', role], message: 'Unknown worker role requires a baseRole; base roles cannot be aliases' });
+        const base = guidance.baseRole && ownWorkerRoleGuidance(policy, guidance.baseRole);
+        if (base)
+            for (const message of aliasRestrictionErrors(guidance, base))
+                context.addIssue({ code: 'custom', path: ['roleGuidance', role], message });
+        if (guidance.effortLadder.includes('none') || (guidance.initialEffort === 'none' ? guidance.effortLadder.length !== 0 : guidance.initialEffort !== null && !guidance.effortLadder.includes(guidance.initialEffort))) {
+            context.addIssue({ code: 'custom', path: ['roleGuidance', role], message: 'Initial effort must belong to the ladder; real none requires an empty ladder' });
+        }
+        if (guidance.initialEffort === null && (guidance.allowNotApplicableEffort !== true || guidance.effortLadder.length !== 0)) {
+            context.addIssue({ code: 'custom', path: ['roleGuidance', role], message: 'Null effort requires an empty ladder and allowNotApplicableEffort=true' });
+        }
+    }
+    for (const key of policy.guards?.deniedModels ?? []) {
+        if (!isCanonicalWorkerModelKey(key))
+            context.addIssue({ code: 'custom', path: ['guards', 'deniedModels'], message: 'Noncanonical inference model key' });
+    }
+    if (policy.freshness?.warnHours !== undefined && policy.freshness.blockHours !== undefined && policy.freshness.warnHours > policy.freshness.blockHours) {
+        context.addIssue({ code: 'custom', path: ['freshness'], message: 'warnHours must not exceed blockHours' });
+    }
+    for (const role of Object.values(policy.taskClasses ?? {})) {
+        if (!baseRoles.includes(role) && !ownWorkerRoleGuidance(policy, role)?.baseRole)
+            context.addIssue({ code: 'custom', path: ['taskClasses'], message: 'Unknown worker role' });
+    }
+});
+/** Aliases may reorder/subset choices, never change base authority or escalation controls. */
+function aliasRestrictionErrors(alias, base) {
+    const errors = [];
+    if (alias.groups.some(group => !base.groups.includes(group)))
+        errors.push('Alias groups widen base role');
+    if (alias.effortLadder.some(effort => !base.effortLadder.includes(effort))
+        || alias.initialEffort === 'none' && base.initialEffort !== 'none'
+        || alias.initialEffort === null && base.initialEffort !== null
+        || alias.allowNotApplicableEffort === true && base.allowNotApplicableEffort !== true)
+        errors.push('Alias effort choices widen base role');
+    if (alias.tier !== base.tier)
+        errors.push('Alias tier must retain base role authority');
+    if ((alias.maxEscalations ?? base.maxEscalations ?? 2) > (base.maxEscalations ?? 2))
+        errors.push('Alias maxEscalations widens base role');
+    for (const key of ['escalateAfter', 'deescalateAfter']) {
+        if (alias[key] !== undefined && alias[key] !== (base[key] ?? 2))
+            errors.push(`Alias ${key} must retain base role control`);
+    }
+    return errors;
+}
+/** Canonical RFC3986 identity; installation and account never enter the key. */
+export function workerModelKey(inferenceProvider, apiModelId) {
+    if (!/^[a-z][a-z0-9-]{0,62}$/.test(inferenceProvider) || !apiModelId)
+        throw new Error('OG_CONFIG_REFERENCE: invalid inference model identity');
+    return `${inferenceProvider}/${encodeURIComponent(apiModelId).replace(/[!'()*]/g, c => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)}`;
+}
+export function isCanonicalWorkerModelKey(key) {
+    const slash = key.indexOf('/');
+    try {
+        return slash > 0 && workerModelKey(key.slice(0, slash), decodeURIComponent(key.slice(slash + 1))) === key;
+    }
+    catch {
+        return false;
+    }
+}
+export const DEFAULT_WORKER_SELECTION = {
+    guards: { deniedEfforts: ['ultra'], deniedModels: [], denySelfDelegation: true, requireExactModel: true, allowedVisibility: ['listed'], allowedLifecycle: ['active'], minimumIdentityEvidence: 'runtime-configured' },
+    dataPolicy: { allowedProcessing: ['local', 'remote'], allowProductImprovement: false, allowUnknown: false },
+    freshness: { warnHours: 24, blockHours: 168, policyDays: 30 },
+    taskClasses: { inventory: 'efficiency', implementation: 'coding', architecture: 'reasoning', review: 'reasoning' },
+};
+/** Merge leaves, preserving pre-merge explicit origins and attempted relaxations. */
+export function mergeWorkerSelection(layers) {
+    const policy = Object.create(null);
+    const origins = Object.create(null);
+    const diagnostics = [];
+    const visit = (target, input, parts, layer) => {
+        for (const [key, value] of Object.entries(input)) {
+            const path = [...parts, key];
+            const pointer = `/defaults/workerSelection/${path.map(p => p.replace(/~/g, '~0').replace(/\//g, '~1')).join('/')}`;
+            if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+                if (!Object.hasOwn(target, key))
+                    target[key] = Object.create(null);
+                visit(target[key], value, path, layer);
+                continue;
+            }
+            const origin = { source: layer.source, authority: layer.authority, digest: layer.digest, pointer, contribution: structuredClone(value) };
+            const prior = origins[pointer] ?? [];
+            const explicit = prior.filter(o => o.authority !== 'builtin');
+            let effective = structuredClone(value);
+            let relaxation = false;
+            if (layer.authority !== 'builtin' && explicit.length > 0) {
+                const previous = target[key];
+                if (['deniedEfforts', 'deniedModels', 'localOnlyPaths'].includes(key))
+                    effective = [...new Set([...previous, ...value])];
+                else if (['allowedVisibility', 'allowedLifecycle', 'allowedProcessing'].includes(key)) {
+                    relaxation = value.some((v) => !previous.includes(v));
+                    effective = previous.filter((v) => value.includes(v));
+                }
+                else if (['denySelfDelegation', 'requireExactModel'].includes(key)) {
+                    relaxation = previous === true && value === false;
+                    effective = previous || value;
+                }
+                else if (['allowUnknown', 'allowProductImprovement'].includes(key)) {
+                    relaxation = previous === false && value === true;
+                    effective = previous && value;
+                }
+                else if (['maxRetentionDays', 'warnHours', 'blockHours', 'policyDays'].includes(key)) {
+                    relaxation = value > previous;
+                    effective = Math.min(previous, value);
+                }
+                else if (key === 'minimumIdentityEvidence') {
+                    relaxation = previous === 'backend-attested' && value !== previous;
+                    effective = previous === 'backend-attested' ? previous : value;
+                }
+            }
+            if (relaxation)
+                diagnostics.push({ code: 'OG_POLICY_RELAXATION', pointer, message: 'Explicit restriction cannot relax an inherited restriction', origins: [...explicit, origin] });
+            target[key] = effective;
+            origins[pointer] = [...prior, origin];
+        }
+    };
+    for (const layer of layers)
+        if (layer.policy) {
+            for (const [role, guidance] of Object.entries(layer.policy.roleGuidance ?? {})) {
+                if (!guidance.baseRole)
+                    continue;
+                const previous = ownWorkerRoleGuidance(policy, role);
+                if (layer.authority !== 'project' || previous?.baseRole && previous.baseRole !== guidance.baseRole)
+                    diagnostics.push({
+                        code: 'OG_POLICY_RELAXATION', pointer: `/defaults/workerSelection/roleGuidance/${role}/baseRole`,
+                        message: 'Only project layers may declare constrained aliases; inherited aliases cannot change baseRole',
+                    });
+            }
+            visit(policy, layer.policy, [], layer);
+        }
+    for (const [role, guidance] of Object.entries(policy.roleGuidance ?? {})) {
+        const base = guidance.baseRole && ownWorkerRoleGuidance(policy, guidance.baseRole);
+        if (base)
+            for (const field of ['maxEscalations', 'escalateAfter', 'deescalateAfter'])
+                guidance[field] ??= base[field];
+        if (guidance.baseRole && !base)
+            diagnostics.push({
+                code: 'OG_CONFIG_REFERENCE', pointer: `/defaults/workerSelection/roleGuidance/${role}/baseRole`, message: 'Alias base role has no guidance',
+            });
+    }
+    const validation = WorkerSelectionPolicySchema.safeParse(policy);
+    if (!validation.success)
+        for (const issue of validation.error.issues)
+            diagnostics.push({ code: 'OG_CONFIG_REFERENCE', pointer: `/defaults/workerSelection/${issue.path.join('/')}`, message: issue.message });
+    // Data classes are applied as further restrictions to the base path.
+    for (const dataClass of Object.values(policy.dataClasses ?? {})) {
+        const base = policy.dataPolicy ?? {};
+        if (dataClass.allowedProcessing)
+            dataClass.allowedProcessing = dataClass.allowedProcessing.filter(p => !base.allowedProcessing || base.allowedProcessing.includes(p));
+        for (const key of ['allowUnknown', 'allowProductImprovement'])
+            if (base[key] === false)
+                dataClass[key] = false;
+        if (base.maxRetentionDays !== undefined)
+            dataClass.maxRetentionDays = Math.min(dataClass.maxRetentionDays ?? base.maxRetentionDays, base.maxRetentionDays);
+    }
+    return { policy, origins, diagnostics };
+}
+//# sourceMappingURL=worker-selection-policy.js.map

package/dist/src/models/wrapper-deployment.js

@@ -156,7 +156,7 @@ export async function verifyModelWrapperDeployment(agentsPath, expectation = {})
     const missing = [];
     const mismatches = [];
     for (const [role, wrapper] of expected) {
-        const matches = files.filter(file => path.basename(file).replace(/\.(?:md|toml|json|yaml|yml)$/i, '') === wrapper);
+        const matches = files.filter(file => path.basename(file).replace(/(?:\.agent)?\.(?:md|toml|json|yaml|yml)$/i, '') === wrapper);
         if (matches.length === 0) {
             missing.push(wrapper);
             continue;