sequant 2.10.0 → 2.11.0

package/dist/src/lib/test-tautology-detector.d.ts

@@ -104,12 +104,13 @@ export declare function extractTestBlocks(content: string): Array<{
  * when it references an imported production function, directly spawns the
  * project's build output, or calls a helper that (transitively) does so.
  *
- * @param spawnHandles Names of describe/module-scope helpers that spawn the
- *   build output (see {@link collectSpawnHandles}).
+ * @param productionHandles Names of describe/module-scope helpers that reach
+ *   production — by spawning the project's executable code or by calling an
+ *   imported production function (see {@link collectProductionHandles}).
  * @param buildOutputVars Variable names bound to a build-output path (see
  *   {@link collectBuildOutputVars}).
  */
-export declare function testBlockCallsProductionCode(body: string, importedFunctions: ImportedFunction[], spawnHandles?: string[], buildOutputVars?: string[]): boolean;
+export declare function testBlockCallsProductionCode(body: string, importedFunctions: ImportedFunction[], productionHandles?: string[], buildOutputVars?: string[]): boolean;
 /**
  * Check if a file opts out of tautology detection via pragma comment.
  *

package/dist/src/lib/test-tautology-detector.js

@@ -369,20 +369,39 @@ const SPAWN_PATTERN = /(?:\b(?:execFileSync|spawnSync|execSync|execFile)\s*\(|(?
  */
 const BUILD_OUTPUT_PATTERN = /\bdist\//;
 /**
- * Collect names of variables bound to a build-output path, e.g.
+ * Non-compiled production code this project ships and executes: the hook
+ * scripts and the `scripts/` + `templates/scripts/` trees (#906).
+ *
+ * `dist/` alone was too narrow. `checkout-lock.integration.test.ts` drives the
+ * real `.claude/hooks/pre-tool.sh` as a subprocess — that hook IS the
+ * enforcement half of the feature under test — yet every block in the file
+ * read as tautological because the path is not under `dist/`.
+ */
+const PROJECT_SCRIPT_PATTERN = /\b(?:hooks\/[\w.-]+\.sh|scripts\/[\w./-]+)/;
+/**
+ * Collect names of variables bound to a path into the project's own executable
+ * code, e.g.
  *   const cliPath = resolve(projectRoot, "dist/bin/cli.js");
- * captures `cliPath`. Tests almost always spawn via such a handle rather than
- * an inline string, so these names stand in for the literal build path.
+ *   const HOOK    = join(REPO_ROOT, ".claude/hooks/pre-tool.sh");
+ * captures `cliPath` / `HOOK`. Tests almost always spawn via such a handle
+ * rather than an inline string, so these names stand in for the literal path.
  *
  * The right-hand side is statement-bounded (`[^;]`) so a match cannot bleed
- * across declarations, and must contain the `dist/` marker.
+ * across declarations, and must reach one of the two markers. Spawning a
+ * *system* binary (`git`, `bash` with a temp fixture) matches neither, which
+ * is the intended exclusion — those are not this project's code.
  */
 function collectBuildOutputVars(content) {
     const names = new Set();
-    const pattern = /(?:const|let|var)\s+(\w+)\s*=\s*[^;]*?\bdist\//g;
-    let match;
-    while ((match = pattern.exec(content)) !== null) {
-        names.add(match[1]);
+    const patterns = [
+        /(?:const|let|var)\s+(\w+)\s*=\s*[^;]*?\bdist\//g,
+        /(?:const|let|var)\s+(\w+)\s*=\s*[^;]*?\b(?:hooks\/[\w.-]+\.sh|scripts\/[\w./-]+)/g,
+    ];
+    for (const pattern of patterns) {
+        let match;
+        while ((match = pattern.exec(content)) !== null) {
+            names.add(match[1]);
+        }
     }
     return [...names];
 }
@@ -391,7 +410,7 @@ function collectBuildOutputVars(content) {
  * `dist/` marker or one of the collected build-path variable names.
  */
 function referencesBuildOutput(body, buildOutputVars) {
-    if (BUILD_OUTPUT_PATTERN.test(body)) {
+    if (BUILD_OUTPUT_PATTERN.test(body) || PROJECT_SCRIPT_PATTERN.test(body)) {
         return true;
     }
     return buildOutputVars.some((name) => referenceMatcher(name).test(body));
@@ -406,45 +425,84 @@ function spawnsBuildOutput(body, buildOutputVars) {
     return (SPAWN_PATTERN.test(body) && referencesBuildOutput(body, buildOutputVars));
 }
 /**
- * Extract module/describe-scope helper definitions (named block-bodied arrow
- * consts) as { name, body } pairs.
+ * Extract module/describe-scope helper definitions as { name, body } pairs.
+ *
+ * Two shapes, because both are idiomatic and a detector that saw only one
+ * produced large-scale false positives (#906): a test calling a helper the
+ * detector cannot see reads as import-less, hence tautological. Measured on
+ * `checkout-lock.integration.test.ts` (helpers written as `function`
+ * declarations): 17 of 19 blocks flagged, every one of them real.
  *
- * Anchors on `=> {` so a return-type object annotation
- *   const run = (): { stdout: string } => { ... }
- * is not mistaken for the function body. Params are matched with `[^()]*` (no
- * nested parens) to keep the scan from running away across the file. Only
- * block-bodied arrows are collected; the subprocess integration tests this
- * targets all use them.
+ * Params are matched with `[^()]*` (no nested parens) to keep the scan from
+ * running away across the file. Expression-bodied arrows are skipped — they
+ * have no `{` body to extract.
  */
 function extractHelperDefinitions(content) {
     const helpers = [];
-    const pattern = /(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\([^()]*\)\s*(?::[^=]*?)?=>\s*\{/g;
+    // Arrow consts anchor on `=> {`, so the body brace is unambiguous.
+    const arrowPattern = /(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\([^()]*\)\s*(?::[^=]*?)?=>\s*\{/g;
     let match;
-    while ((match = pattern.exec(content)) !== null) {
-        if (isInsideString(content, match.index)) {
+    while ((match = arrowPattern.exec(content)) !== null) {
+        if (isInsideString(content, match.index))
             continue;
-        }
-        const name = match[1];
-        // The final `{` of the match is the function body's opening brace.
         const braceIndex = match.index + match[0].length - 1;
-        const body = extractBlockBody(content.substring(braceIndex));
-        helpers.push({ name, body });
+        helpers.push({
+            name: match[1],
+            body: extractBlockBody(content.substring(braceIndex)),
+        });
+    }
+    // Declarations have no `=>` marker, and the return-type annotation may open
+    // a brace group of its own:
+    //   function runHook(o): { status: number; stderr: string } { ... }
+    // so the body is NOT simply the first `{` after the parameters. Do not try
+    // to express that in the regex — a greedy annotation subpattern silently ran
+    // past the body and anchored on the NEXT declaration's brace, yielding a
+    // "helper" whose body was somebody else's code (caught by the object
+    // return-type test below). Match only to the closing paren, then walk: take
+    // the first brace group; if another `{` follows it, that group was the
+    // return type and the body is the next one.
+    const declPattern = /(?:async\s+)?function\s*\*?\s*(\w+)\s*\([^()]*\)/g;
+    while ((match = declPattern.exec(content)) !== null) {
+        if (isInsideString(content, match.index))
+            continue;
+        const rest = content.substring(match.index + match[0].length);
+        const firstBrace = rest.indexOf("{");
+        if (firstBrace === -1)
+            continue;
+        // Anything between `)` and the first `{` must be an annotation, not code.
+        if (/[;)=]/.test(rest.substring(0, firstBrace)))
+            continue;
+        let body = extractBlockBody(rest.substring(firstBrace));
+        const after = rest.substring(firstBrace + body.length);
+        if (/^\s*\{/.test(after)) {
+            body = extractBlockBody(after);
+        }
+        helpers.push({ name: match[1], body });
     }
     return helpers;
 }
 /**
- * Collect the names of helper functions that spawn the build output, resolving
- * indirection transitively: a helper that calls an already-known spawn helper
- * is itself a spawn helper. This lets a test that only calls
- * `expectFlagAccepted(...)` (which calls `runInUninitializedDir`, which spawns
- * the CLI) count as exercising production code.
+ * Collect the names of helper functions that reach production code, resolving
+ * indirection transitively: a helper that calls an already-known handle is
+ * itself a handle. This lets a test that only calls `expectFlagAccepted(...)`
+ * (which calls `runInUninitializedDir`, which spawns the CLI) count as
+ * exercising production code.
+ *
+ * A helper qualifies two ways:
+ *  - it spawns the project's own executable code (subprocess integration
+ *    tests), or
+ *  - it references an imported production function (#906). `makeLock()`
+ *    returning `new CheckoutLock({...})` is production code by any reading,
+ *    but seeding on spawns alone missed it, so every test that built its
+ *    subject through a factory read as tautological.
  */
-function collectSpawnHandles(content, buildOutputVars) {
+function collectProductionHandles(content, buildOutputVars, importedFunctions = []) {
     const helpers = extractHelperDefinitions(content);
     const handles = new Set();
-    // Seed: helpers that directly spawn the build output.
+    // Seed: helpers that directly reach production.
     for (const helper of helpers) {
-        if (spawnsBuildOutput(helper.body, buildOutputVars)) {
+        if (spawnsBuildOutput(helper.body, buildOutputVars) ||
+            importedFunctions.some((fn) => referenceMatcher(fn.name).test(helper.body))) {
             handles.add(helper.name);
         }
     }
@@ -472,12 +530,13 @@ function collectSpawnHandles(content, buildOutputVars) {
  * when it references an imported production function, directly spawns the
  * project's build output, or calls a helper that (transitively) does so.
  *
- * @param spawnHandles Names of describe/module-scope helpers that spawn the
- *   build output (see {@link collectSpawnHandles}).
+ * @param productionHandles Names of describe/module-scope helpers that reach
+ *   production — by spawning the project's executable code or by calling an
+ *   imported production function (see {@link collectProductionHandles}).
  * @param buildOutputVars Variable names bound to a build-output path (see
  *   {@link collectBuildOutputVars}).
  */
-export function testBlockCallsProductionCode(body, importedFunctions, spawnHandles = [], buildOutputVars = []) {
+export function testBlockCallsProductionCode(body, importedFunctions, productionHandles = [], buildOutputVars = []) {
     // 1. References an imported production function.
     for (const fn of importedFunctions) {
         if (referenceMatcher(fn.name).test(body)) {
@@ -490,9 +549,10 @@ export function testBlockCallsProductionCode(body, importedFunctions, spawnHandl
     if (spawnsBuildOutput(body, buildOutputVars)) {
         return true;
     }
-    // 3. Calls a describe/module-scope helper that (transitively) spawns the
-    //    build output.
-    for (const handle of spawnHandles) {
+    // 3. Calls a describe/module-scope helper that (transitively) reaches
+    //    production — spawns the project's executable code, or calls an imported
+    //    production function (#906). Covers arrow-const and `function` helpers.
+    for (const handle of productionHandles) {
         if (referenceMatcher(handle).test(body)) {
             return true;
         }
@@ -529,13 +589,13 @@ export function analyzeTestFile(content, filePath) {
     try {
         const importedFunctions = extractImports(content);
         const buildOutputVars = collectBuildOutputVars(content);
-        const spawnHandles = collectSpawnHandles(content, buildOutputVars);
+        const productionHandles = collectProductionHandles(content, buildOutputVars, importedFunctions);
         const testBlocks = extractTestBlocks(content);
         const analyzedBlocks = testBlocks.map((block) => ({
             description: block.description,
             lineNumber: block.lineNumber,
             style: block.style,
-            isTautological: !testBlockCallsProductionCode(block.body, importedFunctions, spawnHandles, buildOutputVars),
+            isTautological: !testBlockCallsProductionCode(block.body, importedFunctions, productionHandles, buildOutputVars),
         }));
         const tautologicalCount = analyzedBlocks.filter((b) => b.isTautological).length;
         const totalTests = analyzedBlocks.length;

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, } 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";
@@ -876,22 +878,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 +1025,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 +1056,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) {
@@ -1356,7 +1393,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 +1477,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
@@ -219,5 +300,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

@@ -49,6 +49,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

@@ -96,6 +96,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;