@aiwg/cli 2026.10.1 → 2026.10.3

package/dist/src/mission-protocol/types.js

@@ -1,2 +1,112 @@
 export const MISSION_API_VERSION = 'mission.aiwg.io/v1';
+// Worker dispatch payloads merged from 05 §5.1 into schemas/mission-v1.schema.json.
+// The schema file is the executable contract; these types mirror its shapes.
+export const WORKER_CONTRACT_REVISION = 1;
+export const WORKER_BASELINE_FEATURES = [
+    'worker-dispatch.v1',
+    'worker-policy-origins.v1',
+    'worker-admission-fencing.v1',
+    'worker-claims.v1',
+    'worker-activation.v1',
+];
+export const WORKER_OPTIONAL_FEATURES = ['worker-health.v1'];
+/** Adapter capability additionally required before Flow invokeNode. */
+export const WORKER_FLOW_VALUE_FEATURE = 'worker-flow-values.v1';
+export const WORKER_KNOWN_FEATURES = [
+    ...WORKER_BASELINE_FEATURES,
+    ...WORKER_OPTIONAL_FEATURES,
+    WORKER_FLOW_VALUE_FEATURE,
+];
+export const WORKER_DEFINITIONS = [
+    'workerArtifact',
+    'workerEffort',
+    'workerTuple',
+    'workerLimits',
+    'workerSelectionIntent',
+    'workerBrief',
+    'workerClaims',
+    'workerUsage',
+    'workerExecution',
+    'workerVerification',
+    'workerResult',
+    'workerDispatch',
+    'workerDirectIntent',
+    'workerDirectBrief',
+    'workerResolvedInvocation',
+    'workerDirectVerification',
+    'workerDirectResult',
+    'workerHealthSummary',
+    'workerEffectiveHealth',
+];
+export const WORKER_DEFINITION_PRODUCERS = {
+    workerArtifact: 'shared-component',
+    workerEffort: 'shared-component',
+    workerTuple: 'shared-component',
+    workerLimits: 'shared-component',
+    workerSelectionIntent: 'conductor',
+    workerBrief: 'conductor',
+    workerClaims: 'worker',
+    workerUsage: 'shared-component',
+    workerExecution: 'adapter',
+    workerVerification: 'verifier',
+    workerResult: 'trusted-assembly',
+    workerDispatch: 'conductor',
+    workerDirectIntent: 'conductor',
+    workerDirectBrief: 'conductor',
+    workerResolvedInvocation: 'conductor',
+    workerDirectVerification: 'verifier',
+    workerDirectResult: 'trusted-assembly',
+    workerHealthSummary: 'shared-component',
+    workerEffectiveHealth: 'shared-component',
+};
+/** Bounded activity-log transition summary budget (UTF-8 bytes, marker included). */
+export const HEALTH_ACTIVITY_SUMMARY_MAX_UTF8_BYTES = 1024;
+/**
+ * Closed observer reason-code allowlist for activity summaries. Mirrors the
+ * `reasons` set in tools/ralph-external/lib/worker-health.mjs: B-OG-50 owns
+ * the observer set, B-OG-54 owns this mapping allowlist; extend them together.
+ * Unlisted codes project as UNCLASSIFIED#digest so free text (and any secret
+ * material it carries) never crosses into the shared trace.
+ */
+export const HEALTH_KNOWN_REASON_CODES = [
+    'OK',
+    'AWAITING_HANDSHAKE',
+    'PROCESS_ONLY',
+    'ACCEPTED',
+    'PROGRESS',
+    'QUIET',
+    'NO_PROGRESS',
+    'STARTUP_DEADLINE',
+    'HARD_DEADLINE',
+    'STEP_LIMIT',
+    'AUTH',
+    'RATE_LIMIT',
+    'NETWORK',
+    'MODEL',
+    'TRUST',
+    'STDIN_WAIT',
+    'SANDBOX',
+    'NOT_FOUND',
+    'RESOURCE',
+    'PROVIDER_ERROR',
+    'CRASH',
+    'EXIT_ERROR',
+    'FINAL_INVALID',
+    'CANCELLED',
+    'DISCONNECTED',
+    'OBSERVER_GAP',
+    'CAPTURE_WRITE',
+    'OUTPUT_LIMIT',
+    'MALFORMED_FRAME',
+    'SOURCE_GAP',
+    'IDENTITY_CHANGED',
+];
+export class WorkerContractError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'WorkerContractError';
+        this.code = code;
+    }
+}
 //# sourceMappingURL=types.js.map

package/dist/src/mission-protocol/worker-status.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=worker-status.js.map

package/dist/src/models/config-loader.js

@@ -9,15 +9,18 @@ import { readFile } from 'fs/promises';
 import { resolve } from 'path';
 import { homedir } from 'os';
 import { existsSync } from 'fs';
-import { validateUserProjectModelConfig } from './provider-policy.js';
+import { workerConfigDigest, validateWorkerGroupReferences } from '../config/aiwg-config.js';
+import { DEFAULT_WORKER_SELECTION, mergeWorkerSelection, WorkerSelectionPolicySchema, validateUserProjectModelConfig } from './provider-policy.js';
 /**
  * Loads and merges model configurations
  */
 export class ConfigLoader {
     cache = null;
+    cacheDigest = null;
+    inputDigests = null;
     locations;
-    constructor(projectPath) {
-        const aiwgHome = process.env.AIWG_HOME || resolve(homedir(), '.local/share/ai-writing-guide');
+    constructor(projectPath, options) {
+        const aiwgHome = options?.aiwgHome || process.env.AIWG_HOME || resolve(homedir(), '.local/share/ai-writing-guide');
         const userConfigDir = process.env.AIWG_CONFIG || resolve(homedir(), '.config/aiwg');
         this.locations = {
             aiwgDefault: resolve(aiwgHome, 'agentic/code/frameworks/sdlc-complete/config/models-v2.json'),
@@ -29,17 +32,65 @@ export class ConfigLoader {
      * Load and merge all configurations
      * Precedence: project > user > AIWG default
      */
-    async load() {
-        if (this.cache) {
-            return this.cache;
-        }
+    async load(parallelism) {
         // Load all configs
         const aiwgDefault = await this.loadAiwgDefault();
         const userConfig = await this.loadUserConfig();
         const projectConfig = await this.loadProjectConfig();
+        const digest = workerConfigDigest([aiwgDefault, userConfig, projectConfig, parallelism]);
+        if (this.cache && this.cacheDigest === digest)
+            return this.cache;
         // Merge with precedence
         const merged = this.merge(aiwgDefault, userConfig, projectConfig);
+        // A group-bound wrapper's inherited exact pin survives a higher-precedence
+        // tier-only preference. Preserve the legacy unbound merge otherwise.
+        if (parallelism?.worker_dispatch) {
+            for (const [agent, override] of Object.entries(projectConfig?.agentOverrides ?? {})) {
+                merged.agentOverrides[agent] = { ...userConfig?.agentOverrides?.[agent], ...override };
+            }
+        }
+        if (parallelism?.worker_dispatch || [aiwgDefault, userConfig, projectConfig].some(config => config?.defaults?.workerSelection !== undefined)) {
+            const result = mergeWorkerSelection([
+                { source: this.locations.aiwgDefault, authority: 'builtin', digest: workerConfigDigest(aiwgDefault), policy: DEFAULT_WORKER_SELECTION },
+                { source: this.locations.aiwgDefault, authority: 'builtin', digest: workerConfigDigest(aiwgDefault), policy: aiwgDefault.defaults.workerSelection },
+                { source: this.locations.userConfig, authority: 'user', digest: workerConfigDigest(userConfig), policy: userConfig?.defaults?.workerSelection },
+                { source: this.locations.projectConfig, authority: 'project', digest: workerConfigDigest(projectConfig), policy: projectConfig?.defaults?.workerSelection },
+            ]);
+            if (result.diagnostics.length)
+                throw new Error(result.diagnostics.map(d => `${d.code}: ${d.pointer}: ${d.message}; origins=${JSON.stringify(d.origins ?? [])}`).join('; '));
+            merged.defaults.workerSelection = result.policy;
+            merged.workerPolicyOrigins = result.origins;
+        }
+        if (parallelism?.worker_dispatch) {
+            // Exact wrapper pins remain explainable alongside worker restrictions.
+            for (const layer of [
+                { config: userConfig, source: this.locations.userConfig, authority: 'user' },
+                { config: projectConfig, source: this.locations.projectConfig, authority: 'project' },
+            ]) {
+                for (const [agent, override] of Object.entries(layer.config?.agentOverrides ?? {})) {
+                    if (override['model-override'] === undefined)
+                        continue;
+                    const pointer = `/agentOverrides/${agent.replace(/~/g, '~0').replace(/\//g, '~1')}/model-override`;
+                    merged.workerPolicyOrigins[pointer] ??= [];
+                    merged.workerPolicyOrigins[pointer].push({
+                        source: layer.source, authority: layer.authority, digest: workerConfigDigest(layer.config),
+                        pointer, contribution: override['model-override'],
+                    });
+                }
+            }
+            const errors = validateWorkerGroupReferences(parallelism, merged.defaults.workerSelection);
+            if (errors.length)
+                throw new Error(errors.join('; '));
+        }
+        // Publish only a fully validated candidate. A failed merge must not become
+        // a cache hit on the next read, nor replace the prior inspectable value.
         this.cache = merged;
+        this.cacheDigest = digest;
+        this.inputDigests = {
+            builtinModelsDigest: workerConfigDigest(aiwgDefault),
+            userModelsDigest: workerConfigDigest(userConfig),
+            projectModelsDigest: workerConfigDigest(projectConfig),
+        };
         return merged;
     }
     /**
@@ -53,6 +104,8 @@ export class ConfigLoader {
             if (!config.version || !config.tiers || !config.providers) {
                 throw new Error('Invalid AIWG default config: missing required v2 fields');
             }
+            if (config.defaults?.workerSelection !== undefined)
+                WorkerSelectionPolicySchema.parse(config.defaults.workerSelection);
             return config;
         }
         catch (error) {
@@ -63,9 +116,6 @@ export class ConfigLoader {
      * Load user configuration (optional)
      */
     async loadUserConfig() {
-        if (!existsSync(this.locations.userConfig)) {
-            return null;
-        }
         try {
             const content = await readFile(this.locations.userConfig, 'utf-8');
             const parsed = JSON.parse(content);
@@ -76,6 +126,8 @@ export class ConfigLoader {
             return parsed;
         }
         catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
             throw new Error(`Invalid user model config ${this.locations.userConfig}: ${error}`);
         }
     }
@@ -83,9 +135,6 @@ export class ConfigLoader {
      * Load project configuration (optional)
      */
     async loadProjectConfig() {
-        if (!existsSync(this.locations.projectConfig)) {
-            return null;
-        }
         try {
             const content = await readFile(this.locations.projectConfig, 'utf-8');
             const parsed = JSON.parse(content);
@@ -96,6 +145,8 @@ export class ConfigLoader {
             return parsed;
         }
         catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
             throw new Error(`Invalid project model config ${this.locations.projectConfig}: ${error}`);
         }
     }
@@ -217,6 +268,12 @@ export class ConfigLoader {
      */
     clearCache() {
         this.cache = null;
+        this.cacheDigest = null;
+        this.inputDigests = null;
+    }
+    /** Digests of the last successful read; no marker or snapshot writes. */
+    getInputDigests() {
+        return this.inputDigests ? { ...this.inputDigests } : null;
     }
     /**
      * Get configuration file locations

package/dist/src/models/grok-build-models.js

@@ -33,6 +33,8 @@ function stringArray(value) {
     if (!text.startsWith('[') || !text.endsWith(']'))
         return undefined;
     const matches = [...text.matchAll(/"((?:\\.|[^"\\])*)"|'([^']*)'/g)];
+    if (!/^\[\s*(?:s\s*(?:,\s*s\s*)*,?\s*)?\]$/.test(text.replace(/"((?:\\.|[^"\\])*)"|'([^']*)'/g, 's')))
+        return undefined;
     return matches.map(match => match[1] !== undefined
         ? JSON.parse(`"${match[1]}"`)
         : match[2]);
@@ -55,17 +57,25 @@ function mapKeys(value) {
 }
 /** Parse only non-secret fields needed for model discovery. */
 export function parseGrokBuildModelConfig(text, scope) {
-    const parsed = { models: new Map(), projectModelFields: false };
+    const parsed = { models: new Map(), projectModelFields: false, diagnostics: [] };
     let table = '';
-    for (const raw of text.split(/\r?\n/)) {
+    for (const [index, raw] of text.split(/\r?\n/).entries()) {
+        const invalid = (field) => parsed.diagnostics.push(`line ${index + 1}: malformed ${field}`);
         const nextTable = tableName(raw);
         if (nextTable !== undefined) {
             table = nextTable;
             continue;
         }
+        if (/^\s*\[models?(?:[.\]\s]|$)/.test(raw)) {
+            invalid('model table');
+            continue;
+        }
         const match = raw.match(/^\s*([A-Za-z0-9_-]+)\s*=\s*(.*?)\s*(?:#.*)?$/);
-        if (!match)
+        if (!match) {
+            if (/^models?(?:\.|$)/.test(table) && raw.trim() && !raw.trim().startsWith('#'))
+                invalid('model setting');
             continue;
+        }
         const [, key, value] = match;
         const top = table.split('.', 1)[0];
         if (scope === 'project' && !PROJECT_ALLOWED.has(top)) {
@@ -80,6 +90,10 @@ export function parseGrokBuildModelConfig(text, scope) {
                 parsed.allowedModels = stringArray(value);
             else if (key === 'disabled_models')
                 parsed.disabledModels = stringArray(value);
+            if (key === 'default' && !parsed.defaultModel
+                || key === 'allowed_models' && !parsed.allowedModels
+                || key === 'disabled_models' && !parsed.disabledModels)
+                invalid(key);
             continue;
         }
         const alias = modelAlias(table);
@@ -108,49 +122,76 @@ export function parseGrokBuildModelConfig(text, scope) {
             model.supportsBackendSearch = value.trim() === 'true';
         else if (key === 'reasoning_efforts')
             model.reasoningEfforts = stringArray(value);
+        if (['model', 'name', 'base_url', 'api_base_url'].includes(key) && unquote(value) === undefined
+            || key === 'env_key' && unquote(value) === undefined && stringArray(value) === undefined
+            || ['hidden', 'supports_backend_search'].includes(key) && !/^(true|false)$/.test(value.trim())
+            || key === 'context_window' && (!Number.isSafeInteger(Number(value)) || Number(value) < 1)
+            || key === 'reasoning_efforts' && !model.reasoningEfforts)
+            invalid(key);
         parsed.models.set(alias, model);
     }
     return parsed;
 }
-function inspectLayers(report) {
+function inspectLayers(report, diagnostics) {
     const sources = (report.configSources ?? report.config_sources);
-    if (!sources || !Array.isArray(sources.layers))
+    if (!sources || !Array.isArray(sources.layers)) {
+        if (sources !== undefined)
+            diagnostics.push('Grok Build /configSources/layers: expected array');
         return [];
+    }
     return sources.layers.flatMap((entry, index) => {
-        if (!entry || typeof entry !== 'object')
+        if (!entry || typeof entry !== 'object') {
+            diagnostics.push(`Grok Build /configSources/layers/${index}: malformed config layer`);
             return [];
+        }
         const item = entry;
-        return typeof item.role === 'string' && typeof item.path === 'string'
-            ? [{ role: item.role, path: item.path, ...(typeof item.note === 'string' ? { note: item.note } : {}), precedence: index + 1 }]
-            : [];
-    });
-}
-function inspectModels(report) {
-    const candidates = [report.models, report.modelCatalog, report.model_catalog]
-        .find(Array.isArray);
-    if (!candidates)
-        return [];
-    return candidates.flatMap(entry => {
-        if (typeof entry === 'string')
-            return [{ id: entry, alias: entry }];
-        if (!entry || typeof entry !== 'object')
+        if (typeof item.role !== 'string' || !item.role || typeof item.path !== 'string' || !item.path) {
+            diagnostics.push(`Grok Build /configSources/layers/${index}: missing role or path`);
             return [];
-        const model = entry;
-        const alias = [model.alias, model.key, model.id].find(value => typeof value === 'string');
-        if (!alias)
-            return [];
-        return [{
-                id: alias,
-                alias,
-                ...(typeof model.name === 'string' ? { displayName: model.name } : {}),
-                ...(model.default === true || model.isDefault === true ? { isDefault: true } : {}),
-                ...(model.hidden === true ? { hidden: true } : {}),
-                ...(Array.isArray(model.reasoningEfforts)
-                    ? { reasoningEfforts: model.reasoningEfforts.filter((item) => typeof item === 'string') }
-                    : {}),
-            }];
+        }
+        return [{ role: item.role, path: item.path, ...(typeof item.note === 'string' ? { note: item.note } : {}), precedence: index + 1 }];
     });
 }
+function inspectModels(report, diagnostics) {
+    for (const key of ['models', 'modelCatalog', 'model_catalog']) {
+        if (!(key in report))
+            continue;
+        const candidates = report[key];
+        if (!Array.isArray(candidates)) {
+            diagnostics.push(`Grok Build /${key}: expected model array`);
+            continue;
+        }
+        return candidates.flatMap((entry, index) => {
+            const invalid = () => {
+                diagnostics.push(`Grok Build /${key}/${index}: malformed model row`);
+                return [];
+            };
+            if (typeof entry === 'string')
+                return entry.trim() ? [{ id: entry, alias: entry }] : invalid();
+            if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+                return invalid();
+            const model = entry;
+            const alias = [model.alias, model.key, model.id].find(value => typeof value === 'string');
+            if (!alias?.trim()
+                || (model.name !== undefined && typeof model.name !== 'string')
+                || ['default', 'isDefault', 'hidden'].some(field => model[field] !== undefined && typeof model[field] !== 'boolean')
+                || (model.reasoningEfforts !== undefined && (!Array.isArray(model.reasoningEfforts)
+                    || model.reasoningEfforts.some(item => typeof item !== 'string' || !item.trim()))))
+                return invalid();
+            return [{
+                    id: alias,
+                    alias,
+                    ...(typeof model.name === 'string' ? { displayName: model.name } : {}),
+                    ...(model.default === true || model.isDefault === true ? { isDefault: true } : {}),
+                    ...(model.hidden === true ? { hidden: true } : {}),
+                    ...(Array.isArray(model.reasoningEfforts)
+                        ? { reasoningEfforts: model.reasoningEfforts.filter((item) => typeof item === 'string') }
+                        : {}),
+                }];
+        });
+    }
+    return [];
+}
 function setSelected(selected, key, value, layer, constraint) {
     if (value === undefined)
         return;
@@ -174,7 +215,7 @@ function parseEnvOverlay(env) {
     if (!content || typeof content !== 'object' || Array.isArray(content))
         return null;
     const value = content;
-    const parsed = { models: new Map(), projectModelFields: false };
+    const parsed = { models: new Map(), projectModelFields: false, diagnostics: [] };
     const settings = value.models;
     if (settings && typeof settings === 'object' && !Array.isArray(settings)) {
         const table = settings;
@@ -184,6 +225,13 @@ function parseEnvOverlay(env) {
             parsed.allowedModels = table.allowed_models;
         if (Array.isArray(table.disabled_models) && table.disabled_models.every(entry => typeof entry === 'string'))
             parsed.disabledModels = table.disabled_models;
+        if (table.default !== undefined && (typeof table.default !== 'string' || !table.default)
+            || table.allowed_models !== undefined && !parsed.allowedModels
+            || table.disabled_models !== undefined && !parsed.disabledModels)
+            parsed.diagnostics.push('/models: malformed model settings');
+    }
+    else if (settings !== undefined) {
+        parsed.diagnostics.push('/models: expected object');
     }
     // The host allowlists env-overlay sections; per-model secrets and model definitions
     // are intentionally not imported from arbitrary JSON here.
@@ -239,7 +287,8 @@ export async function discoverGrokBuildModels(options = {}) {
                 error: 'Grok Build inspect returned an unsupported JSON shape; update Grok Build or AIWG.' };
         }
     }
-    const layers = inspectLayers(report);
+    const validationDiagnostics = [];
+    const layers = inspectLayers(report, validationDiagnostics);
     if (layers.length === 0 && !Object.keys(report).some(key => ['models', 'modelCatalog', 'model_catalog'].includes(key))) {
         return { ...base, ...(runtimeVersion ? { runtimeVersion } : {}), errorKind: 'invalid-output',
             error: 'Grok Build inspect JSON omitted configSources; update Grok Build or AIWG.' };
@@ -247,7 +296,7 @@ export async function discoverGrokBuildModels(options = {}) {
     const diagnostics = [];
     const selected = {};
     const constraints = [];
-    const discovered = inspectModels(report);
+    const discovered = inspectModels(report, validationDiagnostics);
     const parsedByLayer = await Promise.all(layers.map(layer => layer.role === 'env_overlay'
         && layer.path.includes('(inline)') ? parseEnvOverlay(env) : readLayer(layer)));
     let requirementsDefault;
@@ -255,8 +304,11 @@ export async function discoverGrokBuildModels(options = {}) {
     for (let i = 0; i < layers.length; i++) {
         const layer = layers[i];
         const parsed = parsedByLayer[i];
-        if (!parsed)
+        if (!parsed) {
+            validationDiagnostics.push(`${layer.path}: config layer could not be read or parsed within bounds`);
             continue;
+        }
+        validationDiagnostics.push(...parsed.diagnostics.map(diagnostic => `${layer.path}: ${diagnostic}`));
         if (parsed.projectModelFields)
             diagnostics.push(`${layer.path}: ignored model settings because Grok Build project scope does not allow them`);
         const requirement = /requirements|mdm/i.test(layer.role);
@@ -334,10 +386,10 @@ export async function discoverGrokBuildModels(options = {}) {
                 policyConstraint: /requirements|mdm/i.test(layer.role) })),
             selected,
             constraints,
-            diagnostics,
+            diagnostics: [...validationDiagnostics, ...diagnostics],
         },
-        ...(models.length === 0 ? { errorKind: 'invalid-output',
-            error: 'Grok Build exposed no model aliases. Configure [models].default or [model.<alias>] in $GROK_HOME/config.toml; AIWG will not fabricate an xAI model ID.' } : {}),
+        ...(validationDiagnostics.length || models.length === 0 ? { errorKind: 'invalid-output',
+            error: validationDiagnostics.join('; ') || 'Grok Build exposed no model aliases. Configure [models].default or [model.<alias>] in $GROK_HOME/config.toml; AIWG will not fabricate an xAI model ID.' } : {}),
     };
 }
 /** Resolve aliases only from the observed catalog. Exact API model ids are never synthesized. */