@open-agent-toolkit/cli 0.1.48 → 0.1.50

package/dist/commands/gate/index.js

@@ -9,6 +9,7 @@ import { BUILTIN_EXEC_TARGETS, readOatConfig, readOatLocalConfig, readUserConfig
 import { resolveEffectiveConfig, resolveExecTargetViews, resolveExecTargets, resolveGate, } from '../../config/resolve.js';
 import { dirExists, fileExists } from '../../fs/io.js';
 import { normalizeToPosixPath, resolveProjectRoot, validateRealPathWithinScope, } from '../../fs/paths.js';
+import { buildDispatchReport, } from '../../providers/identity/dispatch-report.js';
 import { classifyModelFamily, } from '../../providers/identity/family.js';
 import { resolveIdentityConfidence, } from '../../providers/identity/provenance.js';
 import { parseDispatchStamps } from '../../providers/identity/stamp.js';
@@ -94,6 +95,62 @@ function createGateInvocationMetadata(runId, selected) {
             : {}),
     });
 }
+function buildGateDispatchReport(invocation, scope) {
+    const report = buildDispatchReport({
+        scope,
+        action: 'review',
+        role: 'reviewer',
+        resolution: {
+            status: 'resolved',
+            provider: invocation.runtime,
+            value: null,
+            policyMode: null,
+            policy: null,
+            source: null,
+            providers: {
+                [invocation.runtime]: {
+                    dispatchArgs: null,
+                    selection: {
+                        role: 'reviewer',
+                        requestedCandidate: null,
+                        candidateTier: null,
+                        candidateIndex: null,
+                        ceilingTier: null,
+                        ceilingTarget: null,
+                        selectedValue: null,
+                        selectionMode: 'gate-invocation',
+                        selectionBranch: 'gate-configured-invocation',
+                        target: null,
+                        cellSource: null,
+                    },
+                },
+            },
+        },
+        requestedControls: {
+            model: {
+                value: null,
+                mechanism: 'base-role',
+                reason: 'Configured gate invocation is reported separately from runtime identity.',
+            },
+            effort: {
+                value: null,
+                mechanism: 'base-role',
+                reason: 'Configured gate invocation is reported separately from runtime identity.',
+            },
+        },
+        configuredDefaults: {
+            model: null,
+            modelSource: null,
+            effort: null,
+            effortSource: null,
+        },
+        gateInvocation: invocation,
+    });
+    return {
+        ...report,
+        route: { ...report.route, target: invocation.targetId },
+    };
+}
 function gateInvocationPromptContext(invocation) {
     const frontmatter = YAML.stringify({
         oat_gate_run_id: invocation.runId,
@@ -1165,6 +1222,7 @@ function writeReviewGateExecutionFailure(context, payload) {
             project: payload.project,
             projectResolutionSource: payload.projectResolutionSource,
             gateInvocation: payload.gateInvocation,
+            dispatchReport: payload.dispatchReport,
             ...(payload.corroboration
                 ? { corroboration: payload.corroboration }
                 : {}),
@@ -1192,6 +1250,7 @@ function writeReviewGateUnexpectedFailure(context, payload) {
             project: payload.project,
             projectResolutionSource: payload.projectResolutionSource,
             gateInvocation: payload.gateInvocation,
+            dispatchReport: payload.dispatchReport,
             message,
         });
         return;
@@ -1210,6 +1269,7 @@ function writeReviewGateArtifactValidationFailure(context, payload) {
             artifactPath: payload.artifactPath,
             generatedAt: payload.generatedAt,
             gateInvocation: payload.gateInvocation,
+            dispatchReport: payload.dispatchReport,
             ...(payload.corroboration
                 ? { corroboration: payload.corroboration }
                 : {}),
@@ -1248,6 +1308,7 @@ function writeReviewGateTargetingFailure(context, payload) {
             artifactPath: payload.artifactPath,
             generatedAt: payload.generatedAt,
             gateInvocation: payload.gateInvocation,
+            dispatchReport: payload.dispatchReport,
             corroboration,
             receiveEligible: false,
             remediable: false,
@@ -1418,11 +1479,13 @@ async function runReviewGate(prompt, options, context, dependencies) {
         });
         const selected = await resolveSelectedExecTarget(targets, options, producerIdentity, context, dependencies);
         const gateInvocation = createGateInvocationMetadata(runId, selected);
+        const dispatchReport = buildGateDispatchReport(gateInvocation, options.reviewScope?.trim() || 'gate-review');
         postSelectionContext = {
             project: projectPath,
             projectResolutionSource: reviewProject.source,
             target: selected.id,
             gateInvocation,
+            dispatchReport,
         };
         const threshold = parseReviewGateThreshold(options.exitNonzeroOn);
         const before = await listReviewGateArtifactCandidates({
@@ -1454,6 +1517,7 @@ async function runReviewGate(prompt, options, context, dependencies) {
                 timedOut: childResult.timedOut ?? false,
                 timeoutMs: resolveGateExecTimeoutMs(dependencies.processEnv),
                 gateInvocation,
+                dispatchReport,
             });
             process.exitCode = childExitCode;
             return;
@@ -1493,6 +1557,7 @@ async function runReviewGate(prompt, options, context, dependencies) {
                 generatedAt: diagnosticArtifact?.generatedAt ?? null,
                 message,
                 gateInvocation,
+                dispatchReport,
                 corroboration: initialTargetCorroboration,
             });
             process.exitCode = 1;
@@ -1514,6 +1579,7 @@ async function runReviewGate(prompt, options, context, dependencies) {
                         ? 'Review artifact is missing oat_project for the explicitly declared project.'
                         : 'Review artifact project identity does not match the explicitly declared project.',
                 gateInvocation,
+                dispatchReport,
                 corroboration: initialTargetCorroboration,
             });
             process.exitCode = 1;
@@ -1531,6 +1597,7 @@ async function runReviewGate(prompt, options, context, dependencies) {
                 message: 'Review artifact oat_generated_at is missing or is not a valid timestamp.',
                 recovery: `Set oat_generated_at to a valid timestamp in ${producedArtifact.path}, then rerun the gate. Invoke oat-project-review-receive only after the gate returns a receive-eligible result.`,
                 gateInvocation,
+                dispatchReport,
                 corroboration: corroborateGateInvocation(gateInvocation, undefined, initialTargetCorroboration),
             });
             process.exitCode = 1;
@@ -1558,6 +1625,7 @@ async function runReviewGate(prompt, options, context, dependencies) {
                 message: detail,
                 recovery: `The review artifact was created at ${producedArtifact.path} but could not be consumed. Fix the artifact format, then rerun the gate to revalidate it. Invoke oat-project-review-receive only after the gate returns a receive-eligible result; if the only issue is a missing zero-count severity heading, rerun the gate to normalize the same artifact instead of creating a new review version.`,
                 gateInvocation,
+                dispatchReport,
                 corroboration: corroborateGateInvocation(gateInvocation, undefined, initialTargetCorroboration),
             });
             process.exitCode = 1;
@@ -1581,6 +1649,7 @@ async function runReviewGate(prompt, options, context, dependencies) {
                     : 'Review artifact invocation metadata does not match the gate-owned configured invocation.',
                 recovery: `Copy the exact gate invocation fields from the review prompt into ${producedArtifact.path}, then run oat-project-review-receive only after the artifact validates.`,
                 gateInvocation,
+                dispatchReport,
                 corroboration,
             });
             process.exitCode = 1;
@@ -1597,6 +1666,7 @@ async function runReviewGate(prompt, options, context, dependencies) {
                 message: 'Review artifact is missing the required gate invocation marker `oat_review_invocation: gate`.',
                 recovery: `Set oat_review_invocation: gate in ${producedArtifact.path}, then run oat-project-review-receive only after the artifact validates.`,
                 gateInvocation,
+                dispatchReport,
                 corroboration,
             });
             process.exitCode = 1;
@@ -1627,6 +1697,7 @@ async function runReviewGate(prompt, options, context, dependencies) {
             handoff,
             diversity: selected.diversity,
             gateInvocation,
+            dispatchReport,
             corroboration,
         });
         process.exitCode = blocking ? 1 : 0;

package/dist/commands/project/dispatch-ceiling/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/dispatch-ceiling/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAY9B,OAAO,EAUL,KAAK,uBAAuB,EAY7B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAezB,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAiC5C,UAAU,2BAA2B;IACnC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,oBAAoB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC7E,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AA+0ED,wBAAgB,mCAAmC,CACjD,SAAS,GAAE,OAAO,CAAC,2BAA2B,CAAM,GACnD,OAAO,CAwFT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/dispatch-ceiling/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAa9B,OAAO,EAUL,KAAK,uBAAuB,EAY7B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAsBzB,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAiC5C,UAAU,2BAA2B;IACnC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,oBAAoB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC7E,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AA63ED,wBAAgB,mCAAmC,CACjD,SAAS,GAAE,OAAO,CAAC,2BAA2B,CAAM,GACnD,OAAO,CAkGT"}

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 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 isProjectMatrixRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
-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, 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.',
             ],
         };
     }
-    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,
-            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,
@@ -1294,7 +1245,7 @@ async function resolveDispatchCeiling(context, dependencies, options) {
                 unresolved: true,
                 projectPath,
                 providerDefaultEffort,
-                matrix: resolvedValue.matrix,
+                matrix: resolvedValue.matrixCompatibility ?? resolvedValue.matrix,
                 providers,
                 message,
             };
@@ -1310,7 +1261,7 @@ async function resolveDispatchCeiling(context, dependencies, options) {
             unresolved: false,
             projectPath,
             providerDefaultEffort,
-            matrix: resolvedValue.matrix,
+            matrix: resolvedValue.matrixCompatibility ?? resolvedValue.matrix,
             providers,
         };
     }
@@ -1356,6 +1307,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 +1343,7 @@ async function resolveCeilingValue(provider, resolvedConfig, projectPath, depend
             ],
             requestedCandidate,
             candidateTier: selected.candidateTier,
+            candidateIndex: selected.candidateIndex,
             ceilingTarget: ceilingCell?.target ?? null,
             ...(ceilingTier ? { ceilingTier } : {}),
         };
@@ -1533,14 +1486,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 +1632,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/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