sequant 2.9.0 → 2.11.0

package/dist/src/commands/locks.js

@@ -1,8 +1,9 @@
 /**
- * `sequant locks` — inspect and clear per-issue concurrency locks (#625).
+ * `sequant locks` — inspect and clear per-issue concurrency locks (#625) and
+ * the checkout-scoped lock (#901).
  */
 import chalk from "chalk";
-import { LockManager, formatLockedMessage, } from "../lib/locks/index.js";
+import { CheckoutLock, LockManager, describeCheckoutHolderIssue, formatCheckoutLockedMessage, formatLockedMessage, } from "../lib/locks/index.js";
 /** Human-readable line for the `--signal-other` log output (#637). */
 function formatSignalLine(issue, pid, result) {
     switch (result.reason) {
@@ -14,6 +15,8 @@ function formatSignalLine(issue, pid, result) {
             return `Refused to signal PID ${pid} for #${issue} (matches this process or its parent)`;
         case "pid-dead":
             return `Could not signal PID ${pid} for #${issue} (already exited)`;
+        case "stale-pid-untrusted":
+            return `Refused to signal PID ${pid} for #${issue} (lock is past the age ceiling; that PID has likely been recycled onto an unrelated process)`;
         case "kill-failed":
             return `Could not signal PID ${pid} for #${issue} (kill syscall failed)`;
         case "orchestrator":
@@ -42,14 +45,35 @@ export async function locksListCommand(options = {}) {
         return;
     }
     const listings = manager.list();
+    // The checkout lock lives in the same directory but is deliberately not a
+    // numeric filename, so `manager.list()` skips it (#901). Query it separately
+    // rather than widening the numeric key everywhere.
+    const checkout = new CheckoutLock().listing();
     if (options.json) {
-        console.log(JSON.stringify({ locks: listings }, null, 2));
+        console.log(JSON.stringify({ locks: listings, checkout }, null, 2));
         return;
     }
-    if (listings.length === 0) {
+    if (listings.length === 0 && !checkout) {
         console.log(chalk.gray("No active locks."));
         return;
     }
+    if (checkout) {
+        const ageMinutes = Math.floor(checkout.ageMs / 60_000);
+        const staleTag = checkout.stale
+            ? chalk.yellow(`  (stale: ${checkout.staleReason})`)
+            : "";
+        console.log(chalk.bold("Checkout lock (whole working tree):"));
+        console.log(`  issue=${describeCheckoutHolderIssue(checkout.holder.issue)}  ` +
+            `pid=${checkout.holder.pid}  ` +
+            `host=${checkout.holder.hostname}  age=${ageMinutes}m  ` +
+            `started=${checkout.holder.startedAt}${staleTag}`);
+        console.log(`    command: ${checkout.holder.command}`);
+        console.log("");
+    }
+    if (listings.length === 0) {
+        console.log(chalk.gray("No active per-issue locks."));
+        return;
+    }
     console.log(chalk.bold(`Active locks (${listings.length}):`));
     console.log("");
     for (const l of listings) {
@@ -60,6 +84,186 @@ export async function locksListCommand(options = {}) {
         console.log(`    command: ${l.holder.command}`);
     }
 }
+/**
+ * Validate `--issue` for the checkout commands. Shared by `acquire` (where the
+ * flag is required) and `release` (where it is optional) so the two cannot
+ * drift on what counts as a valid issue.
+ *
+ * `Number.parseInt` + `Number.isInteger`, never a bare `Number(x)`:
+ * `Number(undefined)` is `NaN`, and `NaN !== undefined`, so a `NaN` would sail
+ * through the `issue !== undefined` guard in `isCheckoutOwner` and silently
+ * refuse every release instead of erroring here (#906).
+ */
+function parseCheckoutIssue(raw) {
+    const issue = Number.parseInt(raw, 10);
+    if (!Number.isInteger(issue) || issue <= 0) {
+        console.error(chalk.red(`Invalid issue number: ${raw}`));
+        process.exitCode = 2;
+        return { ok: false };
+    }
+    return { ok: true, issue };
+}
+/**
+ * `sequant locks checkout <acquire|release|check|clear>` — the working-tree
+ * lock (#901).
+ *
+ * Exit codes mirror the per-issue commands:
+ *   0 — success (acquired / released / free / cleared / nothing to release)
+ *   1 — held by another session, or refused
+ *   2 — invalid arguments
+ */
+export async function locksCheckoutCommand(action, options = {}) {
+    const lock = new CheckoutLock();
+    if (lock.isNoop) {
+        // AC-5: orchestrator/MCP mode is a no-op across the whole surface.
+        if (options.json) {
+            console.log(JSON.stringify({ action, orchestratorMode: true, ok: true }));
+        }
+        else {
+            console.log(chalk.gray("Lock operations are disabled (SEQUANT_ORCHESTRATOR set)."));
+        }
+        return;
+    }
+    switch (action) {
+        case "acquire": {
+            if (options.issue === undefined) {
+                console.error(chalk.red("`locks checkout acquire` requires --issue"));
+                process.exitCode = 2;
+                return;
+            }
+            const parsed = parseCheckoutIssue(options.issue);
+            if (!parsed.ok)
+                return;
+            const issue = parsed.issue;
+            const result = lock.acquire(issue, options.command ?? "unknown", {
+                sessionId: options.sessionId,
+                skipPidCheck: options.skipPidCheck,
+            });
+            if (result.acquired) {
+                if (options.json) {
+                    console.log(JSON.stringify({
+                        acquired: true,
+                        reentrant: result.reentrant,
+                        lockPath: result.lockPath,
+                    }));
+                }
+                else {
+                    console.log(chalk.green(result.reentrant
+                        ? `✓ Checkout already held by this session (#${issue})`
+                        : `✓ Acquired checkout lock for #${issue}`));
+                }
+                return;
+            }
+            process.exitCode = 1;
+            if (options.json) {
+                console.log(JSON.stringify({
+                    acquired: false,
+                    holder: result.holder,
+                    lockPath: result.lockPath,
+                }));
+            }
+            else {
+                console.error(chalk.yellow(formatCheckoutLockedMessage(result.holder, { issue })));
+            }
+            return;
+        }
+        case "release": {
+            // `--issue` is optional here, unlike `acquire`: a live process releasing
+            // its own lock is identified by PID. It is required in practice for
+            // skill shells, whose PID is already gone — see `isCheckoutOwner`.
+            let issue;
+            if (options.issue !== undefined) {
+                const parsed = parseCheckoutIssue(options.issue);
+                if (!parsed.ok)
+                    return;
+                issue = parsed.issue;
+            }
+            // Read the holder *before* releasing, so a refusal can name it.
+            const holder = lock.check();
+            const released = lock.release({
+                sessionId: options.sessionId,
+                ...lock.selfIdentity,
+                issue,
+            });
+            // Three outcomes, not two (#906). Before ownership was enforced,
+            // "released nothing" could only mean "nothing was held". It now also
+            // means "held, but not by you" — a real refusal, which must not print
+            // the same gray no-op line or exit 0.
+            if (options.json) {
+                console.log(JSON.stringify({
+                    released,
+                    refused: !released && holder !== null,
+                    ...(holder ? { holder } : {}),
+                }));
+                if (!released && holder)
+                    process.exitCode = 1;
+                return;
+            }
+            if (released) {
+                console.log(chalk.green("✓ Released checkout lock"));
+                return;
+            }
+            if (holder) {
+                process.exitCode = 1;
+                console.error(chalk.yellow(`Refusing to release the checkout lock — it belongs to the session working ${describeCheckoutHolderIssue(holder.issue)} ` +
+                    `(PID ${holder.pid} on ${holder.hostname}, started ${holder.startedAt}).\n` +
+                    (issue === undefined
+                        ? `You passed no --issue, so nothing identified you as the holder.\n` +
+                            `  • If you are that session: sequant locks checkout release --issue=${holder.issue}\n`
+                        : `You passed --issue=${issue}.\n`) +
+                    `  • If that session is gone: sequant locks checkout clear --force`));
+                return;
+            }
+            console.log(chalk.gray("No releasable checkout lock"));
+            return;
+        }
+        case "check": {
+            const holder = lock.check();
+            if (!holder) {
+                if (options.json) {
+                    console.log(JSON.stringify({ locked: false }));
+                }
+                else {
+                    console.log(chalk.gray("Checkout is not locked"));
+                }
+                return;
+            }
+            process.exitCode = 1;
+            if (options.json) {
+                console.log(JSON.stringify({ locked: true, holder }));
+            }
+            else {
+                console.log(chalk.yellow(formatCheckoutLockedMessage(holder)));
+            }
+            return;
+        }
+        case "clear": {
+            const result = lock.clear({ safetyCheck: !options.force });
+            if (options.json) {
+                console.log(JSON.stringify(result));
+                if (!result.cleared)
+                    process.exitCode = 1;
+                return;
+            }
+            if (result.cleared) {
+                console.log(chalk.green("✓ Cleared checkout lock"));
+                return;
+            }
+            process.exitCode = 1;
+            if (result.reason === "no-lock") {
+                console.log(chalk.gray("No checkout lock to clear"));
+                process.exitCode = 0;
+                return;
+            }
+            console.log(chalk.yellow("Refusing to clear a fresh checkout lock. " +
+                "Re-run with `sequant locks checkout clear --force` if you are sure the holder is gone."));
+            return;
+        }
+        default:
+            console.error(chalk.red(`Unknown action: ${action}. Expected acquire|release|check|clear.`));
+            process.exitCode = 2;
+    }
+}
 /**
  * `sequant locks clear <issue>` — remove a lock manually.
  * By default refuses to clear a fresh same-host lock whose PID is alive;

package/dist/src/commands/logs.js

@@ -85,11 +85,17 @@ function displayLogSummary(log, filename, options) {
     // `0 passed, 0 failed` (older logs predate the field → default to 0).
     const partial = log.summary.partial ?? 0;
     const total = log.summary.totalIssues;
-    const status = failed > 0
-        ? chalk.red("FAILED")
-        : passed === total
-            ? chalk.green("PASSED")
-            : chalk.yellow("PARTIAL");
+    // #856: an aborted run is a failure, but saying only "FAILED" sends the
+    // reader hunting for a bug in their own code. The run never got to fail on
+    // its own terms — something killed it.
+    const aborted = log.summary.aborted ?? 0;
+    const status = aborted > 0
+        ? chalk.red("ABORTED")
+        : failed > 0
+            ? chalk.red("FAILED")
+            : passed === total
+                ? chalk.green("PASSED")
+                : chalk.yellow("PARTIAL");
     console.log(chalk.blue(`\n  Run: ${log.runId.slice(0, 8)}...`));
     console.log(chalk.gray(`  File: ${filename}`));
     console.log(chalk.gray(`  Time: ${formatTime(log.startTime)}`));
@@ -98,6 +104,9 @@ function displayLogSummary(log, filename, options) {
         (partial > 0 ? `, ${partial} partial` : "") +
         `)`));
     console.log(chalk.gray(`  Phases: ${log.config.phases.join(" → ")}`));
+    if (log.abortedBy) {
+        console.log(chalk.red(`  Aborted: run terminated by ${log.abortedBy} — results below are incomplete`));
+    }
     // Show issues
     for (const issue of log.issues) {
         const issueStatus = issue.status === "success"

package/dist/src/commands/merge.js

@@ -13,8 +13,12 @@
  */
 import { spawnSync } from "child_process";
 import { ui, colors } from "../lib/cli-ui.js";
-import { runMergeChecks, formatReportMarkdown, } from "../lib/merge-check/index.js";
+import { runMergeChecks, formatReportMarkdown, resolveBranches, findMostRecentLog, resolveLogDir, } from "../lib/merge-check/index.js";
 import { LockManager, formatLockedMessage } from "../lib/locks/index.js";
+import { waitForChecks, resolveWatchTiming } from "../lib/merge-check/watch.js";
+import { GitHubProvider } from "../lib/workflow/platforms/github.js";
+/** Exit code for a watch that timed out — distinct from the 0/1/2 verdicts. */
+const EXIT_WATCH_TIMEOUT = 3;
 /**
  * Determine exit code from batch verdict
  */
@@ -43,6 +47,126 @@ function getRepoRoot() {
     }
     return result.stdout.trim();
 }
+/**
+ * Resolve the PR numbers to watch for a set of issues.
+ *
+ * Reuses `resolveBranches` (git remote + worktree scan) for the issue→branch
+ * map, then prefers the run-log `prNumber` and falls back to
+ * `viewPRByBranchSync`. Issues with no discoverable PR are returned in
+ * `unresolved` so the caller can report them rather than silently skipping.
+ */
+function resolveWatchTargets(issueNumbers, repoRoot, gh) {
+    const runLog = findMostRecentLog(resolveLogDir());
+    const branches = resolveBranches(issueNumbers, repoRoot, runLog);
+    const targets = [];
+    const unresolved = [];
+    for (const b of branches) {
+        const pr = b.prNumber ?? gh.viewPRByBranchSync(b.branch)?.number ?? null;
+        if (pr) {
+            targets.push({ issue: b.issueNumber, pr });
+        }
+        else {
+            unresolved.push(b.issueNumber);
+        }
+    }
+    return { targets, unresolved };
+}
+/**
+ * Watch gate (#818): before the normal merge-check report runs, poll each
+ * resolved PR's CI rollup until every check is terminal.
+ *
+ * Contract: this **never merges**. It only decides *when* the existing report
+ * runs. Returns `true` when it has handled the outcome and the caller must stop
+ * (a dispatch block → BLOCKED/exit 2, a timeout → distinct message/exit 3, or no
+ * PR could be resolved); returns `false` when every PR reached a terminal state
+ * and the caller should fall through to `runMergeChecks` unchanged.
+ *
+ * Multiple PRs share a single wall-clock deadline so `--timeout` bounds the whole
+ * gate, not each PR independently.
+ */
+async function runWatchGate(issueNumbers, options, repoRoot) {
+    const gh = new GitHubProvider();
+    // Auto-detect issues from the most recent run log when none were given,
+    // mirroring runMergeChecks so `--watch` composes with auto-detection.
+    let issues = issueNumbers;
+    if (issues.length === 0) {
+        const runLog = findMostRecentLog(resolveLogDir());
+        if (runLog) {
+            issues = runLog.issues.map((i) => i.issueNumber);
+        }
+    }
+    const { targets, unresolved } = resolveWatchTargets(issues, repoRoot, gh);
+    if (targets.length === 0) {
+        const message = "Watch: no open PR found for " +
+            (issues.length > 0
+                ? `issue(s) ${issues.map((i) => `#${i}`).join(", ")}`
+                : "the most recent run") +
+            ". Push the branch and open a PR before running `merge --watch`.";
+        if (options.json) {
+            console.log(JSON.stringify({ watch: "blocked", error: message }, null, 2));
+        }
+        else {
+            console.error(ui.errorBox("Watch Blocked", message));
+        }
+        process.exitCode = 2;
+        return true;
+    }
+    // Validated, never NaN — the shared deadline below depends on it (a NaN
+    // deadline would make every per-PR `remaining` NaN and defeat --timeout).
+    const { intervalMs, timeoutMs } = resolveWatchTiming(options);
+    const deadline = Date.now() + timeoutMs;
+    if (unresolved.length > 0 && !options.json) {
+        console.log(colors.muted(`  !  No PR resolved for: ${unresolved.map((i) => `#${i}`).join(", ")} — skipping in watch.`));
+    }
+    for (const { issue, pr } of targets) {
+        if (!options.json) {
+            console.log(colors.muted(`Watching PR #${pr} (issue #${issue})…`));
+        }
+        const remaining = deadline - Date.now();
+        const result = await waitForChecks(pr, {
+            intervalMs,
+            // Share the deadline across PRs so the whole gate honors --timeout.
+            timeoutMs: Math.max(0, remaining),
+            onPoll: options.json
+                ? undefined
+                : (msg) => console.log(colors.muted(`  #${pr}: ${msg}`)),
+        }, gh);
+        if (result.status === "blocked") {
+            const reason = result.reason ?? "CI dispatch is blocked.";
+            if (options.json) {
+                console.log(JSON.stringify({
+                    watch: "blocked",
+                    pr,
+                    issue,
+                    reason,
+                    checkName: result.checkName,
+                }, null, 2));
+            }
+            else {
+                console.log(ui.errorBox("BLOCKED", `PR #${pr} (issue #${issue}) — ${reason}` +
+                    (result.checkName ? `\n\nCheck: ${result.checkName}` : "")));
+            }
+            process.exitCode = 2;
+            return true;
+        }
+        if (result.status === "timeout") {
+            const reason = result.reason ?? "Watch timed out.";
+            if (options.json) {
+                console.log(JSON.stringify({ watch: "timeout", pr, issue, reason }, null, 2));
+            }
+            else {
+                console.error(ui.errorBox("Watch Timed Out", reason));
+            }
+            process.exitCode = EXIT_WATCH_TIMEOUT;
+            return true;
+        }
+        // terminal → this PR is ready to be checked; continue to the next PR.
+        if (!options.json) {
+            console.log(colors.muted(`  #${pr}: all checks terminal after ${result.polls} poll(s).`));
+        }
+    }
+    return false;
+}
 /**
  * Main merge command handler
  */
@@ -51,7 +175,14 @@ export async function mergeCommand(issues, options) {
     if (!options.check && !options.scan && !options.review && !options.all) {
         options.check = true;
     }
-    const repoRoot = getRepoRoot();
+    let repoRoot;
+    try {
+        repoRoot = getRepoRoot();
+    }
+    catch {
+        console.error(colors.error("❌ Not in a git repository. Run merge from inside your project repo."));
+        process.exit(1);
+    }
     const issueNumbers = issues
         .map((i) => parseInt(i, 10))
         .filter((n) => !isNaN(n));
@@ -81,6 +212,27 @@ export async function mergeCommand(issues, options) {
         }
         console.log("");
     }
+    // Watch gate (#818): wait for CI to reach a terminal state before running the
+    // report. Returns true when it has already handled the outcome (dispatch
+    // block, timeout, or no PR to watch) and set the exit code — stop here.
+    if (options.watch) {
+        try {
+            const handled = await runWatchGate(issueNumbers, options, repoRoot);
+            if (handled)
+                return;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (options.json) {
+                console.log(JSON.stringify({ watch: "error", error: message }, null, 2));
+            }
+            else {
+                console.error(ui.errorBox("Watch Failed", message));
+            }
+            process.exitCode = 2;
+            return;
+        }
+    }
     try {
         const report = await runMergeChecks(issueNumbers, options, repoRoot);
         if (options.json) {

package/dist/src/commands/ready-tui-adapter.js

@@ -77,7 +77,12 @@ export class ReadySnapshotAdapter {
                     this.status = "failed";
                 break;
             }
-            case "activity": {
+            // #804: an auto-wait surfaces here the same way activity does — as a
+            // refreshed nowLine on the still-running phase. Sharing one body is
+            // deliberate: a wait must NOT reach the complete/failed case, which
+            // would close out a phase that is merely paused.
+            case "activity":
+            case "waiting": {
                 if (this.currentPhase) {
                     this.currentPhase = {
                         ...this.currentPhase,

package/dist/src/commands/ready.d.ts

@@ -14,7 +14,7 @@
  * human / no implementation), persists that state, and emits a structured gap
  * report. See `src/lib/workflow/ready-gate.ts` for the engine.
  */
-import { type ReadyPolicy } from "../lib/settings.js";
+import { type ReadyPolicy, type SequantSettings } from "../lib/settings.js";
 import { type ReadyResult } from "../lib/workflow/ready-gate.js";
 export interface ReadyCommandOptions {
     policy?: string;
@@ -25,12 +25,21 @@ export interface ReadyCommandOptions {
     mcp?: boolean;
     json?: boolean;
     verbose?: boolean;
+    /** Per-phase model override (#914). See `RunOptions.models`. */
+    models?: string;
+    /** Per-phase effort override (#914). See `RunOptions.efforts`. */
+    efforts?: string;
+    /** Evidence-based effort escalation on QA-pass retries (#915). See `RunOptions.escalateEffort`. */
+    escalateEffort?: boolean;
 }
 /**
  * Exit code from a ready result.
  * - 0: ready (awaiting human merge)
- * - 1: not ready — needs human intervention (budget/iterations/stagnation)
- * - 2: not ready — no implementation (#534) or hard error
+ * - 1: not ready — needs human intervention (budget/iterations/stagnation,
+ *      or a NO_VERDICT QA turn (#853): the implementation may exist, so this
+ *      is a re-run case, not the "nothing there" exit)
+ * - 2: not ready — no implementation (#534), uncommitted-only work (#879), or
+ *      hard error. Same class: nothing certifiable exists on the branch.
  */
 export declare function getReadyExitCode(result: ReadyResult): number;
 /**
@@ -40,6 +49,25 @@ export declare function getReadyExitCode(result: ReadyResult): number;
  * @internal Exported for testing only.
  */
 export declare function resolvePolicy(flag: string | undefined, settingsPolicy: ReadyPolicy): ReadyPolicy;
+/**
+ * Resolve the numeric limits for a ready-gate run: CLI → settings → default.
+ *
+ * #833: these previously guarded only the CLI value (`typeof x === "number" &&
+ * x > 0`) and fell straight through to `settings.run.*` unchecked. But
+ * `settings.run.timeout` is user-authored JSON, and `ready`'s value does NOT
+ * pass through `buildExecutionConfig` — `ready-gate.ts`'s `buildPhaseConfig`
+ * assembles its own `ExecutionConfig`. So a `"timeout": 0` in settings.json
+ * reached `setTimeout` as a 0 ms delay and aborted every ready-gate phase on
+ * its first tick, with no warning: the #833 defect, on the path the original
+ * fix did not cover. Chaining `positiveOr` leaves no layer unchecked.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function resolveReadyLimits(options: Pick<ReadyCommandOptions, "maxIterations" | "budget" | "timeout">, settings: Pick<SequantSettings, "run">): {
+    maxIterations: number;
+    tokenBudget: number | undefined;
+    phaseTimeout: number;
+};
 /**
  * Locate the worktree path for an issue from `git worktree list`.
  *

package/dist/src/commands/ready.js

@@ -15,25 +15,33 @@
  * report. See `src/lib/workflow/ready-gate.ts` for the engine.
  */
 import { ui, colors } from "../lib/cli-ui.js";
-import { getSettings } from "../lib/settings.js";
+import { getSettings, } from "../lib/settings.js";
 import { listWorktrees } from "../lib/workflow/worktree-manager.js";
 import { GitHubProvider } from "../lib/workflow/platforms/github.js";
 import { getStateManager } from "../lib/workflow/state-manager.js";
 import { executePhaseWithRetry } from "../lib/workflow/phase-executor.js";
 import { buildProgressWiring } from "./run-progress.js";
 import { ReadySnapshotAdapter } from "./ready-tui-adapter.js";
+import { DEFAULT_CONFIG } from "../lib/workflow/types.js";
+import { positiveOr, resolvePhasePolicies, } from "../lib/workflow/config-resolver.js";
+import { getPhaseNames } from "../lib/workflow/phase-registry.js";
 import { runReadyGate, parseNonGoals, } from "../lib/workflow/ready-gate.js";
 /**
  * Exit code from a ready result.
  * - 0: ready (awaiting human merge)
- * - 1: not ready — needs human intervention (budget/iterations/stagnation)
- * - 2: not ready — no implementation (#534) or hard error
+ * - 1: not ready — needs human intervention (budget/iterations/stagnation,
+ *      or a NO_VERDICT QA turn (#853): the implementation may exist, so this
+ *      is a re-run case, not the "nothing there" exit)
+ * - 2: not ready — no implementation (#534), uncommitted-only work (#879), or
+ *      hard error. Same class: nothing certifiable exists on the branch.
  */
 export function getReadyExitCode(result) {
     if (result.ready)
         return 0;
-    if (result.reason === "NO_IMPLEMENTATION")
+    if (result.reason === "NO_IMPLEMENTATION" ||
+        result.reason === "UNCOMMITTED_ONLY") {
         return 2;
+    }
     return 1;
 }
 /**
@@ -47,6 +55,33 @@ export function resolvePolicy(flag, settingsPolicy) {
         return flag;
     return settingsPolicy;
 }
+/**
+ * Resolve the numeric limits for a ready-gate run: CLI → settings → default.
+ *
+ * #833: these previously guarded only the CLI value (`typeof x === "number" &&
+ * x > 0`) and fell straight through to `settings.run.*` unchecked. But
+ * `settings.run.timeout` is user-authored JSON, and `ready`'s value does NOT
+ * pass through `buildExecutionConfig` — `ready-gate.ts`'s `buildPhaseConfig`
+ * assembles its own `ExecutionConfig`. So a `"timeout": 0` in settings.json
+ * reached `setTimeout` as a 0 ms delay and aborted every ready-gate phase on
+ * its first tick, with no warning: the #833 defect, on the path the original
+ * fix did not cover. Chaining `positiveOr` leaves no layer unchecked.
+ *
+ * @internal Exported for testing only.
+ */
+export function resolveReadyLimits(options, settings) {
+    return {
+        maxIterations: positiveOr(options.maxIterations, positiveOr(settings.run.maxIterations, DEFAULT_CONFIG.maxIterations)),
+        // Budget is genuinely optional — `undefined` means "no budget", not "use a
+        // default" — so it keeps the two-state form rather than chaining.
+        tokenBudget: typeof options.budget === "number" &&
+            Number.isFinite(options.budget) &&
+            options.budget > 0
+            ? options.budget
+            : undefined,
+        phaseTimeout: positiveOr(options.timeout, positiveOr(settings.run.timeout, DEFAULT_CONFIG.phaseTimeout)),
+    };
+}
 /**
  * Locate the worktree path for an issue from `git worktree list`.
  *
@@ -70,16 +105,12 @@ export async function readyCommand(issueArg, options) {
     }
     const settings = await getSettings();
     const policy = resolvePolicy(options.policy, settings.ready.policy);
-    const maxIterations = typeof options.maxIterations === "number" && options.maxIterations > 0
-        ? options.maxIterations
-        : settings.run.maxIterations;
-    const tokenBudget = typeof options.budget === "number" && options.budget > 0
-        ? options.budget
-        : undefined;
-    const phaseTimeout = typeof options.timeout === "number" && options.timeout > 0
-        ? options.timeout
-        : settings.run.timeout;
+    const { maxIterations, tokenBudget, phaseTimeout } = resolveReadyLimits(options, settings);
     const mcp = options.mcp !== false;
+    const phasePolicies = resolvePhasePolicies(options.models, options.efforts, settings.run.phases, getPhaseNames());
+    // #915: CLI > settings > default `false`, same precedence as the `run`
+    // path's `buildExecutionConfig` (config-resolver.ts).
+    const effortEscalation = options.escalateEffort ?? settings.run.effortEscalation ?? false;
     // Resolve the issue's existing worktree (reuses run/state worktree infra).
     const worktreePath = resolveWorktreePath(issueNumber);
     if (!worktreePath) {
@@ -172,6 +203,8 @@ export async function readyCommand(issueArg, options) {
             verbose: options.verbose,
             runPhase,
             onProgress,
+            phasePolicies,
+            effortEscalation,
         });
     }
     catch (error) {
@@ -194,6 +227,13 @@ export async function readyCommand(issueArg, options) {
         process.exitCode = 2;
         return;
     }
+    // #915: surface any escalated qa/loop dispatches — the gate has no live
+    // print of its own (see `withEscalatedEffort` in `ready-gate.ts`).
+    if (options.verbose) {
+        for (const e of result.effortEscalations) {
+            console.log(colors.muted(`  effort: ${e.base} → ${e.escalated} (${e.phase} retry)`));
+        }
+    }
     // Persist the terminal state so `sequant status` reflects it (Derived AC).
     // Best-effort: initialize the issue in state if a prior run didn't track it.
     try {