@open-agent-toolkit/cli 0.1.48 → 0.1.51

package/dist/commands/project/dispatch-ceiling/index.js

@@ -4,12 +4,14 @@ import { buildCommandContext, } from '../../../app/command-context.js';
 import { getFrontmatterBlock } from '../../shared/frontmatter.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { compileDispatchPolicyPreset, } from '../../../config/dispatch-ceiling-preset.js';
+import { normalizeDispatchMatrix } from '../../../config/dispatch-matrix.js';
 import { getDispatchPolicyChoices, managedDispatchPolicyValueList, renderDispatchPolicyChoicesMarkdown, } from '../../../config/dispatch-policy-options.js';
 import { resolveActiveProject, VALID_CLAUDE_DISPATCH_CEILINGS, VALID_CODEX_DISPATCH_CEILINGS, VALID_DISPATCH_MATRIX_TIERS, VALID_MANAGED_DISPATCH_POLICIES, isWorkflowDispatchCandidateLadder, isWorkflowDispatchFallbackRoute, toWorkflowDispatchCandidateLadder, validateDispatchRouteTarget, } from '../../../config/oat-config.js';
 import { resolveEffectiveConfig, } from '../../../config/resolve.js';
 import { resolveProjectRoot } from '../../../fs/paths.js';
 import TOML from '@iarna/toml';
 import { getCeilingAdapter, isDirectDispatchRoleName, CLAUDE_TIER_ORDER, } from '../../../providers/ceiling/registry.js';
+import { buildDispatchReport, formatDispatchReport, } from '../../../providers/identity/dispatch-report.js';
 import { classifyModelFamily, } from '../../../providers/identity/family.js';
 import { Command, Option } from 'commander';
 import YAML from 'yaml';
@@ -125,131 +127,64 @@ function invalidProjectPolicyMessage(value) {
     const actual = typeof value === 'string' ? value : String(value);
     return `Invalid project dispatch policy "${actual}". Valid managed policies: ${validManagedPolicyList()}. Use mode "inherit" for host defaults.`;
 }
-function normalizeProjectMatrixBareValue(provider, value) {
-    if (typeof value !== 'string') {
-        return undefined;
-    }
-    const trimmed = value.trim();
-    if (!trimmed) {
-        return undefined;
-    }
-    const order = providerValueOrder(provider);
-    if (order && !isValidProviderValue(provider, trimmed)) {
-        return undefined;
-    }
-    return trimmed;
+function isProjectMatrixRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
-function normalizeProjectMatrixRouteTarget(value) {
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
-        return undefined;
-    }
-    const record = value;
-    const target = {};
-    for (const key of ['harness', 'model', 'effort']) {
-        const rawValue = record[key];
-        if (typeof rawValue === 'string' && rawValue.trim()) {
-            target[key] = rawValue.trim();
-        }
-    }
-    return Object.keys(target).length > 0 ? target : undefined;
-}
-function normalizeProjectMatrixRoute(provider, value) {
-    if (!Array.isArray(value) || value.length === 0) {
-        return undefined;
-    }
-    const route = [];
-    for (const entry of value) {
-        const bareEntry = normalizeProjectMatrixBareValue(provider, entry);
-        if (bareEntry !== undefined) {
-            route.push(bareEntry);
+function toProjectMatrixCompatibility(rawMatrix, matrix) {
+    const compatibility = {};
+    for (const [provider, providerValue] of Object.entries(matrix)) {
+        if (typeof providerValue === 'string') {
+            compatibility[provider] = providerValue;
             continue;
         }
-        const target = normalizeProjectMatrixRouteTarget(entry);
-        if (target !== undefined) {
-            route.push(target);
-        }
-    }
-    return route.length > 0 ? route : undefined;
-}
-function normalizeProjectMatrixCandidate(provider, value) {
-    const bareValue = normalizeProjectMatrixBareValue(provider, value);
-    if (bareValue !== undefined) {
-        return bareValue;
-    }
-    if (isWorkflowDispatchFallbackRoute(value)) {
-        const route = normalizeProjectMatrixRoute(provider, value.route);
-        return route ? { route } : undefined;
-    }
-    return normalizeProjectMatrixRouteTarget(value);
-}
-function normalizeProjectMatrixCell(provider, value) {
-    const bareValue = normalizeProjectMatrixBareValue(provider, value);
-    if (bareValue !== undefined) {
-        return bareValue;
-    }
-    if (isWorkflowDispatchCandidateLadder(value)) {
-        const candidates = [];
-        for (const candidate of value.candidates) {
-            const normalized = normalizeProjectMatrixCandidate(provider, candidate);
-            if (normalized !== undefined) {
-                candidates.push(normalized);
+        const rawProvider = isProjectMatrixRecord(rawMatrix[provider])
+            ? rawMatrix[provider]
+            : {};
+        const tiers = {};
+        for (const [tier, cell] of Object.entries(providerValue)) {
+            const matrixTier = tier;
+            const rawCell = rawProvider[matrixTier];
+            const ladder = toWorkflowDispatchCandidateLadder(cell);
+            const firstCandidate = ladder.candidates[0];
+            if (typeof rawCell === 'string' && typeof firstCandidate === 'string') {
+                tiers[matrixTier] = firstCandidate;
+                continue;
             }
+            if (Array.isArray(rawCell) &&
+                firstCandidate !== undefined &&
+                isWorkflowDispatchFallbackRoute(firstCandidate)) {
+                tiers[matrixTier] = firstCandidate.route;
+                continue;
+            }
+            tiers[matrixTier] = cell;
         }
-        return candidates.length > 0 ? { candidates } : undefined;
-    }
-    return normalizeProjectMatrixRoute(provider, value);
-}
-function normalizeProjectMatrixProviderValue(provider, value) {
-    const bareValue = normalizeProjectMatrixBareValue(provider, value);
-    if (bareValue !== undefined) {
-        return bareValue;
-    }
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
-        return undefined;
-    }
-    const tierMap = {};
-    for (const [tier, rawCell] of Object.entries(value)) {
-        if (!VALID_DISPATCH_MATRIX_TIERS.includes(tier)) {
-            continue;
-        }
-        const normalized = normalizeProjectMatrixCell(provider, rawCell);
-        if (normalized !== undefined) {
-            tierMap[tier] = normalized;
-        }
+        compatibility[provider] = tiers;
     }
-    return Object.keys(tierMap).length > 0 ? tierMap : undefined;
+    return compatibility;
 }
 function readProjectDispatchMatrix(value) {
     if (value === undefined || value === null) {
-        return { matrix: null, warnings: [] };
-    }
-    if (typeof value !== 'object' || Array.isArray(value)) {
-        return {
-            matrix: null,
-            warnings: [
-                'Ignoring malformed oat_dispatch_policy.matrix in project state.',
-            ],
-        };
-    }
-    const matrix = {};
-    for (const [provider, rawProviderValue] of Object.entries(value)) {
-        if (!provider.trim()) {
-            continue;
-        }
-        const normalized = normalizeProjectMatrixProviderValue(provider, rawProviderValue);
-        if (normalized !== undefined) {
-            matrix[provider] = normalized;
-        }
-    }
-    if (Object.keys(matrix).length === 0) {
+        return { matrix: null, compatibilityMatrix: null, warnings: [] };
+    }
+    const normalized = normalizeDispatchMatrix(value, {
+        pathPrefix: 'oat_dispatch_policy.matrix',
+        compatibilityMode: 'project-state',
+    });
+    const matrix = Object.fromEntries(Object.entries(normalized.providers).filter(([provider]) => Boolean(provider.trim())));
+    if (!isProjectMatrixRecord(value) || Object.keys(matrix).length === 0) {
         return {
             matrix: null,
+            compatibilityMatrix: null,
             warnings: [
                 'Ignoring malformed oat_dispatch_policy.matrix in project state.',
             ],
         };
     }
-    return { matrix, warnings: [] };
+    return {
+        matrix,
+        compatibilityMatrix: toProjectMatrixCompatibility(value, matrix),
+        warnings: [],
+    };
 }
 function policyTier(policy) {
     return typeof policy === 'string' &&
@@ -585,6 +520,7 @@ function resolveRequestedMatrixCandidate(provider, requested, ceilingTier, resol
             }
             allowedMatch ??= {
                 tier,
+                candidateIndex,
                 candidate,
                 cellSource: definition.cellSource,
                 routeSignature,
@@ -613,6 +549,7 @@ function resolveRequestedMatrixCandidate(provider, requested, ceilingTier, resol
                 : 'candidate-requested',
         },
         candidateTier: allowedMatch.tier,
+        candidateIndex: allowedMatch.candidateIndex,
     };
 }
 function readProjectDispatchPolicy(provider, content) {
@@ -639,9 +576,11 @@ function readProjectDispatchPolicy(provider, content) {
             source: 'project-state',
             preset: null,
             matrix: parsedMatrix.matrix,
+            matrixCompatibility: parsedMatrix.compatibilityMatrix,
             cellSource: null,
             target: null,
             selectionBranch: 'inherit',
+            candidateIndex: null,
             warnings: parsedMatrix.warnings,
         };
     }
@@ -662,9 +601,11 @@ function readProjectDispatchPolicy(provider, content) {
             source: 'project-state',
             preset: policyValue,
             matrix: parsedMatrix.matrix,
+            matrixCompatibility: parsedMatrix.compatibilityMatrix,
             cellSource: null,
             target: null,
             selectionBranch: 'prompt-persisted',
+            candidateIndex: null,
             warnings: parsedMatrix.warnings,
         };
     }
@@ -689,9 +630,11 @@ function readProjectDispatchPolicy(provider, content) {
         source: 'project-state',
         preset: policyValue,
         matrix: parsedMatrix.matrix,
+        matrixCompatibility: parsedMatrix.compatibilityMatrix,
         cellSource: 'project-state',
         target: null,
         selectionBranch: 'prompt-persisted',
+        candidateIndex: null,
         warnings: parsedMatrix.warnings,
     };
 }
@@ -722,6 +665,7 @@ function readLegacyProjectDispatchCeiling(provider, parsed) {
         cellSource: 'project-state',
         target: null,
         selectionBranch: 'prompt-persisted',
+        candidateIndex: null,
         warnings: [],
     };
 }
@@ -790,9 +734,11 @@ function stripConfigCandidateSource(candidate) {
         source: candidate.source,
         preset: candidate.preset,
         matrix: candidate.matrix,
+        matrixCompatibility: candidate.matrixCompatibility,
         cellSource: candidate.cellSource,
         target: candidate.target,
         selectionBranch: candidate.selectionBranch,
+        candidateIndex: candidate.candidateIndex,
         warnings: candidate.warnings,
     };
 }
@@ -815,6 +761,7 @@ function readResolvedConfigPolicyCandidate(provider, resolvedConfig) {
             cellSource: null,
             target: null,
             selectionBranch: 'inherit',
+            candidateIndex: null,
             warnings: [],
             configSource: modeEntry.source,
         };
@@ -840,6 +787,7 @@ function readResolvedConfigPolicyCandidate(provider, resolvedConfig) {
             cellSource: null,
             target: null,
             selectionBranch: 'prompt-persisted',
+            candidateIndex: null,
             warnings: [],
             configSource,
         };
@@ -870,6 +818,7 @@ function readResolvedLegacyConfigCeilingCandidate(provider, resolvedConfig) {
         cellSource: source,
         target: null,
         selectionBranch: 'prompt-persisted',
+        candidateIndex: null,
         warnings: [],
         configSource: entry.source,
     };
@@ -998,6 +947,7 @@ function selectDispatchValue(provider, role, policy, preferredValue) {
         target: policy.target,
         requestedCandidate: policy.requestedCandidate ?? null,
         candidateTier: policy.candidateTier ?? null,
+        candidateIndex: policy.candidateIndex,
         ceilingTier: policy.ceilingTier ?? policyTier(policy.policy),
         ceilingTarget: policy.ceilingTarget ?? policy.target,
     };
@@ -1160,6 +1110,7 @@ function buildProviderResolution(provider, policy, role, orchestratorTier, prefe
                 preferredValue,
                 requestedCandidate: null,
                 candidateTier: null,
+                candidateIndex: null,
                 ceilingTier: null,
                 ceilingTarget: null,
                 selectedValue: null,
@@ -1224,6 +1175,58 @@ function readCodexDefaultFromToml(content) {
     const value = parsed['model_reasoning_effort'];
     return typeof value === 'string' && value.trim() ? value.trim() : null;
 }
+function readCodexMaxDepthEntry(content) {
+    let parsed;
+    try {
+        parsed = TOML.parse(content);
+    }
+    catch {
+        return { present: true, value: null };
+    }
+    const agents = parsed.agents;
+    if (!agents || typeof agents !== 'object' || Array.isArray(agents)) {
+        return { present: false, value: undefined };
+    }
+    const record = agents;
+    return {
+        present: Object.prototype.hasOwnProperty.call(record, 'max_depth'),
+        value: record.max_depth,
+    };
+}
+async function readCodexMaxDepthAtPath(path, dependencies) {
+    if (!(await dependencies.pathExists(path))) {
+        return { present: false, value: undefined };
+    }
+    try {
+        return readCodexMaxDepthEntry(await dependencies.readFile(path));
+    }
+    catch {
+        return { present: true, value: null };
+    }
+}
+/**
+ * Resolves the depth seen by Codex: project config wins whenever it declares a
+ * value, while an absent project value inherits the user config.
+ */
+async function resolveEffectiveCodexMaxDepth(scope, repoRoot, context, dependencies) {
+    const userPath = join(context.home, '.codex', 'config.toml');
+    if (scope === 'user') {
+        return readCodexMaxDepthAtPath(userPath, dependencies);
+    }
+    const projectEntry = await readCodexMaxDepthAtPath(join(repoRoot, '.codex', 'config.toml'), dependencies);
+    return projectEntry.present
+        ? projectEntry
+        : readCodexMaxDepthAtPath(userPath, dependencies);
+}
+function managedCodexDepthBlockMessage(scope, entry) {
+    const validDepth = typeof entry.value === 'number' && Number.isFinite(entry.value);
+    const state = !entry.present
+        ? 'agents.max_depth is missing'
+        : validDepth
+            ? `agents.max_depth is ${entry.value}`
+            : 'agents.max_depth is not a valid number';
+    return `BLOCKED: Codex ${state}; managed implementation requires root (0) → phase coordinator (1) → task worker (2).\nRun \`oat sync --scope ${scope}\`, or materialize a single role with \`oat providers codex materialize <agent-name> --model <model> --effort <effort> --scope ${scope}\`.`;
+}
 async function resolveCodexProviderDefaultEffort(repoRoot, context, dependencies) {
     const candidates = [
         join(repoRoot, '.codex', 'config.toml'),
@@ -1273,6 +1276,34 @@ async function resolveDispatchCeiling(context, dependencies, options) {
         [provider]: providerResolution,
     };
     if (resolvedValue) {
+        const requiresManagedCodexDepth = options.preflight === true &&
+            provider === 'codex' &&
+            role === 'implementer' &&
+            resolvedValue.mode === 'managed';
+        if (requiresManagedCodexDepth) {
+            const scope = context.scope === 'user' ? 'user' : 'project';
+            const depth = await resolveEffectiveCodexMaxDepth(scope, repoRoot, context, dependencies);
+            const numericDepth = typeof depth.value === 'number' && Number.isFinite(depth.value)
+                ? depth.value
+                : null;
+            if (numericDepth === null || numericDepth < 2) {
+                return {
+                    status: 'blocked',
+                    provider,
+                    value: resolvedValue.value,
+                    policyMode: resolvedValue.mode,
+                    policy: resolvedValue.policy,
+                    source: resolvedValue.source,
+                    preset: resolvedValue.preset,
+                    unresolved: true,
+                    projectPath,
+                    providerDefaultEffort,
+                    matrix: resolvedValue.matrix,
+                    providers,
+                    message: managedCodexDepthBlockMessage(scope, depth),
+                };
+            }
+        }
         const incompleteManagedPreflight = options.preflight === true &&
             resolvedValue.mode === 'managed' &&
             providerResolution.mode === 'advisory' &&
@@ -1294,7 +1325,7 @@ async function resolveDispatchCeiling(context, dependencies, options) {
                 unresolved: true,
                 projectPath,
                 providerDefaultEffort,
-                matrix: resolvedValue.matrix,
+                matrix: resolvedValue.matrixCompatibility ?? resolvedValue.matrix,
                 providers,
                 message,
             };
@@ -1310,7 +1341,7 @@ async function resolveDispatchCeiling(context, dependencies, options) {
             unresolved: false,
             projectPath,
             providerDefaultEffort,
-            matrix: resolvedValue.matrix,
+            matrix: resolvedValue.matrixCompatibility ?? resolvedValue.matrix,
             providers,
         };
     }
@@ -1356,6 +1387,7 @@ async function resolveCeilingValue(provider, resolvedConfig, projectPath, depend
             source: 'invocation',
             preset: invocationCeilingTier,
             matrix: projectCeiling?.matrix ?? baseCeiling.matrix,
+            matrixCompatibility: projectCeiling?.matrixCompatibility ?? baseCeiling.matrixCompatibility,
             cellSource: null,
             target: null,
             selectionBranch: 'prompt-persisted',
@@ -1391,6 +1423,7 @@ async function resolveCeilingValue(provider, resolvedConfig, projectPath, depend
             ],
             requestedCandidate,
             candidateTier: selected.candidateTier,
+            candidateIndex: selected.candidateIndex,
             ceilingTarget: ceilingCell?.target ?? null,
             ...(ceilingTier ? { ceilingTier } : {}),
         };
@@ -1533,14 +1566,91 @@ function writeHumanResolution(context, resolution) {
         }
     }
 }
+function reportRole(action) {
+    if (action === 'review') {
+        return 'reviewer';
+    }
+    return action === 'fix' ? 'fix' : 'implementer';
+}
+function reportControl(axis, dispatchArgs, reason) {
+    if (axis.startsWith('selected:')) {
+        return {
+            value: axis.slice('selected:'.length),
+            mechanism: dispatchArgs && 'variant' in dispatchArgs
+                ? 'materialized-role'
+                : 'task-model-argument',
+            reason,
+        };
+    }
+    if (axis === 'inherited') {
+        return { value: null, mechanism: 'host-inherited', reason };
+    }
+    if (axis === 'provider-default') {
+        return { value: null, mechanism: 'provider-default', reason };
+    }
+    if (axis === 'not-applicable') {
+        return { value: null, mechanism: 'not-applicable', reason };
+    }
+    return { value: null, mechanism: 'base-role', reason };
+}
+function buildResolutionReport(resolution, options) {
+    const hasScope = options.reportScope !== undefined;
+    const hasAction = options.reportAction !== undefined;
+    if (!hasScope && !hasAction) {
+        return null;
+    }
+    if (!hasScope || !hasAction) {
+        throw new Error('--report-scope and --report-action must be provided together.');
+    }
+    const scope = options.reportScope.trim();
+    if (!scope) {
+        throw new Error('--report-scope must be a non-empty value.');
+    }
+    const action = options.reportAction;
+    const role = reportRole(action);
+    const providerResolution = resolution.providers[resolution.provider];
+    if (!providerResolution) {
+        throw new Error(`Dispatch report resolution is missing provider data for "${resolution.provider}".`);
+    }
+    const expectedResolverRole = role === 'reviewer' ? 'reviewer' : 'implementer';
+    if (providerResolution.selection.role !== expectedResolverRole) {
+        throw new Error(`Invalid dispatch report action/role context: ${action}/${role} requires resolver role ${expectedResolverRole}, received ${providerResolution.selection.role}.`);
+    }
+    return buildDispatchReport({
+        scope,
+        action,
+        role,
+        resolution,
+        requestedControls: {
+            model: reportControl(providerResolution.modelAxis, providerResolution.dispatchArgs, 'Derived from the completed resolver model-axis result.'),
+            effort: reportControl(providerResolution.effortAxis, providerResolution.dispatchArgs, 'Derived from the completed resolver effort-axis result.'),
+        },
+        configuredDefaults: {
+            model: null,
+            modelSource: null,
+            effort: resolution.provider === 'codex' &&
+                resolution.providerDefaultEffort !== 'unknown'
+                ? resolution.providerDefaultEffort
+                : null,
+            effortSource: resolution.provider === 'codex' &&
+                resolution.providerDefaultEffort !== 'unknown'
+                ? 'codex-config'
+                : null,
+        },
+    });
+}
 async function runDispatchCeilingResolve(context, dependencies, options) {
     try {
         const resolution = await resolveDispatchCeiling(context, dependencies, options);
+        const dispatchReport = buildResolutionReport(resolution, options);
         if (context.json) {
-            context.logger.json(resolution);
+            context.logger.json(dispatchReport ? { ...resolution, dispatchReport } : resolution);
         }
         else {
             writeHumanResolution(context, resolution);
+            if (dispatchReport) {
+                context.logger.info(formatDispatchReport(dispatchReport));
+            }
         }
         process.exitCode = resolution.status === 'blocked' ? 1 : 0;
     }
@@ -1602,6 +1712,8 @@ export function createProjectDispatchCeilingCommand(overrides = {}) {
         .option('--project-path <path>', 'Read project-state policy from an explicit project path')
         .option('--preflight', 'Treat unresolved non-interactive resolution as an implementation block')
         .option('--non-interactive', 'Force non-interactive block behavior when the ceiling is unresolved')
+        .option('--report-scope <scope>', 'Include Dispatch Report V1 for the explicit workflow scope')
+        .addOption(new Option('--report-action <action>', 'Dispatch Report V1 action; must match the resolver role').choices(['implementation', 'fix', 'review']))
         .option('--json', 'Output machine-readable JSON')
         .action(async (options, cmd) => {
         const globalOptions = readGlobalOptions(cmd);

package/dist/commands/providers/codex/materialize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"materialize.d.ts","sourceRoot":"","sources":["../../../../src/commands/providers/codex/materialize.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,sBAAsB,EACtB,qCAAqC,EACtC,MAAM,qCAAqC,CAAC;AAU7C,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAsD5C,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,sBAAsB,GAC7B,MAAM,CAaR;AA+GD,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,OAAO,CAAC,qCAAqC,CAAM,GAC7D,OAAO,CAoCT"}
+{"version":3,"file":"materialize.d.ts","sourceRoot":"","sources":["../../../../src/commands/providers/codex/materialize.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,sBAAsB,EACtB,qCAAqC,EACtC,MAAM,qCAAqC,CAAC;AAa7C,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAyD5C,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,sBAAsB,GAC7B,MAAM,CAaR;AAsID,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,OAAO,CAAC,qCAAqC,CAAM,GAC7D,OAAO,CAoCT"}

package/dist/commands/providers/codex/materialize.js

@@ -6,7 +6,7 @@ import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { CliError } from '../../../errors/index.js';
 import { ensureDir, fileExists } from '../../../fs/io.js';
 import { resolveProjectRoot, resolveScopeRoot } from '../../../fs/paths.js';
-import { mergeCodexConfigForRole } from '../../../providers/codex/codec/config-merge.js';
+import { mergeCodexConfigForRole, readCodexMaxDepth, } from '../../../providers/codex/codec/config-merge.js';
 import { materializeCodexRole } from '../../../providers/codex/codec/materialize.js';
 import { withOatManagedCodexRoleOwner } from '../../../providers/codex/codec/shared.js';
 import { Command, Option } from 'commander';
@@ -72,8 +72,29 @@ async function buildCodexMaterializePlan(agentName, options, context, dependenci
     };
     const rolePath = join(scopeRoot, '.codex', role.configFile);
     const configPath = join(scopeRoot, '.codex', 'config.toml');
+    const existingRoleContent = await readOptionalFile(rolePath);
+    const existingConfigContent = await readOptionalFile(configPath);
+    let inheritedMaxDepth;
+    if (scope === 'project') {
+        const userScopeRoot = await dependencies.resolveScopeRoot('user', context);
+        const userConfigContent = await readOptionalFile(join(userScopeRoot, '.codex', 'config.toml'));
+        inheritedMaxDepth = readCodexMaxDepth(userConfigContent) ?? undefined;
+    }
+    const mergedConfig = mergeCodexConfigForRole({
+        existingContent: existingConfigContent,
+        role: {
+            roleName: role.roleName,
+            description: role.description,
+            configFile: role.configFile,
+        },
+        inheritedMaxDepth,
+    });
     return {
+        configChanged: mergedConfig.changed,
+        mergedConfigContent: mergedConfig.mergedContent,
         role,
+        roleChanged: existingRoleContent === null ||
+            existingRoleContent.trimEnd() !== role.content.trimEnd(),
         result: {
             status: context.dryRun ? 'preview' : 'written',
             dryRun: context.dryRun,
@@ -93,20 +114,15 @@ async function readOptionalFile(filePath) {
     }
     return readFile(filePath, 'utf8');
 }
-async function applyCodexMaterializePlan({ result, role, }) {
-    await ensureDir(dirname(result.rolePath));
-    await writeFile(result.rolePath, role.content, 'utf8');
-    const existingConfig = await readOptionalFile(result.configPath);
-    const mergedConfig = mergeCodexConfigForRole({
-        existingContent: existingConfig,
-        role: {
-            roleName: role.roleName,
-            description: role.description,
-            configFile: role.configFile,
-        },
-    });
-    await ensureDir(dirname(result.configPath));
-    await writeFile(result.configPath, mergedConfig.mergedContent, 'utf8');
+async function applyCodexMaterializePlan({ configChanged, mergedConfigContent, result, role, roleChanged, }) {
+    if (roleChanged) {
+        await ensureDir(dirname(result.rolePath));
+        await writeFile(result.rolePath, role.content, 'utf8');
+    }
+    if (configChanged) {
+        await ensureDir(dirname(result.configPath));
+        await writeFile(result.configPath, mergedConfigContent, 'utf8');
+    }
 }
 async function runCodexMaterializeCommand(agentName, options, context, dependencies) {
     try {

package/dist/config/dispatch-matrix.d.ts

@@ -0,0 +1,59 @@
+export type WorkflowDispatchMatrixTier = 'economy' | 'balanced' | 'high' | 'frontier';
+export interface WorkflowDispatchRouteTarget {
+    harness?: string;
+    model?: string;
+    effort?: string;
+}
+export interface DispatchRouteTargetValidation {
+    valid: boolean;
+    reason?: string;
+}
+export type WorkflowDispatchRouteEntry = string | WorkflowDispatchRouteTarget;
+export type WorkflowDispatchRoute = WorkflowDispatchRouteEntry[];
+export interface WorkflowDispatchFallbackRoute {
+    route: WorkflowDispatchRoute;
+}
+export type WorkflowDispatchCandidate = WorkflowDispatchRouteEntry | WorkflowDispatchFallbackRoute;
+export interface WorkflowDispatchCandidateLadder {
+    candidates: WorkflowDispatchCandidate[];
+}
+export type WorkflowDispatchLegacyMatrixCell = string | WorkflowDispatchRoute;
+export type WorkflowDispatchMatrixCell = WorkflowDispatchCandidateLadder | WorkflowDispatchLegacyMatrixCell;
+export type WorkflowDispatchProviderValue = string | Partial<Record<WorkflowDispatchMatrixTier, WorkflowDispatchMatrixCell>>;
+export type DispatchMatrixNormalizationIssueKind = 'malformed-provider' | 'malformed-tier' | 'malformed-candidate';
+export interface DispatchMatrixNormalizationIssue {
+    path: string;
+    kind: DispatchMatrixNormalizationIssueKind;
+    value: unknown;
+}
+export interface NormalizedDispatchMatrix {
+    providers: Record<string, WorkflowDispatchProviderValue>;
+    issues: DispatchMatrixNormalizationIssue[];
+}
+export type DispatchMatrixSource = 'local-config' | 'repo-config' | 'user-config' | 'project-state';
+export interface DispatchMatrixWalkContext {
+    source: DispatchMatrixSource;
+    pathPrefix: string;
+}
+export interface DispatchMatrixCellRef {
+    provider: string;
+    tier: WorkflowDispatchMatrixTier | null;
+    candidateIndex: number | null;
+    fallbackRouteIndex: number | null;
+    value: string | null;
+    target: WorkflowDispatchRouteTarget | null;
+    path: string;
+    source: DispatchMatrixSource;
+}
+export declare const VALID_DISPATCH_MATRIX_TIERS: readonly WorkflowDispatchMatrixTier[];
+export declare function normalizeDispatchMatrix(value: unknown, options: {
+    pathPrefix: string;
+    compatibilityMode: 'layered-config' | 'project-state';
+}): NormalizedDispatchMatrix;
+export declare function isCodexMaterializedRouteTarget(provider: string, target: WorkflowDispatchRouteTarget): boolean;
+export declare function validateDispatchRouteTarget(provider: string, target: WorkflowDispatchRouteTarget): DispatchRouteTargetValidation;
+export declare function isWorkflowDispatchFallbackRoute(value: unknown): value is WorkflowDispatchFallbackRoute;
+export declare function isWorkflowDispatchCandidateLadder(value: unknown): value is WorkflowDispatchCandidateLadder;
+export declare function toWorkflowDispatchCandidateLadder(cell: WorkflowDispatchMatrixCell): WorkflowDispatchCandidateLadder;
+export declare function walkDispatchMatrix(providers: Record<string, WorkflowDispatchProviderValue>, context: DispatchMatrixWalkContext): DispatchMatrixCellRef[];
+//# sourceMappingURL=dispatch-matrix.d.ts.map

package/dist/config/dispatch-matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-matrix.d.ts","sourceRoot":"","sources":["../../src/config/dispatch-matrix.ts"],"names":[],"mappings":"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"}