sequant 2.11.0 → 2.13.0

package/dist/src/lib/workflow/batch-executor.js

@@ -14,7 +14,7 @@ import { withEscalatedEffort } from "./effort-escalation.js";
 import { classifyError, errorTypeToCategory, } from "./error-classifier.js";
 import { getGitDiffStats, getCommitHash, resolveDiffBase, } from "./git-diff-utils.js";
 import { createCheckpointCommit, rebaseBeforePR, createPR, readCacheMetrics, filterResumedPhases, } from "./worktree-manager.js";
-import { AUTO_WAIT_BUFFER_MS, createAutoWaitLedger, executePhaseWithRetry, hasExecChanges, isWindowExhaustedRateLimit, } from "./phase-executor.js";
+import { AUTO_WAIT_BUFFER_MS, createAutoWaitLedger, executePhaseWithRetry, hasExecChanges, isWindowExhaustedRateLimit, selectFixableGaps, } from "./phase-executor.js";
 import { BillingError, RateLimitError, resetsAtToMs } from "../errors.js";
 import { parseBodyDependencyMarkers } from "./dependency-markers.js";
 import { determinePhasesForIssue, DOCS_LABELS } from "./phase-mapper.js";
@@ -135,8 +135,11 @@ export function buildLoopContext(failedResult) {
     if (failedResult.verdict) {
         parts.push(`QA Verdict: ${failedResult.verdict}`);
     }
-    if (failedResult.summary?.gaps?.length) {
-        parts.push(`QA Gaps:\n${failedResult.summary.gaps.map((gap) => `- ${gap}`).join("\n")}`);
+    // #937 AC-3: exclude findings marked `document`/`pause_for_human` — those
+    // are QA-real but not something a fix loop should chase.
+    const fixableGaps = selectFixableGaps(failedResult.summary);
+    if (fixableGaps.length) {
+        parts.push(`QA Gaps:\n${fixableGaps.map((gap) => `- ${gap}`).join("\n")}`);
     }
     if (failedResult.summary?.suggestions?.length) {
         parts.push(`Suggestions:\n${failedResult.summary.suggestions.map((s) => `- ${s}`).join("\n")}`);
@@ -564,6 +567,50 @@ async function recordWindowHaltState(stateManager, issueNumber, phase, result) {
         // State tracking errors shouldn't stop execution
     }
 }
+/**
+ * Build the comment body for a standard-qa-phase verdict post (#964).
+ * Includes AC coverage and any gaps/suggestions from the parsed `QaSummary`,
+ * plus a machine marker so a future dedup pass has an anchor.
+ * @internal Exported for testing.
+ */
+export function buildQaVerdictComment(verdict, summary, commitHash, iteration) {
+    const lines = [`## QA Verdict: ${verdict}`];
+    if (summary) {
+        lines.push("", `AC coverage: ${summary.acMet}/${summary.acTotal} met`);
+        if (summary.gaps.length > 0) {
+            lines.push("", "**Gaps:**", ...summary.gaps.map((g) => `- ${g}`));
+        }
+        if (summary.suggestions.length > 0) {
+            lines.push("", "**Suggestions:**", ...summary.suggestions.map((s) => `- ${s}`));
+        }
+    }
+    lines.push("", `<!-- SEQUANT_QA_VERDICT: ${JSON.stringify({
+        verdict,
+        commit: commitHash ?? null,
+        iteration,
+    })} -->`);
+    return lines.join("\n");
+}
+/**
+ * Post the qa-verdict comment for a standard (non-ready-gate) qa phase under
+ * orchestrated `sequant run` (#964). This is the channel `qa/SKILL.md` §9
+ * promises ("orchestrator handles aggregated summary") but batch-executor
+ * never backed — a re-run producing a fresh, different verdict left a stale,
+ * contradicted comment as the only externally-visible one.
+ *
+ * Best-effort: a post failure is caught and logged, never fails the run —
+ * mirrors {@link runReadyGateForIssue}'s `postReport` contract (#937 AC-4).
+ * @internal Exported for testing.
+ */
+export async function postQaVerdictComment(issueNumber, verdict, summary, commitHash, iteration, log, postComment = (n, body) => new GitHubProvider().postComment(String(n), body)) {
+    try {
+        const body = buildQaVerdictComment(verdict, summary, commitHash, iteration);
+        await postComment(issueNumber, body);
+    }
+    catch (err) {
+        log(chalk.yellow(`    !  Failed to post QA verdict comment: ${err}`));
+    }
+}
 /**
  * Run the post-QA ready gate (#817) for a single issue at the run path's
  * post-success / pre-PR seam.
@@ -594,6 +641,8 @@ async function runReadyGateForIssue(args) {
     const getSettingsFn = args.getSettingsFn ?? getSettings;
     const fetchBody = args.fetchBody ??
         ((n) => new GitHubProvider().fetchIssueBodySync(String(n)));
+    const postComment = args.postComment ??
+        ((n, body) => new GitHubProvider().postComment(String(n), body));
     try {
         const settings = await getSettingsFn();
         const policy = settings.ready.policy;
@@ -620,6 +669,8 @@ async function runReadyGateForIssue(args) {
             verbose: config.verbose,
             runPhase,
             onProgress,
+            // #937 AC-4: persist the final gap report as an issue comment.
+            postReport: (body) => postComment(issueNumber, body),
         });
         log(result.ready
             ? chalk.green(`  ✓ Ready gate: ${result.reason} — awaiting human merge (never merged)`)
@@ -636,7 +687,7 @@ async function runReadyGateForIssue(args) {
 }
 export async function runIssueWithLogging(ctx) {
     // Destructure context for use throughout the function
-    const { issueNumber, config, options, title: issueTitle, labels, services: { logWriter, stateManager, shutdownManager }, worktree, chain, packageManager, baseBranch, onProgress, onPhasePlan, phasePauseHandle, } = ctx;
+    const { issueNumber, config, options, title: issueTitle, labels, services: { logWriter, stateManager, shutdownManager }, worktree, chain, packageManager, baseBranch, onProgress, onPhasePlan, phasePauseHandle, postComment: injectedPostComment, } = ctx;
     const worktreePath = worktree?.path;
     const branch = worktree?.branch;
     const chainMode = chain?.enabled;
@@ -1103,6 +1154,23 @@ export async function runIssueWithLogging(ctx) {
                     /* progress errors must not halt */
                 }
             }
+            // #964: post the verdict from a standard (non-ready-gate) qa phase.
+            // qa/SKILL.md §9 promises "the orchestrator handles aggregated summary"
+            // under SEQUANT_ORCHESTRATOR, but nothing backed that promise — a
+            // re-run producing a fresh, different verdict left the stale prior
+            // comment as the only externally-visible one. Gating on
+            // `result.success && result.verdict` also excludes turn-capped and
+            // unparseable-verdict phases (AC-4) without extra bookkeeping, since
+            // both already flow through the `else` branch above.
+            if (phase === "qa" && result.success && result.verdict) {
+                const verdictDiffBase = worktreePath
+                    ? resolveDiffBase(worktreePath, baseBranch ?? "main")
+                    : undefined;
+                const verdictCommitHash = worktreePath && verdictDiffBase
+                    ? getCommitHash(worktreePath, verdictDiffBase)
+                    : undefined;
+                await postQaVerdictComment(issueNumber, result.verdict, result.summary, verdictCommitHash, iteration, log, injectedPostComment);
+            }
             // Log phase result with observability data (AC-1, AC-2, AC-3, AC-7)
             if (logWriter) {
                 // Resolve the diff base once (#878): worktrees branch from
@@ -1222,10 +1290,14 @@ export async function runIssueWithLogging(ctx) {
                     // Build enriched config for loop phase with QA context (#488).
                     // Pass verdict, failed ACs, and error directly so the /loop skill
                     // doesn't need to reconstruct context from GitHub comments.
+                    // #937 AC-3: exclude `document`/`pause_for_human`-tagged findings
+                    // from what the loop is told to fix (same filter as ready-gate's
+                    // fixableGaps).
+                    const fixableGaps = selectFixableGaps(result.summary);
                     const loopConfig = {
                         ...issueConfig,
                         lastVerdict: result.verdict ?? undefined,
-                        failedAcs: result.summary?.gaps?.join("; ") ?? undefined,
+                        failedAcs: fixableGaps.length ? fixableGaps.join("; ") : undefined,
                         promptContext: buildLoopContext(result),
                     };
                     const loopStartTime = new Date();
@@ -1335,10 +1407,13 @@ export async function runIssueWithLogging(ctx) {
     // Hoisted out of the `if (stateManager)` block below because the checkpoint
     // warning also has to name this status, and naming the wrong one is exactly
     // the #837 inaccuracy being fixed here.
+    const qaVerdict = phaseResults.find((p) => p.phase === "qa")?.verdict;
     const finalStatus = readyGateResult
         ? readyGateResult.issueStatus
         : success
-            ? "ready_for_merge"
+            ? qaVerdict === "NEEDS_VERIFICATION"
+                ? "awaiting_verification"
+                : "ready_for_merge"
             : "in_progress";
     if (stateManager) {
         try {

package/dist/src/lib/workflow/config-resolver.d.ts

@@ -7,7 +7,7 @@
  * @module
  */
 import { type ExecutionConfig, type RunOptions } from "./types.js";
-import type { SequantSettings } from "../settings.js";
+import type { SequantSettings, ModelRoles } from "../settings.js";
 /**
  * Layers for config resolution.
  * Each field is optional — only defined values participate in merging.
@@ -72,6 +72,19 @@ export declare function positiveOr(value: number | undefined, fallback: number):
 export interface PhasePolicy {
     model?: string;
     effort?: string;
+    /**
+     * The original `role:<name>` string before resolution (#975). Set only when
+     * a `role:` prefix was used; absent for raw model strings. Allows metrics to
+     * record both what the user configured and what was actually dispatched.
+     */
+    requestedModel?: string;
+    /**
+     * Concrete model ID from `modelUsage` after phase execution (#975). Not
+     * present on the static config — populated by `enrichPhasePoliciesFromResults`
+     * just before the run is written to metrics. Absent for phases that did not
+     * execute or drivers that do not report `modelUsage`.
+     */
+    resolvedModel?: string;
 }
 /**
  * Parse a `--models`/`--efforts` CLI spec into a phase → value map.
@@ -83,6 +96,21 @@ export interface PhasePolicy {
  * malformed spec must never silently resolve to "nothing configured".
  */
 export declare function parsePhaseSpec(spec: string, phaseNames: string[]): Record<string, string>;
+/**
+ * Resolve a model-or-role reference to a concrete model string (#975).
+ *
+ * - No `role:` prefix → returns verbatim (backward compat, AC-3).
+ * - `role:<name>` → looks up `<name>` in `modelRoles`.
+ *   - Missing entry → throws, naming the role and available keys (AC-2).
+ *   - String value → desugars to `{ "claude-code": value }`, picks by `activeDriver`.
+ *   - Object value → picks by `activeDriver`; missing driver key → throws.
+ * - A role that resolves to a string for a different driver throws (AC-2).
+ *
+ * @param roleOrString - The model string from config/CLI (may have `role:` prefix).
+ * @param modelRoles   - The resolved `run.modelRoles` map.
+ * @param activeDriver - Driver registry name (default: `"claude-code"`).
+ */
+export declare function resolveRoleToModel(roleOrString: string, modelRoles?: ModelRoles, activeDriver?: string): string;
 /**
  * Resolve per-phase model/effort policies with CLI > settings > absent
  * precedence.
@@ -92,7 +120,7 @@ export declare function parsePhaseSpec(spec: string, phaseNames: string[]): Reco
  * two `phaseTimeout` producers did in #833 — see `positiveOr`'s doc comment
  * for that history.
  */
-export declare function resolvePhasePolicies(cliModels: string | undefined, cliEfforts: string | undefined, settingsPhases: Record<string, PhasePolicy> | undefined, phaseNames: string[]): Record<string, PhasePolicy>;
+export declare function resolvePhasePolicies(cliModels: string | undefined, cliEfforts: string | undefined, settingsPhases: Record<string, PhasePolicy> | undefined, phaseNames: string[], modelRoles?: ModelRoles, activeDriver?: string): Record<string, PhasePolicy>;
 /**
  * Build an ExecutionConfig from merged RunOptions and settings.
  * Extracts the phase-timeout, MCP, retry, and mode resolution logic

package/dist/src/lib/workflow/config-resolver.js

@@ -7,6 +7,7 @@
  * @module
  */
 import { DEFAULT_CONFIG, DEFAULT_PHASES, } from "./types.js";
+import { DEFAULT_MODEL_ROLES } from "../settings.js";
 import { getEnvConfig } from "./batch-executor.js";
 import { getPhaseNames } from "./phase-registry.js";
 /**
@@ -213,6 +214,46 @@ function applyPhaseSpec(target, parsed, field, phaseNames) {
         target[phase] = { ...target[phase], [field]: value };
     }
 }
+/**
+ * Resolve a model-or-role reference to a concrete model string (#975).
+ *
+ * - No `role:` prefix → returns verbatim (backward compat, AC-3).
+ * - `role:<name>` → looks up `<name>` in `modelRoles`.
+ *   - Missing entry → throws, naming the role and available keys (AC-2).
+ *   - String value → desugars to `{ "claude-code": value }`, picks by `activeDriver`.
+ *   - Object value → picks by `activeDriver`; missing driver key → throws.
+ * - A role that resolves to a string for a different driver throws (AC-2).
+ *
+ * @param roleOrString - The model string from config/CLI (may have `role:` prefix).
+ * @param modelRoles   - The resolved `run.modelRoles` map.
+ * @param activeDriver - Driver registry name (default: `"claude-code"`).
+ */
+export function resolveRoleToModel(roleOrString, modelRoles = DEFAULT_MODEL_ROLES, activeDriver = "claude-code") {
+    if (!roleOrString.startsWith("role:")) {
+        return roleOrString;
+    }
+    const roleName = roleOrString.slice("role:".length);
+    if (!roleName) {
+        throw new Error(`Invalid role reference "role:" — role name is empty. Available roles: ${Object.keys(modelRoles).join(", ")}.`);
+    }
+    const entry = modelRoles[roleName];
+    if (entry === undefined) {
+        throw new Error(`Role "${roleName}" is not defined in run.modelRoles. Available roles: ${Object.keys(modelRoles).join(", ")}.`);
+    }
+    if (typeof entry === "string") {
+        // String shorthand desugars to { "claude-code": value } — only for claude-code.
+        if (activeDriver !== "claude-code") {
+            throw new Error(`Role "${roleName}" uses a string shorthand (claude-code only) but the active driver is "${activeDriver}". Use an object map to define per-driver models.`);
+        }
+        return entry;
+    }
+    // Object map: pick by driver.
+    const resolved = entry[activeDriver];
+    if (resolved === undefined) {
+        throw new Error(`Role "${roleName}" has no entry for driver "${activeDriver}". Available drivers in this role: ${Object.keys(entry).join(", ")}.`);
+    }
+    return resolved;
+}
 /**
  * Resolve per-phase model/effort policies with CLI > settings > absent
  * precedence.
@@ -222,7 +263,7 @@ function applyPhaseSpec(target, parsed, field, phaseNames) {
  * two `phaseTimeout` producers did in #833 — see `positiveOr`'s doc comment
  * for that history.
  */
-export function resolvePhasePolicies(cliModels, cliEfforts, settingsPhases, phaseNames) {
+export function resolvePhasePolicies(cliModels, cliEfforts, settingsPhases, phaseNames, modelRoles, activeDriver) {
     const result = {};
     // Layer 1 (lowest): settings.run.phases. Skip any phase name settings
     // validation already didn't recognize — that's surfaced as a settings
@@ -243,6 +284,20 @@ export function resolvePhasePolicies(cliModels, cliEfforts, settingsPhases, phas
     if (cliEfforts) {
         applyPhaseSpec(result, parsePhaseSpec(cliEfforts, phaseNames), "effort", phaseNames);
     }
+    // Role resolution (#975): resolve any `role:<name>` model references to
+    // concrete model strings. Raw strings (no `role:` prefix) pass through
+    // verbatim — this is AC-3 backward compat.
+    if (modelRoles) {
+        for (const [phase, policy] of Object.entries(result)) {
+            if (policy.model && policy.model.startsWith("role:")) {
+                result[phase] = {
+                    ...policy,
+                    requestedModel: policy.model, // capture pre-resolution value (AC-4)
+                    model: resolveRoleToModel(policy.model, modelRoles, activeDriver),
+                };
+            }
+        }
+    }
     return result;
 }
 /**
@@ -285,6 +340,7 @@ export function buildExecutionConfig(mergedOptions, settings, issueCount) {
         maxIterations: positiveOr(mergedOptions.maxIterations, positiveOr(settings.run.maxIterations, DEFAULT_CONFIG.maxIterations)),
         noSmartTests: mergedOptions.noSmartTests ?? false,
         mcp: mcpEnabled,
+        mcpAllowlist: settings.run.mcpAllowlist,
         retry: retryEnabled,
         // #804: default 0 (off) — the whole regression contract for auto-wait is
         // that an unset flag leaves the #761/#799 halt path untouched.
@@ -303,7 +359,8 @@ export function buildExecutionConfig(mergedOptions, settings, issueCount) {
         // #914: CLI > settings > absent, via the shared resolver both
         // ExecutionConfig producers call (see `resolvePhasePolicies`'s doc
         // comment for the #833 drift this guards against).
-        phasePolicies: resolvePhasePolicies(mergedOptions.models, mergedOptions.efforts, settings.run.phases, getPhaseNames()),
+        // #975: pass modelRoles + active driver so `role:` prefixes resolve.
+        phasePolicies: resolvePhasePolicies(mergedOptions.models, mergedOptions.efforts, settings.run.phases, getPhaseNames(), settings.run.modelRoles, settings.run.agent ?? "claude-code"),
         // #915: CLI > settings > default `false` — mirrors the `readyGate`
         // precedent above. Both `ExecutionConfig` producers (here and
         // `ready-gate.ts:buildPhaseConfig`) resolve this the same way (#833).

package/dist/src/lib/workflow/drivers/agent-driver.d.ts

@@ -32,6 +32,13 @@ export interface AgentExecutionConfig {
     phaseTimeout: number;
     verbose: boolean;
     mcp: boolean;
+    /**
+     * Claude Desktop MCP server names explicitly opted in to pass through to
+     * this phase, despite `mcp`'s default exclusion (#936). Forwarded
+     * verbatim to `getPhaseMcpServersConfig`'s `desktopAllowlist` by
+     * ClaudeCodeDriver; ignored by drivers without an MCP concept.
+     */
+    mcpAllowlist?: string[];
     /**
      * Resume a previous session (driver-specific; ignored if unsupported).
      *
@@ -102,6 +109,13 @@ export interface AgentPhaseResult {
     stdoutTail?: string[];
     /** Process exit code (undefined for SDK-based drivers) (#447) */
     exitCode?: number;
+    /**
+     * Per-model usage totals from the SDK result (#975). Keys are concrete model
+     * IDs (e.g. `"claude-sonnet-5"`); first key is the resolved model string used
+     * for this phase. Only set by SDK-based drivers (claude-code); undefined for
+     * subprocess drivers (aider).
+     */
+    modelUsage?: Record<string, unknown>;
 }
 /**
  * Interface that all agent backends must implement.

package/dist/src/lib/workflow/drivers/claude-code.js

@@ -5,8 +5,8 @@
  * orchestration layer should import the SDK directly.
  */
 import { query } from "@anthropic-ai/claude-agent-sdk";
-import { getMcpServersConfig } from "../../system.js";
-import { RateLimitError, BillingError, createRateLimitError, isWaitableWindow, isRateLimitFailureInfo, } from "../../errors.js";
+import { getPhaseMcpServersConfig } from "../../mcp-config.js";
+import { ApiError, RateLimitError, BillingError, createRateLimitError, isWaitableWindow, isRateLimitFailureInfo, } from "../../errors.js";
 import { RingBuffer } from "../ring-buffer.js";
 export class ClaudeCodeDriver {
     name = "claude-code";
@@ -80,8 +80,14 @@ export class ClaudeCodeDriver {
             resumeToken = undefined;
         }
         try {
-            // Get MCP servers config if enabled
-            const mcpServers = config.mcp ? getMcpServersConfig() : undefined;
+            // Get MCP servers config if enabled — allowlisted, not passed through
+            // from Claude Desktop config (#936), except for servers explicitly
+            // named in config.mcpAllowlist (settings.run.mcpAllowlist).
+            const mcpServers = config.mcp
+                ? getPhaseMcpServersConfig(config.cwd, {
+                    desktopAllowlist: config.mcpAllowlist,
+                })
+                : undefined;
             const queryInstance = query({
                 prompt,
                 options: {
@@ -167,6 +173,31 @@ export class ClaudeCodeDriver {
             const structuredError = this.buildStructuredError(rateLimitInfo, assistantError, apiRetryError);
             if (resultMessage) {
                 if (resultMessage.subtype === "success") {
+                    // The SDK emits subtype "success" with is_error:true when the turn
+                    // ends on an API error (e.g. unrecognized model). Treat it as a
+                    // phase failure so the caller gets a real error, not a zero-work
+                    // success. See #973 / SDK docs §SDKResultMessage.
+                    if (resultMessage.is_error) {
+                        const metadata = {};
+                        if (resultMessage.api_error_status != null) {
+                            metadata.statusCode = resultMessage.api_error_status;
+                            metadata.api_error_status = resultMessage.api_error_status;
+                        }
+                        if (resultMessage.terminal_reason != null) {
+                            metadata.terminal_reason = resultMessage.terminal_reason;
+                        }
+                        const apiError = new ApiError(resultMessage.result, metadata);
+                        return {
+                            success: false,
+                            output: capturedOutput,
+                            sessionId: resultSessionId,
+                            resumeHandle,
+                            error: resultMessage.result,
+                            structuredError: apiError,
+                            stderrTail: stderrBuffer.getLines(),
+                            stdoutTail: stdoutBuffer.getLines(),
+                        };
+                    }
                     return {
                         success: true,
                         output: capturedOutput,
@@ -174,6 +205,7 @@ export class ClaudeCodeDriver {
                         resumeHandle,
                         stderrTail: stderrBuffer.getLines(),
                         stdoutTail: stdoutBuffer.getLines(),
+                        modelUsage: resultMessage.modelUsage,
                     };
                 }
                 // Turn-cap is a soft, recoverable outcome, not a hard failure: the

package/dist/src/lib/workflow/metrics-schema.d.ts

@@ -116,6 +116,8 @@ export declare const MetricRunSchema: z.ZodObject<{
     phasePolicies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         model: z.ZodOptional<z.ZodString>;
         effort: z.ZodOptional<z.ZodString>;
+        requestedModel: z.ZodOptional<z.ZodString>;
+        resolvedModel: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     effortEscalations: z.ZodOptional<z.ZodArray<z.ZodObject<{
         phase: z.ZodString;
@@ -176,6 +178,8 @@ export declare const MetricsSchema: z.ZodObject<{
         phasePolicies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
             model: z.ZodOptional<z.ZodString>;
             effort: z.ZodOptional<z.ZodString>;
+            requestedModel: z.ZodOptional<z.ZodString>;
+            resolvedModel: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
         effortEscalations: z.ZodOptional<z.ZodArray<z.ZodObject<{
             phase: z.ZodString;
@@ -215,15 +219,20 @@ export declare function createMetricRun(options: {
     flags?: string[];
     failureCategory?: FailureCategory;
     /**
-     * Resolved per-phase model/effort overrides (#914), keyed by phase name.
+     * Resolved per-phase model/effort overrides (#914/#975), keyed by phase name.
      * Pass only the phases that actually had a configured override — a phase
      * that inherited the CLI default should not appear here at all. See
      * `resolvePhasePolicies` in `config-resolver.ts`, which already produces
      * a map shaped this way.
+     *
+     * `requestedModel` and `resolvedModel` are #975 additions — pass when available
+     * to enable cross-time benchmark comparisons as the model roster evolves.
      */
     phasePolicies?: Record<string, {
         model?: string;
         effort?: string;
+        requestedModel?: string;
+        resolvedModel?: string;
     }>;
     /**
      * Effort escalations applied during this run (#915), one entry per

package/dist/src/lib/workflow/metrics-schema.js

@@ -103,9 +103,21 @@ export const MetricRunSchema = z.object({
      * undefined fields. Enum/alias strings only, consistent with this
      * schema's no-file-paths/no-content privacy contract. Optional and
      * additive — absent on records written before this field existed.
+     *
+     * `requestedModel` and `resolvedModel` are added in #975 to record the
+     * role string (pre-resolution) and the concrete model ID from `modelUsage`
+     * (post-execution) respectively — enabling cross-time benchmark comparisons
+     * as the model roster moves under aliases.
      */
     phasePolicies: z
-        .record(z.string(), z.object({ model: z.string().optional(), effort: z.string().optional() }))
+        .record(z.string(), z.object({
+        model: z.string().optional(),
+        effort: z.string().optional(),
+        /** The role string or raw model string as configured (pre-resolution, #975). */
+        requestedModel: z.string().optional(),
+        /** The concrete model ID from `modelUsage` after execution (#975). */
+        resolvedModel: z.string().optional(),
+    }))
         .optional(),
     /**
      * Effort escalations applied during this run (#915), one entry per

package/dist/src/lib/workflow/metrics-writer.d.ts

@@ -70,10 +70,12 @@ export declare class MetricsWriter {
         model?: string;
         flags?: string[];
         failureCategory?: FailureCategory;
-        /** Resolved per-phase model/effort overrides (#914). See `createMetricRun`. */
+        /** Resolved per-phase model/effort overrides (#914/#975). See `createMetricRun`. */
         phasePolicies?: Record<string, {
             model?: string;
             effort?: string;
+            requestedModel?: string;
+            resolvedModel?: string;
         }>;
         /** Effort escalations applied during this run (#915). See `createMetricRun`. */
         effortEscalations?: Array<{

package/dist/src/lib/workflow/mutation-marker.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Parseable mutation-verification markers for `/qa` §6i (#939).
+ *
+ * CLAUDE.md's testing rule ("Gate tests ship with a recorded mutation
+ * result") was honor-system prose — nothing parsed or checked the recorded
+ * result, so compliance was invisible (see #830, #834's "prose only, and
+ * therefore unenforceable" defect class). This module promotes that record
+ * to a parseable PR-body marker:
+ *
+ * ```
+ * <!-- SEQUANT_MUTATION: {"ac":"AC-3","mutation":"removed payload fixture
+ * block","failedTest":"injection.test.ts > rejects payload"} -->
+ * ```
+ *
+ * Same durable-marker idiom as `SEQUANT_SPEC` (spec-recommendation.ts) and
+ * `SEQUANT_PHASE` (phase-detection.ts): a flat-JSON HTML comment, matched
+ * with the `{[^}]+}` regex family. That regex stops at the FIRST `}`, so the
+ * payload must stay flat — a nested object would truncate mid-JSON and fail
+ * to parse. Unlike those two markers (one recommendation / one status per
+ * comment, latest-wins), a PR body carries one `SEQUANT_MUTATION` marker per
+ * AC, so all markers are collected, not just the latest.
+ */
+import { z } from "zod";
+declare const MutationMarkerSchema: z.ZodObject<{
+    ac: z.ZodString;
+    mutation: z.ZodString;
+    failedTest: z.ZodString;
+}, z.core.$strip>;
+export type MutationMarker = z.infer<typeof MutationMarkerSchema>;
+export type MutationMarkerClassification = "valid" | "test_not_in_diff";
+export interface ClassifiedMutationMarker extends MutationMarker {
+    classification: MutationMarkerClassification;
+}
+/**
+ * Parse every `SEQUANT_MUTATION` marker from a PR body.
+ *
+ * Markers inside fenced code blocks or inline code (e.g. a doc example
+ * showing the marker format) are ignored, matching `parsePhaseMarkers`.
+ * Malformed JSON or schema-invalid entries are skipped silently rather than
+ * thrown — one bad marker must not take down the rest of the PR body's
+ * markers.
+ *
+ * Called with just `prBody`, this only parses. Given a second argument —
+ * the diff's test-file paths — it also **rejects** markers naming a test
+ * absent from the diff, attaching a `classification` to each result rather
+ * than silently dropping the rejected ones (a fabricated marker is worse
+ * than a missing one; it must be visible, not discarded). The two-argument
+ * form is what makes this function itself the rejecting entry point AC-3
+ * names, while the one-argument form stays free of a git-diff dependency
+ * for parser-only tests.
+ *
+ * @param prBody - The full PR body text
+ * @param diffTestFiles - When provided, test file paths present in the PR's
+ *   diff; each returned marker is classified against them
+ * @returns Every valid marker found, in document order — classified when
+ *   `diffTestFiles` is provided
+ */
+export declare function parseMutationMarkers(prBody: string): MutationMarker[];
+export declare function parseMutationMarkers(prBody: string, diffTestFiles: string[]): ClassifiedMutationMarker[];
+/**
+ * Reduce a marker list to one-per-AC, the later marker winning.
+ *
+ * A re-run's marker (e.g. after amending the PR body) supersedes the
+ * earlier one for the same AC — the same "latest wins" idiom
+ * `resolveSpecRecommendation` uses for `SEQUANT_SPEC`.
+ *
+ * @param markers - Markers as returned by {@link parseMutationMarkers}
+ * @returns Map keyed by AC id, one marker per key
+ */
+export declare function latestMutationMarkerPerAc(markers: MutationMarker[]): Map<string, MutationMarker>;
+/**
+ * Classify a marker's `failedTest` against the diff's actual test files.
+ *
+ * A fabricated marker (naming a test that doesn't exist in the diff) is
+ * worse than a missing one — it claims verification that never happened.
+ * `failedTest` follows the `<file> > <test name>` shape `/qa` §6i renders
+ * in its output table (e.g. `injection.test.ts > rejects payload`); only
+ * the file segment is checked, since the suite/test-name portion after
+ * ` > ` isn't independently verifiable without executing the test.
+ *
+ * @param marker - A single parsed marker
+ * @param diffTestFiles - Test file paths present in the PR's diff
+ * @returns `"valid"` when the named file is in the diff, `"test_not_in_diff"` otherwise
+ */
+export declare function classifyMutationMarker(marker: MutationMarker, diffTestFiles: string[]): MutationMarkerClassification;
+export {};