sequant 2.9.0 → 2.11.0

package/dist/src/lib/workflow/chain-resume.d.ts

@@ -2,28 +2,29 @@
  * Chain resume planning (#760).
  *
  * When a `--chain` run fails mid-way, earlier links may already be complete
- * (`ready_for_merge`) with a checkpoint commit on their feature branch
+ * (see `completed-status.ts`) with a checkpoint commit on their feature branch
  * (`createCheckpointCommit`, worktree-manager.ts). Re-running the same chain
  * should skip that completed prefix and resume at the first incomplete link,
  * rebased onto the last completed link's committed tip — NOT `main` (which is
  * the #748 wrong-base failure this reuses the #748 rebase path to avoid).
  *
- * The existing pre-flight guard (`run-orchestrator.ts`) already drops
- * `ready_for_merge`/`merged` issues from the run, but it is chain-unaware:
- * dropping the completed prefix leaves the first incomplete link at index 0,
- * where `executeSequential`'s successor-rebase never fires, so it silently
- * builds on `main`. This module computes a *chain-correct* resume plan that
- * preserves the completed prefix as the resume base.
+ * The non-chain pre-flight guard (`run-orchestrator.ts`) drops completed issues
+ * from the run using the same {@link isCompletedIssueStatus} predicate, but it
+ * is chain-unaware: dropping the completed prefix leaves the first incomplete
+ * link at index 0, where `executeSequential`'s successor-rebase never fires, so
+ * it silently builds on `main`. This module computes a *chain-correct* resume
+ * plan that preserves the completed prefix as the resume base.
  *
  * The planner is pure over an injected {@link CompletedLinkResolver} so the
  * skip/fail-fast state machine (AC-3) is unit-testable without real git; the
  * real-git rebase is covered by the integration test.
  */
+import { type CompletedIssueStatus } from "./completed-status.js";
 /** A completed link that will be skipped (not re-executed) on resume. */
 export interface ChainResumeSkip {
     issueNumber: number;
     /** Why it was skipped — the terminal-ish status that made it complete. */
-    status: "ready_for_merge" | "merged";
+    status: CompletedIssueStatus;
     /** The link's local feature branch (from state), if known. */
     branch?: string;
     /** The link's worktree path (from state), if known — used for the dirty check. */
@@ -45,9 +46,10 @@ export interface ChainResumePlan {
     /** First incomplete issue number (the resume point), if any. */
     resumeIssue?: number;
     /**
-     * Set when resume cannot proceed safely (AC-3): a `ready_for_merge` link's
-     * branch/checkpoint is gone and its tip is unreconstructable. The caller must
-     * abort rather than silently execute the successor on the wrong base.
+     * Set when resume cannot proceed safely (AC-3): an unmerged completed link's
+     * (`ready_for_merge` or `waiting_for_human_merge`) branch/checkpoint is gone
+     * and its tip is unreconstructable. The caller must abort rather than
+     * silently execute the successor on the wrong base.
      */
     failFast?: string;
     /** True when every link in the chain is already complete. */

package/dist/src/lib/workflow/chain-resume.js

@@ -2,24 +2,24 @@
  * Chain resume planning (#760).
  *
  * When a `--chain` run fails mid-way, earlier links may already be complete
- * (`ready_for_merge`) with a checkpoint commit on their feature branch
+ * (see `completed-status.ts`) with a checkpoint commit on their feature branch
  * (`createCheckpointCommit`, worktree-manager.ts). Re-running the same chain
  * should skip that completed prefix and resume at the first incomplete link,
  * rebased onto the last completed link's committed tip — NOT `main` (which is
  * the #748 wrong-base failure this reuses the #748 rebase path to avoid).
  *
- * The existing pre-flight guard (`run-orchestrator.ts`) already drops
- * `ready_for_merge`/`merged` issues from the run, but it is chain-unaware:
- * dropping the completed prefix leaves the first incomplete link at index 0,
- * where `executeSequential`'s successor-rebase never fires, so it silently
- * builds on `main`. This module computes a *chain-correct* resume plan that
- * preserves the completed prefix as the resume base.
+ * The non-chain pre-flight guard (`run-orchestrator.ts`) drops completed issues
+ * from the run using the same {@link isCompletedIssueStatus} predicate, but it
+ * is chain-unaware: dropping the completed prefix leaves the first incomplete
+ * link at index 0, where `executeSequential`'s successor-rebase never fires, so
+ * it silently builds on `main`. This module computes a *chain-correct* resume
+ * plan that preserves the completed prefix as the resume base.
  *
  * The planner is pure over an injected {@link CompletedLinkResolver} so the
  * skip/fail-fast state machine (AC-3) is unit-testable without real git; the
  * real-git rebase is covered by the integration test.
  */
-const COMPLETED_STATUSES = new Set(["ready_for_merge", "merged"]);
+import { isCompletedIssueStatus, } from "./completed-status.js";
 /**
  * Compute a chain-correct resume plan.
  *
@@ -37,7 +37,7 @@ export function computeChainResumePlan(orderedLinks, baseBranch, resolver) {
     const skipped = [];
     let firstIncomplete = 0;
     for (const link of orderedLinks) {
-        if (link.status && COMPLETED_STATUSES.has(link.status)) {
+        if (isCompletedIssueStatus(link.status)) {
             skipped.push({
                 issueNumber: link.issueNumber,
                 status: link.status,
@@ -72,17 +72,18 @@ export function computeChainResumePlan(orderedLinks, baseBranch, resolver) {
         resumeBaseCommit = resolver.resolveBaseTip();
     }
     else {
-        // ready_for_merge: the checkpoint tip lives only on the local feature
-        // branch. If that branch is gone (worktree/branch destroyed mid-way), the
-        // tip is unreconstructable — fail fast instead of wrong-basing the
-        // successor onto main (which would miss the completed link's work).
+        // ready_for_merge / waiting_for_human_merge: the checkpoint tip lives only
+        // on the local feature branch. If that branch is gone (worktree/branch
+        // destroyed mid-way), the tip is unreconstructable — fail fast instead of
+        // wrong-basing the successor onto main (which would miss the completed
+        // link's work).
         if (!last.branch) {
             return {
                 skipped,
                 active,
                 resumeIssue: active[0],
                 allComplete: false,
-                failFast: `#${last.issueNumber} is ready_for_merge but no branch is recorded in state — ` +
+                failFast: `#${last.issueNumber} is ${last.status} but no branch is recorded in state — ` +
                     `cannot reconstruct the resume base. Re-run with --force to redo the chain from scratch.`,
             };
         }
@@ -93,24 +94,27 @@ export function computeChainResumePlan(orderedLinks, baseBranch, resolver) {
                 active,
                 resumeIssue: active[0],
                 allComplete: false,
-                failFast: `#${last.issueNumber} is ready_for_merge but its branch "${last.branch}" no longer exists — ` +
+                failFast: `#${last.issueNumber} is ${last.status} but its branch "${last.branch}" no longer exists — ` +
                     `the resume base is unreconstructable. Re-run with --force to redo the chain from scratch.`,
             };
         }
         // The branch exists, but a tip is only a valid resume base if it actually
         // contains the link's work. `createCheckpointCommit` sweeps trailing
         // uncommitted changes into a checkpoint commit; when it fails (commit hook,
-        // staging error, or unrelated dirty files) the status was *already* written
-        // as ready_for_merge, so this link still reads as a completed prefix while
-        // its tip is missing work. Rebasing the successor onto it would be exactly
-        // the silent wrong-base execution AC-3 forbids — fail fast instead.
+        // staging error, or unrelated dirty files) a completed status was *already*
+        // written — `ready_for_merge` on a plain run, or `waiting_for_human_merge`
+        // when #817's `--ready-gate` owned the terminal status (#837) — so this link
+        // still reads as a completed prefix while its tip is missing work. Both
+        // statuses reach this branch, so the check covers gated links too. Rebasing
+        // the successor onto such a tip would be exactly the silent wrong-base
+        // execution AC-3 forbids — fail fast instead.
         if (last.worktree && resolver.isWorktreeDirty(last.worktree)) {
             return {
                 skipped,
                 active,
                 resumeIssue: active[0],
                 allComplete: false,
-                failFast: `#${last.issueNumber} is ready_for_merge but its worktree has uncommitted changes — ` +
+                failFast: `#${last.issueNumber} is ${last.status} but its worktree has uncommitted changes — ` +
                     `its checkpoint commit never landed, so branch "${last.branch}" is missing that work and ` +
                     `resuming #${active[0]} here would build on an incomplete base. Commit them in ${last.worktree}, ` +
                     `or re-run with --force to redo the chain from scratch.`,

package/dist/src/lib/workflow/completed-status.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Which persisted issue statuses mean "this issue is already done" (#837).
+ *
+ * Single source of truth for every pre-flight guard that skips finished work.
+ * It exists because the same predicate was previously spelled out inline at two
+ * sites with two different lists, and #817's `--ready-gate` extended the status
+ * vocabulary without either site following:
+ *
+ * - `chain-resume.ts` peels the completed prefix off a `--chain` run.
+ * - `run-orchestrator.ts` drops finished issues from a non-chain run.
+ *
+ * A gated issue deliberately terminates in `waiting_for_human_merge` (policy
+ * threshold reached) rather than `ready_for_merge`, since `ready_for_merge`
+ * would read as auto-merge-ready and defeat the human merge gate the feature
+ * exists to preserve. Both guards missed it, so re-running re-executed
+ * already-gated issues from phase 0 — a full spec/exec/qa pipeline plus another
+ * full-weight ready gate.
+ *
+ * `blocked` is deliberately NOT a completed status, for two reasons:
+ *
+ * 1. It is a *generic* member of `IssueStatusSchema` ("waiting on external input
+ *    or dependency"), not a ready-gate-exclusive terminal. Admitting it here
+ *    would silently apply to every other writer of that status, present and
+ *    future.
+ * 2. A guard halt IS the human-attention signal. Skipping it as complete would
+ *    report the issue as passed when it demonstrably did not.
+ *
+ * So a `blocked` issue is re-executed rather than skipped — the same
+ * conservative rule already applied to issues whose state lookup fails.
+ * Re-running wastes tokens; silently dropping an issue the user must look at is
+ * the worse failure. Once the user clears the blocker, the re-run is what lets
+ * work resume.
+ *
+ * NOTE: this is "done, do not re-run", which is NOT the same set as "might have
+ * a merged PR" — `state-cleanup.ts`'s merge-detection sweep deliberately keeps
+ * its own wider list (it also scans `in_progress`, #592, and
+ * `waiting_for_qa_gate`, #606). Do not unify the two.
+ *
+ * When adding a status to `IssueStatusSchema`, decide here whether it belongs.
+ */
+export declare const COMPLETED_ISSUE_STATUSES: readonly ["ready_for_merge", "merged", "waiting_for_human_merge"];
+/** A persisted status that counts as completed work. */
+export type CompletedIssueStatus = (typeof COMPLETED_ISSUE_STATUSES)[number];
+/**
+ * True iff `status` marks the issue as already finished, so a re-run should
+ * skip it unless `--force` is passed.
+ *
+ * Accepts `string | undefined` because persisted state may predate the current
+ * schema or be absent entirely; an unknown or missing status is treated as
+ * incomplete (re-execute), never as complete.
+ */
+export declare function isCompletedIssueStatus(status: string | undefined): status is CompletedIssueStatus;

package/dist/src/lib/workflow/completed-status.js

@@ -0,0 +1,57 @@
+/**
+ * Which persisted issue statuses mean "this issue is already done" (#837).
+ *
+ * Single source of truth for every pre-flight guard that skips finished work.
+ * It exists because the same predicate was previously spelled out inline at two
+ * sites with two different lists, and #817's `--ready-gate` extended the status
+ * vocabulary without either site following:
+ *
+ * - `chain-resume.ts` peels the completed prefix off a `--chain` run.
+ * - `run-orchestrator.ts` drops finished issues from a non-chain run.
+ *
+ * A gated issue deliberately terminates in `waiting_for_human_merge` (policy
+ * threshold reached) rather than `ready_for_merge`, since `ready_for_merge`
+ * would read as auto-merge-ready and defeat the human merge gate the feature
+ * exists to preserve. Both guards missed it, so re-running re-executed
+ * already-gated issues from phase 0 — a full spec/exec/qa pipeline plus another
+ * full-weight ready gate.
+ *
+ * `blocked` is deliberately NOT a completed status, for two reasons:
+ *
+ * 1. It is a *generic* member of `IssueStatusSchema` ("waiting on external input
+ *    or dependency"), not a ready-gate-exclusive terminal. Admitting it here
+ *    would silently apply to every other writer of that status, present and
+ *    future.
+ * 2. A guard halt IS the human-attention signal. Skipping it as complete would
+ *    report the issue as passed when it demonstrably did not.
+ *
+ * So a `blocked` issue is re-executed rather than skipped — the same
+ * conservative rule already applied to issues whose state lookup fails.
+ * Re-running wastes tokens; silently dropping an issue the user must look at is
+ * the worse failure. Once the user clears the blocker, the re-run is what lets
+ * work resume.
+ *
+ * NOTE: this is "done, do not re-run", which is NOT the same set as "might have
+ * a merged PR" — `state-cleanup.ts`'s merge-detection sweep deliberately keeps
+ * its own wider list (it also scans `in_progress`, #592, and
+ * `waiting_for_qa_gate`, #606). Do not unify the two.
+ *
+ * When adding a status to `IssueStatusSchema`, decide here whether it belongs.
+ */
+export const COMPLETED_ISSUE_STATUSES = [
+    "ready_for_merge",
+    "merged",
+    "waiting_for_human_merge",
+];
+const COMPLETED_ISSUE_STATUS_SET = new Set(COMPLETED_ISSUE_STATUSES);
+/**
+ * True iff `status` marks the issue as already finished, so a re-run should
+ * skip it unless `--force` is passed.
+ *
+ * Accepts `string | undefined` because persisted state may predate the current
+ * schema or be absent entirely; an unknown or missing status is treated as
+ * incomplete (re-execute), never as complete.
+ */
+export function isCompletedIssueStatus(status) {
+    return status !== undefined && COMPLETED_ISSUE_STATUS_SET.has(status);
+}

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

@@ -42,6 +42,57 @@ export declare function normalizeCommanderOptions(options: RunOptions): RunOptio
  * This replaces the inline merging logic previously in run.ts.
  */
 export declare function resolveRunOptions(cliOptions: RunOptions, settings: SequantSettings): RunOptions;
+/**
+ * Fall back to `fallback` unless `value` is a usable positive number.
+ *
+ * `??` alone is not enough for these (#833). `NaN` is not nullish, so a
+ * malformed value survives `?? default` and flows on into `setTimeout`, which
+ * clamps a `NaN` delay to 0 and aborts the phase on its first tick, or into
+ * `while (iteration < maxIterations)`, which is false on entry and runs zero
+ * phases. Both read as a phase/agent fault rather than a bad input, which is
+ * what makes the silent version expensive. Non-finite and non-positive values
+ * therefore fall back *to* the default instead of through it.
+ *
+ * `bin/cli.ts` rejects these at the flag boundary with a message naming the
+ * flag — that is the user-facing fix. This is the structural backstop for
+ * programmatic callers, `settings.json`, and whatever calls this next.
+ *
+ * Exported because `phaseTimeout` has two producers, not one: this module and
+ * `commands/ready.ts`, whose value reaches the driver through
+ * `ready-gate.ts`'s own `buildPhaseConfig` and never passes through
+ * `buildExecutionConfig`. Guarding only here would have left that path open.
+ * Chain it to express the layering — CLI, then settings, then the default:
+ *
+ * ```ts
+ * positiveOr(options.timeout, positiveOr(settings.run.timeout, DEFAULT))
+ * ```
+ */
+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.
@@ -97,6 +98,10 @@ export function normalizeCommanderOptions(options) {
         ...(raw.retry === false && { noRetry: true }),
         ...(raw.rebase === false && { noRebase: true }),
         ...(raw.pr === false && { noPr: true }),
+        // #804: map the flag-derived key onto the interface field. Guarded on
+        // `undefined` (not truthiness) so an explicit `--auto-wait 0` still
+        // overrides a non-zero setting.
+        ...(raw.autoWait !== undefined && { autoWaitMinutes: raw.autoWait }),
     };
 }
 /**
@@ -117,6 +122,7 @@ export function resolveRunOptions(cliOptions, settings) {
         qualityLoop: defined.qualityLoop ?? settings.run.qualityLoop,
         maxIterations: defined.maxIterations ?? settings.run.maxIterations,
         noSmartTests: defined.noSmartTests ?? !settings.run.smartTests,
+        autoWaitMinutes: defined.autoWaitMinutes ?? settings.run.autoWaitMinutes,
         // Agent settings
         isolateParallel: defined.isolateParallel ?? settings.agents.isolateParallel,
         // Env overrides
@@ -129,6 +135,116 @@ export function resolveRunOptions(cliOptions, settings) {
     merged.autoDetectPhases = autoDetectPhases;
     return merged;
 }
+/**
+ * Fall back to `fallback` unless `value` is a usable positive number.
+ *
+ * `??` alone is not enough for these (#833). `NaN` is not nullish, so a
+ * malformed value survives `?? default` and flows on into `setTimeout`, which
+ * clamps a `NaN` delay to 0 and aborts the phase on its first tick, or into
+ * `while (iteration < maxIterations)`, which is false on entry and runs zero
+ * phases. Both read as a phase/agent fault rather than a bad input, which is
+ * what makes the silent version expensive. Non-finite and non-positive values
+ * therefore fall back *to* the default instead of through it.
+ *
+ * `bin/cli.ts` rejects these at the flag boundary with a message naming the
+ * flag — that is the user-facing fix. This is the structural backstop for
+ * programmatic callers, `settings.json`, and whatever calls this next.
+ *
+ * Exported because `phaseTimeout` has two producers, not one: this module and
+ * `commands/ready.ts`, whose value reaches the driver through
+ * `ready-gate.ts`'s own `buildPhaseConfig` and never passes through
+ * `buildExecutionConfig`. Guarding only here would have left that path open.
+ * Chain it to express the layering — CLI, then settings, then the default:
+ *
+ * ```ts
+ * positiveOr(options.timeout, positiveOr(settings.run.timeout, DEFAULT))
+ * ```
+ */
+export function positiveOr(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? 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
@@ -157,15 +273,40 @@ export function buildExecutionConfig(mergedOptions, settings, issueCount) {
         parallel: isParallel,
         dryRun: mergedOptions.dryRun ?? false,
         verbose: mergedOptions.verbose ?? false,
-        phaseTimeout: mergedOptions.timeout ?? DEFAULT_CONFIG.phaseTimeout,
+        // #833: chained so the layering is CLI → settings → default, matching
+        // `commands/ready.ts`. A malformed CLI value falls back to the user's
+        // configured setting rather than skipping past it to the hardcoded
+        // default; a malformed setting falls back to the default. In the normal
+        // path `mergedOptions` already carries the settings value, so this only
+        // differs when one of the two layers is unusable — which is the case that
+        // matters.
+        phaseTimeout: positiveOr(mergedOptions.timeout, positiveOr(settings.run.timeout, DEFAULT_CONFIG.phaseTimeout)),
         qualityLoop: mergedOptions.qualityLoop ?? false,
-        maxIterations: mergedOptions.maxIterations ?? DEFAULT_CONFIG.maxIterations,
+        maxIterations: positiveOr(mergedOptions.maxIterations, positiveOr(settings.run.maxIterations, DEFAULT_CONFIG.maxIterations)),
         noSmartTests: mergedOptions.noSmartTests ?? false,
         mcp: mcpEnabled,
         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.
+        autoWaitMinutes: mergedOptions.autoWaitMinutes ??
+            settings.run.autoWaitMinutes ??
+            DEFAULT_CONFIG.autoWaitMinutes,
         agent: mergedOptions.agent ?? settings.run.agent,
         aiderSettings: settings.run.aider,
         isolateParallel: mergedOptions.isolateParallel,
         relayEnabled,
+        // #817: opt-in only, no settings backing (AC-4). A missing `--ready-gate`
+        // resolves to false, keeping the run path byte-identical (AC-5). This is the
+        // 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.
@@ -98,6 +113,13 @@ export interface AgentPhaseResult {
 export interface AgentDriver {
     /** Human-readable name for logging */
     name: string;
+    /**
+     * True when this driver executes phases by resolving slash-command skills
+     * from the project's `.claude/skills/` directory (claude-code). Drivers
+     * whose prompts do the work inline (aider's `driverOverrides` templates)
+     * return false, and the `run` skills pre-flight (#813) is skipped for them.
+     */
+    resolvesSkills: boolean;
     /** Execute a phase prompt and return structured result */
     executePhase(prompt: string, config: AgentExecutionConfig): Promise<AgentPhaseResult>;
     /** Check if this driver is available/configured */

package/dist/src/lib/workflow/drivers/aider.d.ts

@@ -9,6 +9,8 @@ import type { AgentDriver, AgentExecutionConfig, AgentPhaseResult, ResumeHandle
 import type { AiderSettings } from "../../settings.js";
 export declare class AiderDriver implements AgentDriver {
     name: string;
+    /** Aider phases use inline `driverOverrides` prompts — no skills (#813). */
+    resolvesSkills: boolean;
     private settings?;
     constructor(settings?: AiderSettings);
     /**

package/dist/src/lib/workflow/drivers/aider.js

@@ -10,6 +10,8 @@ import { execSync } from "child_process";
 import { RingBuffer } from "../ring-buffer.js";
 export class AiderDriver {
     name = "aider";
+    /** Aider phases use inline `driverOverrides` prompts — no skills (#813). */
+    resolvesSkills = false;
     settings;
     constructor(settings) {
         this.settings = settings;

package/dist/src/lib/workflow/drivers/claude-code.d.ts

@@ -7,6 +7,8 @@
 import type { AgentDriver, AgentExecutionConfig, AgentPhaseResult, ResumeHandle } from "./agent-driver.js";
 export declare class ClaudeCodeDriver implements AgentDriver {
     name: string;
+    /** Phases run slash-command skills from `.claude/skills/` (#813). */
+    resolvesSkills: boolean;
     /**
      * Track session ID across calls so callers can implement resume.
      * Set after each executePhase() call.
@@ -42,6 +44,18 @@ export declare class ClaudeCodeDriver implements AgentDriver {
      * RateLimitError would wrongly re-enable the retry / MCP-fallback path. When
      * the `rate_limit_event` is itself a billing failure its richer metadata
      * (`canUserPurchaseCredits`, etc.) is preserved.
+     *
+     * Counter-exception (#860): when the `rate_limit_event` carries the FULL
+     * captured subscription-window shape — waitable window evidence (recognized
+     * window type + future `resetsAt`) *plus* the `out_of_credits` marker — the
+     * richer structured signal wins over the bare `billing_error` enum. A
+     * subscription plan's five-hour exhaustion surfaces assistant-side as a
+     * billing error, and overriding on that enum here would strip the metadata
+     * `--auto-wait` needs and re-inert the feature this classification exists
+     * to enable. Deliberately no wider than the evidenced shape: a pure
+     * throttle event (window, no billing markers) beside a `billing_error`
+     * enum keeps the #732 rule — billing wins — because there the two signals
+     * genuinely conflict and no capture justifies trusting the throttle.
      */
     private buildStructuredError;
     /**

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

@@ -6,10 +6,12 @@
  */
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { getMcpServersConfig } from "../../system.js";
-import { RateLimitError, BillingError, createRateLimitError, isRateLimitFailureInfo, } from "../../errors.js";
+import { RateLimitError, BillingError, createRateLimitError, isWaitableWindow, isRateLimitFailureInfo, } from "../../errors.js";
 import { RingBuffer } from "../ring-buffer.js";
 export class ClaudeCodeDriver {
     name = "claude-code";
+    /** Phases run slash-command skills from `.claude/skills/` (#813). */
+    resolvesSkills = true;
     /**
      * Track session ID across calls so callers can implement resume.
      * Set after each executePhase() call.
@@ -94,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
@@ -282,11 +289,27 @@ export class ClaudeCodeDriver {
      * RateLimitError would wrongly re-enable the retry / MCP-fallback path. When
      * the `rate_limit_event` is itself a billing failure its richer metadata
      * (`canUserPurchaseCredits`, etc.) is preserved.
+     *
+     * Counter-exception (#860): when the `rate_limit_event` carries the FULL
+     * captured subscription-window shape — waitable window evidence (recognized
+     * window type + future `resetsAt`) *plus* the `out_of_credits` marker — the
+     * richer structured signal wins over the bare `billing_error` enum. A
+     * subscription plan's five-hour exhaustion surfaces assistant-side as a
+     * billing error, and overriding on that enum here would strip the metadata
+     * `--auto-wait` needs and re-inert the feature this classification exists
+     * to enable. Deliberately no wider than the evidenced shape: a pure
+     * throttle event (window, no billing markers) beside a `billing_error`
+     * enum keeps the #732 rule — billing wins — because there the two signals
+     * genuinely conflict and no capture justifies trusting the throttle.
      */
     buildStructuredError(rateLimitInfo, assistantError, apiRetryError) {
         if (rateLimitInfo) {
             const err = createRateLimitError(rateLimitInfo);
-            if (err instanceof RateLimitError && assistantError === "billing_error") {
+            const isCapturedSubscriptionShape = isWaitableWindow(rateLimitInfo) &&
+                rateLimitInfo.overageDisabledReason === "out_of_credits";
+            if (err instanceof RateLimitError &&
+                assistantError === "billing_error" &&
+                !isCapturedSubscriptionShape) {
                 return new BillingError("Billing error");
             }
             return err;