sequant 2.10.0 → 2.12.0

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

@@ -10,13 +10,15 @@
 import chalk from "chalk";
 import { spawnSync } from "child_process";
 import { createPhaseLogFromTiming } from "./log-writer.js";
+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, 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 { detectPhasesFromLabels, parseRecommendedWorkflow, determinePhasesForIssue, DOCS_LABELS, } from "./phase-mapper.js";
+import { determinePhasesForIssue, DOCS_LABELS } from "./phase-mapper.js";
+import { resolveSpecRecommendation } from "./spec-recommendation.js";
 import { activateRelay, deactivateRelay, } from "../relay/activation.js";
 import { getSettings } from "../settings.js";
 import { GitHubProvider } from "./platforms/github.js";
@@ -133,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")}`);
@@ -562,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.
@@ -592,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;
@@ -618,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)`)
@@ -634,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;
@@ -876,22 +929,35 @@ export async function runIssueWithLogging(ctx) {
                 failureCategory: deriveFailureCategory(phaseResults),
             };
         }
-        // Parse recommended workflow from spec output
-        const parsedWorkflow = specResult.output
-            ? parseRecommendedWorkflow(specResult.output)
-            : null;
-        if (parsedWorkflow) {
-            // Remove spec from phases since we already ran it
-            phases = parsedWorkflow.phases.filter((p) => p !== "spec");
-            detectedQualityLoop = parsedWorkflow.qualityLoop;
-            log(chalk.gray(`    Spec recommends: ${phases.join(" → ")}${detectedQualityLoop ? " (quality loop)" : ""}`));
+        // Resolve the spec→run phase recommendation through the ordered chain
+        // comment-marker → comment-prose → chat-text → label-fallback (#921).
+        // Chat-text parsing alone is nondeterministic: the spec agent's plan
+        // comment is the durable artifact, but the old code only ever looked at
+        // ephemeral chat output, silently dropping recommended phases (e.g.
+        // testgen) whenever the agent posted the plan via a body file (#814).
+        const resolved = resolveSpecRecommendation({
+            chatOutput: specResult.output ?? "",
+            issueNumber,
+            labels,
+        });
+        // `resolveSpecRecommendation` already excludes "spec" regardless of
+        // which step in the chain produced the result.
+        phases = resolved.phases;
+        detectedQualityLoop = resolved.qualityLoop;
+        if (logWriter) {
+            logWriter.setSpecRecommendation({ source: resolved.source, phases, qualityLoop: detectedQualityLoop }, issueNumber);
+        }
+        if (resolved.source === "marker") {
+            log(chalk.gray(`    Spec recommends (marker): ${phases.join(" → ")}${detectedQualityLoop ? " (quality loop)" : ""}`));
+        }
+        else if (resolved.source === "comment-prose") {
+            log(chalk.gray(`    Spec recommends (comment): ${phases.join(" → ")}${detectedQualityLoop ? " (quality loop)" : ""}`));
+        }
+        else if (resolved.source === "chat") {
+            log(chalk.gray(`    Spec recommends (chat): ${phases.join(" → ")}${detectedQualityLoop ? " (quality loop)" : ""}`));
         }
         else {
-            // Fall back to label-based detection
             log(chalk.yellow(`    Could not parse spec recommendation, using label-based detection`));
-            const detected = detectPhasesFromLabels(labels);
-            phases = detected.phases.filter((p) => p !== "spec");
-            detectedQualityLoop = detected.qualityLoop;
             log(chalk.gray(`    Fallback: ${phases.join(" → ")}`));
         }
     }
@@ -1010,8 +1076,22 @@ export async function runIssueWithLogging(ctx) {
                     // State tracking errors shouldn't stop execution
                 }
             }
+            // #915: iteration > 1 is the outer quality-loop's retry signal — the
+            // same condition that triggers the "Quality loop iteration" log line
+            // above. This loop re-runs the WHOLE `phases` list on every iteration
+            // (it does not resume from the specific phase that failed), so the
+            // escalation is per RETRIED ITERATION, not per specific-phase-that-
+            // previously-failed: every phase dispatched while iteration > 1
+            // escalates, including one that already succeeded on iteration 1 (e.g.
+            // exec re-running alongside a retried qa). `withEscalatedEffort` is a
+            // no-op (returns the input config by reference) whenever escalation is
+            // off or this is the first attempt.
+            const { config: dispatchConfig, record: escalationRecord } = withEscalatedEffort(withActivityHook(issueConfig, issueNumber, phase, onProgress, makeWaitTransition(phase)), phase, iteration > 1);
+            if (escalationRecord && config.verbose) {
+                log(chalk.gray(`    effort: ${escalationRecord.base} → ${escalationRecord.escalated} (loop retry)`));
+            }
             const phaseStartTime = new Date();
-            const result = await executePhaseWithRetry(issueNumber, phase, withActivityHook(issueConfig, issueNumber, phase, onProgress, makeWaitTransition(phase)), resumeHandle, worktreePath, shutdownManager, phasePauseHandle, undefined, // executePhaseFn — use the default
+            const result = await executePhaseWithRetry(issueNumber, phase, dispatchConfig, resumeHandle, worktreePath, shutdownManager, phasePauseHandle, undefined, // executePhaseFn — use the default
             undefined, // delayFn — use the default
             autoWaitLedger);
             const phaseEndTime = new Date();
@@ -1027,7 +1107,15 @@ export async function runIssueWithLogging(ctx) {
                     }
                 }
             }
-            phaseResults.push(result);
+            phaseResults.push(escalationRecord
+                ? {
+                    ...result,
+                    escalatedEffort: {
+                        base: escalationRecord.base,
+                        escalated: escalationRecord.escalated,
+                    },
+                }
+                : result);
             // Emit completion/failure progress event (AC-8)
             const phaseDurationSec = Math.round((phaseEndTime.getTime() - phaseStartTime.getTime()) / 1000);
             if (result.success) {
@@ -1066,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
@@ -1185,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();
@@ -1356,7 +1465,23 @@ export async function runIssueWithLogging(ctx) {
     // warning and leave the issue at `success`. Recorded here and folded into the
     // returned `success` below.
     let prCreationError;
-    const shouldCreatePR = success && worktreePath && branch && !options.noPr;
+    const wouldCreatePR = success && worktreePath && branch && !options.noPr;
+    // #920: a phase-restricted run (e.g. `--phases spec`) provisions a worktree
+    // and branch unconditionally of which phases ran, so a clean spec-only pass
+    // satisfies every conjunct above with zero commits — `gh pr create` then
+    // fails with "No commits between main and …" and the run reports failed
+    // for work that landed exactly where it was supposed to (the plan comment).
+    // Gate on the evidence (commits ahead of base) rather than the phase list:
+    // `hasExecChanges` fails open (`unknown` counts as "has changes") so a git
+    // error here falls through to today's attempt-PR behavior, and it resolves
+    // the base the same #537-aware way `classifyExecChanges` already does for
+    // the exec zero-diff guard.
+    let prSkippedReason;
+    if (wouldCreatePR && !hasExecChanges(worktreePath)) {
+        prSkippedReason = `no commits ahead of ${baseBranch ?? "main"} (no implementing phase ran)`;
+        log(chalk.gray(`    ℹ️  PR skipped — ${prSkippedReason}`));
+    }
+    const shouldCreatePR = wouldCreatePR && !prSkippedReason;
     if (shouldCreatePR) {
         // #605: under --stacked, target predecessor branch (only for non-first,
         // non-last issues). Last PR keeps `main` so partial progress can land.
@@ -1424,10 +1549,16 @@ export async function runIssueWithLogging(ctx) {
         prNumber,
         prUrl,
         prCreationError,
+        prSkippedReason,
         checkpointFailed,
         failureCategory: overallSuccess
             ? undefined
-            : deriveFailureCategory(phaseResults),
+            : // #920: a PR-creation failure has no failed phase for
+                // `deriveFailureCategory` to classify — fall back to the dedicated
+                // category so the metrics residual from #879 (empty failureCategory
+                // on a PR-only failure) doesn't reopen for this failure path.
+                (deriveFailureCategory(phaseResults) ??
+                    (prCreationError ? "pr_creation" : undefined)),
         // #817: present only when `--ready-gate` ran the gate; the summary renders
         // its terminal reason (AC-6).
         readyGate: readyGateResult,

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

@@ -68,6 +68,31 @@ export declare function resolveRunOptions(cliOptions: RunOptions, settings: Sequ
  * ```
  */
 export declare function positiveOr(value: number | undefined, fallback: number): number;
+/** A single phase's resolved model/effort override (#914). */
+export interface PhasePolicy {
+    model?: string;
+    effort?: string;
+}
+/**
+ * Parse a `--models`/`--efforts` CLI spec into a phase → value map.
+ *
+ * Grammar: a bare value (`"sonnet"`) applies to every phase and resolves to
+ * `{"*": "sonnet"}`; a comma list of `phase=value` pairs (`"spec=fable,exec=sonnet"`)
+ * resolves per phase. Mixing the two forms, an empty phase/value, or an
+ * unrecognized phase name all fail fast — this is the CLI boundary, so a
+ * malformed spec must never silently resolve to "nothing configured".
+ */
+export declare function parsePhaseSpec(spec: string, phaseNames: string[]): Record<string, string>;
+/**
+ * Resolve per-phase model/effort policies with CLI > settings > absent
+ * precedence.
+ *
+ * This is the single resolver both `buildExecutionConfig` (here) and
+ * `ready-gate.ts:buildPhaseConfig` call, so they cannot drift the way the
+ * 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>;
 /**
  * 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

@@ -8,6 +8,7 @@
  */
 import { DEFAULT_CONFIG, DEFAULT_PHASES, } from "./types.js";
 import { getEnvConfig } from "./batch-executor.js";
+import { getPhaseNames } from "./phase-registry.js";
 /**
  * Coerce an env-var string to the type of the default value.
  * Returns the string as-is if no default exists for type inference.
@@ -164,6 +165,86 @@ export function positiveOr(value, fallback) {
         ? value
         : fallback;
 }
+/**
+ * Parse a `--models`/`--efforts` CLI spec into a phase → value map.
+ *
+ * Grammar: a bare value (`"sonnet"`) applies to every phase and resolves to
+ * `{"*": "sonnet"}`; a comma list of `phase=value` pairs (`"spec=fable,exec=sonnet"`)
+ * resolves per phase. Mixing the two forms, an empty phase/value, or an
+ * unrecognized phase name all fail fast — this is the CLI boundary, so a
+ * malformed spec must never silently resolve to "nothing configured".
+ */
+export function parsePhaseSpec(spec, phaseNames) {
+    const trimmed = spec.trim();
+    if (!trimmed) {
+        throw new Error("Malformed spec: value is empty.");
+    }
+    if (!trimmed.includes("=")) {
+        return { "*": trimmed };
+    }
+    const result = {};
+    for (const segment of trimmed.split(",")) {
+        const eq = segment.indexOf("=");
+        if (eq === -1) {
+            throw new Error(`Malformed spec segment '${segment}' — expected 'phase=value' (cannot mix a bare value with phase=value pairs).`);
+        }
+        const phase = segment.slice(0, eq).trim();
+        const value = segment.slice(eq + 1).trim();
+        if (!phase || !value) {
+            throw new Error(`Malformed spec segment '${segment}' — both phase and value are required.`);
+        }
+        if (!phaseNames.includes(phase)) {
+            throw new Error(`Unknown phase '${phase}'. Available phases: ${phaseNames.join(", ")}.`);
+        }
+        result[phase] = value;
+    }
+    return result;
+}
+/** Apply a parsed phase-spec map onto a policy accumulator for one field. */
+function applyPhaseSpec(target, parsed, field, phaseNames) {
+    const wildcard = parsed["*"];
+    if (wildcard !== undefined) {
+        for (const phase of phaseNames) {
+            target[phase] = { ...target[phase], [field]: wildcard };
+        }
+        return;
+    }
+    for (const [phase, value] of Object.entries(parsed)) {
+        target[phase] = { ...target[phase], [field]: value };
+    }
+}
+/**
+ * Resolve per-phase model/effort policies with CLI > settings > absent
+ * precedence.
+ *
+ * This is the single resolver both `buildExecutionConfig` (here) and
+ * `ready-gate.ts:buildPhaseConfig` call, so they cannot drift the way the
+ * two `phaseTimeout` producers did in #833 — see `positiveOr`'s doc comment
+ * for that history.
+ */
+export function resolvePhasePolicies(cliModels, cliEfforts, settingsPhases, phaseNames) {
+    const result = {};
+    // Layer 1 (lowest): settings.run.phases. Skip any phase name settings
+    // validation already didn't recognize — that's surfaced as a settings
+    // warning at load time (AC-1), not a resolver-time failure.
+    if (settingsPhases) {
+        for (const [phase, policy] of Object.entries(settingsPhases)) {
+            if (!phaseNames.includes(phase))
+                continue;
+            result[phase] = { ...policy };
+        }
+    }
+    // Layer 2 (highest): CLI --models/--efforts. Malformed specs throw here —
+    // callers at the CLI boundary (cli-flags.ts) turn that into a fail-fast
+    // InvalidArgumentError.
+    if (cliModels) {
+        applyPhaseSpec(result, parsePhaseSpec(cliModels, phaseNames), "model", phaseNames);
+    }
+    if (cliEfforts) {
+        applyPhaseSpec(result, parsePhaseSpec(cliEfforts, phaseNames), "effort", phaseNames);
+    }
+    return result;
+}
 /**
  * Build an ExecutionConfig from merged RunOptions and settings.
  * Extracts the phase-timeout, MCP, retry, and mode resolution logic
@@ -204,6 +285,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.
@@ -219,5 +301,13 @@ export function buildExecutionConfig(mergedOptions, settings, issueCount) {
         // load-bearing wire the #795 inert-flag class guards against — the flag is
         // useless if it stops reaching the executor here.
         readyGate: mergedOptions.readyGate ?? false,
+        // #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()),
+        // #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).
+        effortEscalation: mergedOptions.escalateEffort ?? settings.run.effortEscalation ?? false,
     };
 }

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).
      *
@@ -49,6 +56,21 @@ export interface AgentExecutionConfig {
     onStderr?: (text: string) => void;
     /** Relevant files for the phase (used by file-oriented drivers like Aider) */
     files?: string[];
+    /**
+     * Claude model to use for this phase (#914). Forwarded verbatim to the
+     * Agent SDK `query()` options by ClaudeCodeDriver; ignored by drivers
+     * without a model concept (Aider uses its own `AiderSettings.model`).
+     * Absent by default — the SDK falls back to the CLI default model.
+     */
+    model?: string;
+    /**
+     * Reasoning effort for this phase (#914). Forwarded verbatim to the Agent
+     * SDK `query()` options by ClaudeCodeDriver; ignored by drivers without an
+     * effort concept. Absent by default — the SDK defaults to `high`. Matches
+     * the SDK's own closed `EffortLevel` enum, not a bare `string`, so a value
+     * that reaches this field type-checks against `query()`'s options.
+     */
+    effort?: "low" | "medium" | "high" | "xhigh" | "max";
 }
 /**
  * Result returned by an agent after executing a phase.

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

@@ -5,7 +5,7 @@
  * orchestration layer should import the SDK directly.
  */
 import { query } from "@anthropic-ai/claude-agent-sdk";
-import { getMcpServersConfig } from "../../system.js";
+import { getPhaseMcpServersConfig } from "../../mcp-config.js";
 import { RateLimitError, BillingError, createRateLimitError, isWaitableWindow, isRateLimitFailureInfo, } from "../../errors.js";
 import { RingBuffer } from "../ring-buffer.js";
 export class ClaudeCodeDriver {
@@ -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: {
@@ -96,6 +102,11 @@ export class ClaudeCodeDriver {
                     ...(resumeToken ? { resume: resumeToken } : {}),
                     env: config.env,
                     ...(mcpServers ? { mcpServers } : {}),
+                    // #914: per-phase model/effort override. Omitted entirely when
+                    // unset (not `undefined`-valued) so the SDK's own default
+                    // resolution is untouched — see the AC-3 key-presence test.
+                    ...(config.model ? { model: config.model } : {}),
+                    ...(config.effort ? { effort: config.effort } : {}),
                     stderr: (data) => {
                         capturedStderr += data;
                         // Split on newlines and push each line to the ring buffer

package/dist/src/lib/workflow/effort-escalation.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Evidence-based effort escalation on quality-loop retries (#915).
+ *
+ * Sequant already detects several "this attempt is a retry" moments: the
+ * outer quality-loop re-entering a phase (`batch-executor.ts`) and the
+ * `sequant ready` QA-pass loop re-running `qa`/`loop` (`ready-gate.ts`).
+ * Escalation raises the phase's reasoning effort one tier for exactly that
+ * retried execution when the workflow observed a prior attempt fail — never
+ * speculatively, and never more than one tier per retry (see AC-6).
+ *
+ * Deliberately its own module rather than living beside `resolvePhasePolicies`
+ * in `config-resolver.ts`: `config-resolver.ts` imports `getEnvConfig` from
+ * `batch-executor.ts`, and `batch-executor.ts` is one of this module's
+ * dispatch-time callers, so co-locating here avoids introducing that cycle.
+ */
+import { EFFORT_LEVELS } from "../settings.js";
+import type { ExecutionConfig, Phase } from "./types.js";
+/**
+ * Base effort assumed for a phase with no configured `effort` override, when
+ * escalation needs a starting point to step up from (AC-5). `phase-executor.ts`
+ * omits the `effort` key entirely in that case (#914) so the Agent SDK's own
+ * default applies — #914 deliberately never encoded what that default is,
+ * since "omitted" is not the same claim as "equals X".
+ *
+ * Verified against `@anthropic-ai/claude-agent-sdk`'s own `query()` Options
+ * type (`sdk.d.ts`): `effort?: EffortLevel` is documented inline as
+ * `'high' — Deep reasoning (default)`. That is the SDK's default for the
+ * exact call sequant makes (raw `query()`, not the Claude Code CLI product —
+ * whose own `xhigh` default is a caller choice on top of this SDK, not the
+ * SDK's own default), so this constant is not a guess.
+ */
+export declare const DEFAULT_ESCALATION_BASE: (typeof EFFORT_LEVELS)[number];
+/**
+ * Pure ladder step: one tier above `base` on `EFFORT_LEVELS`, capped at the
+ * top (`max`). Returns `base` unchanged whenever `enabled` is false or this
+ * isn't a retry — the disabled/first-attempt path must be indistinguishable
+ * from #914 with escalation never having existed (AC-2).
+ *
+ * Always escalates from the phase's CONFIGURED base, never from a previously
+ * escalated value — callers must not accumulate escalation across iterations
+ * (AC-6): base `high` on the 3rd loop iteration is `xhigh`, not `max`.
+ */
+export declare function resolveEscalatedEffort(base: string | undefined, isRetry: boolean, enabled: boolean): string | undefined;
+/** One escalated execution, for observability (run metrics + verbose output). */
+export interface EscalationRecord {
+    phase: Phase;
+    base: string;
+    escalated: string;
+}
+export interface EscalationOutcome {
+    /**
+     * The config to dispatch with. Identical by reference to the input `config`
+     * whenever nothing escalated — so a shared `ExecutionConfig` object is never
+     * mutated and an escalation never leaks into a phase execution it wasn't
+     * computed for (AC-7).
+     */
+    config: ExecutionConfig;
+    /** Present only when this dispatch actually escalated. */
+    record?: EscalationRecord;
+}
+/**
+ * Apply escalation to ONE phase's execution, for THIS dispatch only.
+ *
+ * This is deliberately a per-execution decision made at the dispatch site,
+ * not a value baked into `ExecutionConfig` at build time: `buildExecutionConfig`
+ * / `buildPhaseConfig` run once per run/gate, not once per phase execution, so
+ * a static escalated value would leak across every phase in the chain and
+ * violate AC-7. The three retry-dispatch sites (batch-executor.ts's quality
+ * loop, ready-gate.ts's QA-pass loop `qa`/`loop` dispatch) call this function
+ * — and only this function — so they cannot drift on the cap/one-tier rules
+ * in AC-6 (see resolveEscalatedEffort's doc comment).
+ */
+export declare function withEscalatedEffort(config: ExecutionConfig, phase: Phase, isRetry: boolean): EscalationOutcome;

package/dist/src/lib/workflow/effort-escalation.js

@@ -0,0 +1,82 @@
+/**
+ * Evidence-based effort escalation on quality-loop retries (#915).
+ *
+ * Sequant already detects several "this attempt is a retry" moments: the
+ * outer quality-loop re-entering a phase (`batch-executor.ts`) and the
+ * `sequant ready` QA-pass loop re-running `qa`/`loop` (`ready-gate.ts`).
+ * Escalation raises the phase's reasoning effort one tier for exactly that
+ * retried execution when the workflow observed a prior attempt fail — never
+ * speculatively, and never more than one tier per retry (see AC-6).
+ *
+ * Deliberately its own module rather than living beside `resolvePhasePolicies`
+ * in `config-resolver.ts`: `config-resolver.ts` imports `getEnvConfig` from
+ * `batch-executor.ts`, and `batch-executor.ts` is one of this module's
+ * dispatch-time callers, so co-locating here avoids introducing that cycle.
+ */
+import { EFFORT_LEVELS } from "../settings.js";
+/**
+ * Base effort assumed for a phase with no configured `effort` override, when
+ * escalation needs a starting point to step up from (AC-5). `phase-executor.ts`
+ * omits the `effort` key entirely in that case (#914) so the Agent SDK's own
+ * default applies — #914 deliberately never encoded what that default is,
+ * since "omitted" is not the same claim as "equals X".
+ *
+ * Verified against `@anthropic-ai/claude-agent-sdk`'s own `query()` Options
+ * type (`sdk.d.ts`): `effort?: EffortLevel` is documented inline as
+ * `'high' — Deep reasoning (default)`. That is the SDK's default for the
+ * exact call sequant makes (raw `query()`, not the Claude Code CLI product —
+ * whose own `xhigh` default is a caller choice on top of this SDK, not the
+ * SDK's own default), so this constant is not a guess.
+ */
+export const DEFAULT_ESCALATION_BASE = "high";
+/**
+ * Pure ladder step: one tier above `base` on `EFFORT_LEVELS`, capped at the
+ * top (`max`). Returns `base` unchanged whenever `enabled` is false or this
+ * isn't a retry — the disabled/first-attempt path must be indistinguishable
+ * from #914 with escalation never having existed (AC-2).
+ *
+ * Always escalates from the phase's CONFIGURED base, never from a previously
+ * escalated value — callers must not accumulate escalation across iterations
+ * (AC-6): base `high` on the 3rd loop iteration is `xhigh`, not `max`.
+ */
+export function resolveEscalatedEffort(base, isRetry, enabled) {
+    if (!enabled || !isRetry)
+        return base;
+    const effectiveBase = (base ??
+        DEFAULT_ESCALATION_BASE);
+    const baseIdx = EFFORT_LEVELS.indexOf(effectiveBase);
+    const resolvedIdx = baseIdx === -1 ? EFFORT_LEVELS.indexOf(DEFAULT_ESCALATION_BASE) : baseIdx;
+    const nextIdx = Math.min(resolvedIdx + 1, EFFORT_LEVELS.length - 1);
+    return EFFORT_LEVELS[nextIdx];
+}
+/**
+ * Apply escalation to ONE phase's execution, for THIS dispatch only.
+ *
+ * This is deliberately a per-execution decision made at the dispatch site,
+ * not a value baked into `ExecutionConfig` at build time: `buildExecutionConfig`
+ * / `buildPhaseConfig` run once per run/gate, not once per phase execution, so
+ * a static escalated value would leak across every phase in the chain and
+ * violate AC-7. The three retry-dispatch sites (batch-executor.ts's quality
+ * loop, ready-gate.ts's QA-pass loop `qa`/`loop` dispatch) call this function
+ * — and only this function — so they cannot drift on the cap/one-tier rules
+ * in AC-6 (see resolveEscalatedEffort's doc comment).
+ */
+export function withEscalatedEffort(config, phase, isRetry) {
+    if (!config.effortEscalation || !isRetry)
+        return { config };
+    const currentPolicy = config.phasePolicies?.[phase];
+    const base = currentPolicy?.effort;
+    const escalated = resolveEscalatedEffort(base, isRetry, true);
+    if (!escalated || escalated === base)
+        return { config };
+    return {
+        config: {
+            ...config,
+            phasePolicies: {
+                ...config.phasePolicies,
+                [phase]: { ...currentPolicy, effort: escalated },
+            },
+        },
+        record: { phase, base: base ?? DEFAULT_ESCALATION_BASE, escalated },
+    };
+}