sequant 2.8.0 → 2.10.0

package/dist/src/commands/assess-render.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `sequant assess-render <file>` — render an `AssessResult` JSON payload (#823).
+ *
+ * Internal surface. The `/assess` skill builds the JSON, calls this, and pastes
+ * stdout verbatim. Shipping it as a CLI subcommand rather than a `scripts/`
+ * shell-out is what makes the fix reach end users: `skills/spec/SKILL.md:78`
+ * establishes that skills may only run `npx tsx` blocks when the sequant source
+ * tree is present, so a script would work in this repo and nowhere else. A
+ * subcommand ships via `package.json` `bin` + `files: ["dist", ...]` and is
+ * present for every sequant install by definition.
+ *
+ * All output goes to stdout unmodified — no chalk, no boxes, no TTY branching —
+ * because the caller pastes it into a chat transcript and a GitHub comment.
+ */
+/**
+ * Read, validate, and render an `AssessResult` file.
+ *
+ * Exits non-zero with a readable stderr message when the file is missing,
+ * unreadable, not JSON, or fails schema validation — the skill's Step 6 treats a
+ * non-zero exit as its signal to fall back to a hand-drawn dashboard rather than
+ * silently emitting nothing.
+ */
+export declare function assessRenderCommand(file: string): Promise<void>;

package/dist/src/commands/assess-render.js

@@ -0,0 +1,60 @@
+/**
+ * `sequant assess-render <file>` — render an `AssessResult` JSON payload (#823).
+ *
+ * Internal surface. The `/assess` skill builds the JSON, calls this, and pastes
+ * stdout verbatim. Shipping it as a CLI subcommand rather than a `scripts/`
+ * shell-out is what makes the fix reach end users: `skills/spec/SKILL.md:78`
+ * establishes that skills may only run `npx tsx` blocks when the sequant source
+ * tree is present, so a script would work in this repo and nowhere else. A
+ * subcommand ships via `package.json` `bin` + `files: ["dist", ...]` and is
+ * present for every sequant install by definition.
+ *
+ * All output goes to stdout unmodified — no chalk, no boxes, no TTY branching —
+ * because the caller pastes it into a chat transcript and a GitHub comment.
+ */
+import { readFile } from "node:fs/promises";
+import { render } from "../lib/assess/renderer.js";
+import { AssessResultValidationError, parseAssessResult, } from "../lib/assess/types.js";
+/**
+ * Read, validate, and render an `AssessResult` file.
+ *
+ * Exits non-zero with a readable stderr message when the file is missing,
+ * unreadable, not JSON, or fails schema validation — the skill's Step 6 treats a
+ * non-zero exit as its signal to fall back to a hand-drawn dashboard rather than
+ * silently emitting nothing.
+ */
+export async function assessRenderCommand(file) {
+    let raw;
+    try {
+        raw = await readFile(file, "utf-8");
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        console.error(`assess-render: cannot read ${file}\n  ${reason}`);
+        process.exitCode = 1;
+        return;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        console.error(`assess-render: ${file} is not valid JSON\n  ${reason}`);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        console.log(render(parseAssessResult(payload)));
+    }
+    catch (error) {
+        if (error instanceof AssessResultValidationError) {
+            console.error(`assess-render: ${file} — ${error.message}`);
+        }
+        else {
+            const reason = error instanceof Error ? error.message : String(error);
+            console.error(`assess-render: failed to render ${file}\n  ${reason}`);
+        }
+        process.exitCode = 1;
+    }
+}

package/dist/src/commands/doctor.js

@@ -6,10 +6,11 @@ import { execSync } from "child_process";
 import { ui, colors } from "../lib/cli-ui.js";
 import { GitHubProvider } from "../lib/workflow/platforms/github.js";
 import { fileExists, isExecutable } from "../lib/fs.js";
+import { checkSkillsInstalled } from "../lib/skills-check.js";
 import { getManifest } from "../lib/manifest.js";
 import { commandExists, isGhAuthenticated, isNativeWindows, isWSL, checkOptionalMcpServers, getMcpServersConfig, OPTIONAL_MCP_SERVERS, } from "../lib/system.js";
 import { getSettings, DEFAULT_AGENT_SETTINGS } from "../lib/settings.js";
-import { checkVersionThorough, getVersionWarning, } from "../lib/version-check.js";
+import { checkVersionThorough, getVersionWarning, resolveCliInvocation, } from "../lib/version-check.js";
 import { areSkillsOutdated } from "./sync.js";
 import { readAgentsMd, checkAgentsMdConsistency, AGENTS_MD_PATH, } from "../lib/agents-md.js";
 import { readFile } from "../lib/fs.js";
@@ -146,9 +147,11 @@ export async function doctorCommand(options = {}) {
             message: "Missing .sequant-manifest.json - run `sequant init`",
         });
     }
-    // Check 2: Skills directory
-    const skillsExist = await fileExists(".claude/skills");
-    if (skillsExist) {
+    // Checks 2+3: Skills directory + core skills. Shared with the `run`
+    // pre-flight via checkSkillsInstalled (#813) so the layout cannot drift.
+    const coreSkills = ["spec", "exec", "qa"];
+    const { skillsDirExists, missingSkills } = await checkSkillsInstalled(coreSkills);
+    if (skillsDirExists) {
         checks.push({
             name: "Skills",
             status: "pass",
@@ -162,14 +165,6 @@ export async function doctorCommand(options = {}) {
             message: "Missing .claude/skills/ directory",
         });
     }
-    // Check 3: Core skills present
-    const coreSkills = ["spec", "exec", "qa"];
-    const missingSkills = [];
-    for (const skill of coreSkills) {
-        if (!(await fileExists(`.claude/skills/${skill}/SKILL.md`))) {
-            missingSkills.push(skill);
-        }
-    }
     if (missingSkills.length === 0) {
         checks.push({
             name: "Core Skills",
@@ -190,7 +185,7 @@ export async function doctorCommand(options = {}) {
         checks.push({
             name: "Skills Version",
             status: "warn",
-            message: `Outdated (${skillsStatus.currentVersion || "unknown"} → ${skillsStatus.packageVersion}) - run: npx sequant sync`,
+            message: `Outdated (${skillsStatus.currentVersion || "unknown"} → ${skillsStatus.packageVersion}) - run: ${resolveCliInvocation()} sync`,
         });
     }
     else {

package/dist/src/commands/init.js

@@ -8,7 +8,7 @@ import { join, dirname } from "path";
 import { readdir } from "fs/promises";
 import { ui, colors } from "../lib/cli-ui.js";
 import { detectStack, detectAllStacks, getStackConfig, detectPackageManager, getPackageManagerCommands, STACKS, } from "../lib/stacks.js";
-import { copyTemplates } from "../lib/templates.js";
+import { copyTemplates, assertTemplatesDirExists } from "../lib/templates.js";
 import { createManifest } from "../lib/manifest.js";
 import { saveConfig } from "../lib/config.js";
 import { createDefaultSettings, generateSettingsReference, } from "../lib/settings.js";
@@ -73,6 +73,17 @@ function logDefault(label, value) {
     console.log(chalk.blue(`${label}: ${value} (default)`));
 }
 export async function initCommand(options) {
+    // Fail loudly on a missing templates root before any prompt or write, so a
+    // broken install can never half-provision a project. Placed ahead of the
+    // --upgrade-skills branch, which reads the same directory (#822).
+    try {
+        await assertTemplatesDirExists();
+    }
+    catch (error) {
+        console.log(chalk.red(`❌ ${error.message}`));
+        process.exitCode = 1;
+        return;
+    }
     // Handle --upgrade-skills: update skill files from installed package templates
     if (options.upgradeSkills) {
         await upgradeSkills();
@@ -520,6 +531,7 @@ async function upgradeSkills() {
     const installedDir = ".claude/skills";
     if (!(await fileExists(installedDir))) {
         console.log(chalk.red("No skills directory found. Run `sequant init` first."));
+        process.exitCode = 1;
         return;
     }
     // Resolve the package's templates/skills directory

package/dist/src/commands/locks.js

@@ -14,6 +14,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":

package/dist/src/commands/logs.js

@@ -81,18 +81,32 @@ function formatTime(isoString) {
 function displayLogSummary(log, filename, options) {
     const passed = log.summary.passed;
     const failed = log.summary.failed;
+    // #766: `partial` gets its own bucket so an all-partial run isn't rendered as
+    // `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)}`));
     console.log(chalk.gray(`  Duration: ${formatDuration(log.summary.totalDurationSeconds)}`));
-    console.log(chalk.gray(`  Status: ${status} (${passed}/${total} passed, ${failed} failed)`));
+    console.log(chalk.gray(`  Status: ${status} (${passed}/${total} passed, ${failed} failed` +
+        (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;
@@ -29,8 +29,11 @@ export interface ReadyCommandOptions {
 /**
  * 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 +43,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,32 @@
  * 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 } from "../lib/workflow/config-resolver.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 +54,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,15 +104,7 @@ 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;
     // Resolve the issue's existing worktree (reuses run/state worktree infra).
     const worktreePath = resolveWorktreePath(issueNumber);