sequant 2.10.0 → 2.11.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sequant",
   "description": "AI coding agent orchestrator for Claude Code — resolve GitHub issues end-to-end with isolated git worktrees and quality gates, through spec → exec → qa phases.",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "author": {
     "name": "sequant-io",
     "email": "hello@sequant.io"

package/README.md

@@ -296,12 +296,16 @@ Multi-issue runs are parallel by default, and a per-issue lock (`.sequant/locks/
   "run": {
     "qualityLoop": false,
     "maxIterations": 3,
-    "defaultBase": "feature/dashboard"  // Optional: custom default base branch
+    "defaultBase": "feature/dashboard",  // Optional: custom default base branch
+    "phases": {
+      "exec": { "model": "sonnet", "effort": "medium" }  // Optional: per-phase model/effort override
+    },
+    "effortEscalation": false  // Optional: escalate effort one tier on a quality-loop retry
   }
 }
 ```
 
-See [Customization Guide](docs/guides/customization.md) for all options.
+See [Customization Guide](docs/guides/customization.md) for all options, [Per-Phase Model & Effort](docs/reference/run-command.md#per-phase-model--effort) for the `run.phases` shape, the `--models`/`--efforts` flags, and precedence, and [Effort Escalation on Retries](docs/reference/run-command.md#effort-escalation-on-retries) for `run.effortEscalation`/`--escalate-effort`.
 
 ---
 

package/dist/bin/cli.js

@@ -18,7 +18,9 @@ import { readFileSync } from "fs";
 import { initCommand } from "../src/commands/init.js";
 import { buildHomeStrayWarning, getInstallRoot, isHomeStrayInstall, isLocalNodeModulesInstall, } from "../src/lib/version-check.js";
 import { configureUI, banner } from "../src/lib/cli-ui.js";
-import { parseWholeNumber, parsePositiveSeconds, } from "../src/lib/cli-flags.js";
+import { parseWholeNumber, parsePositiveSeconds, parsePhaseSpecFlag, } from "../src/lib/cli-flags.js";
+import { getPhaseNames } from "../src/lib/workflow/phase-registry.js";
+import { EFFORT_LEVELS } from "../src/lib/settings.js";
 import { isCI, isStdoutTTY } from "../src/lib/tty.js";
 import { detectPackageManagerSync, getPackageManagerCommands, } from "../src/lib/stacks.js";
 // Read version from package.json dynamically
@@ -58,7 +60,8 @@ import { syncCommand, areSkillsOutdated, checkAndWarnSkillsOutdated, } from "../
 import { mergeCommand } from "../src/commands/merge.js";
 import { readyCommand, } from "../src/commands/ready.js";
 import { conventionsCommand } from "../src/commands/conventions.js";
-import { locksListCommand, locksClearCommand, locksAcquireCommand, locksReleaseCommand, locksCheckCommand, locksCheckBatchCommand, } from "../src/commands/locks.js";
+import { locksListCommand, locksClearCommand, locksAcquireCommand, locksReleaseCommand, locksCheckCommand, locksCheckBatchCommand, locksCheckoutCommand, } from "../src/commands/locks.js";
+import { worktreeResolveCommand, worktreeVerifyCommand, } from "../src/commands/worktree.js";
 import { promptCommand } from "../src/commands/prompt.js";
 import { watchCommand } from "../src/commands/watch.js";
 import { abortCommand } from "../src/commands/abort.js";
@@ -236,6 +239,14 @@ parseWholeNumber("--auto-wait", {
     // bounds (policy from settings.ready.policy, iteration cap, stagnation guard,
     // Non-Goals) — no new policy surface. Never merges; stops at the human gate.
     .option("--ready-gate", "After phases succeed, run the post-QA ready gate (qa→loop→qa to the configured policy) — never merges, stops at the human merge gate")
+    // #914: per-phase model/effort override for the claude-code driver. Bare
+    // value applies to every phase; comma list of phase=value pairs applies
+    // per phase. CLI > settings.run.phases > absent (resolvePhasePolicies).
+    .option("--models <spec>", "Per-phase model override, e.g. 'sonnet' or 'spec=fable,exec=sonnet' (default: none — inherits the CLI default model)", parsePhaseSpecFlag("--models", getPhaseNames()))
+    .option("--efforts <spec>", "Per-phase reasoning-effort override (low|medium|high|xhigh|max), same grammar as --models (default: none — inherits the SDK default)", parsePhaseSpecFlag("--efforts", getPhaseNames(), EFFORT_LEVELS))
+    // #915: opt-in escalation on quality-loop retries. Raises token cost, so
+    // off by default — matches --ready-gate's opt-in shape above.
+    .option("--escalate-effort", "On a quality-loop retry (loop iteration ≥ 2), run that retried phase one reasoning-effort tier above its resolved base (default: off — see --efforts)")
     .option("-f, --force", "Force re-execution of completed issues (bypass pre-flight state guard) and take over per-issue locks")
     .option("--signal-other", "With --force, SIGTERM the prior PID holding the lock (same-host alive only)")
     .option("--concurrency <n>", "Max concurrent issues in parallel mode (default: 3)", 
@@ -359,6 +370,11 @@ parseWholeNumber("--max-iterations", {
 }))
     .option("--timeout <seconds>", "Timeout per phase in seconds", parsePositiveSeconds("--timeout"))
     .option("--no-mcp", "Disable MCP server injection in headless mode")
+    .option("--models <spec>", "Per-phase model override for the qa/loop phases this gate runs, e.g. 'sonnet' or 'qa=sonnet' (default: none)", parsePhaseSpecFlag("--models", getPhaseNames()))
+    .option("--efforts <spec>", "Per-phase reasoning-effort override (low|medium|high|xhigh|max), same grammar as --models (default: none)", parsePhaseSpecFlag("--efforts", getPhaseNames(), EFFORT_LEVELS))
+    // #915: same opt-in escalation as `sequant run --escalate-effort`, applied
+    // to this gate's qa/loop retry passes.
+    .option("--escalate-effort", "On a QA-pass retry (pass ≥ 2), run that retried phase one reasoning-effort tier above its resolved base (default: off)")
     .option("--json", "Output as JSON")
     .option("-v, --verbose", "Enable verbose output")
     .action((issue, options) => readyCommand(issue, options));
@@ -486,6 +502,35 @@ locksCmd
     .description("Batch read-only probe: emit canonical ⚠ warning lines for held issues (for /assess dashboard)")
     .option("--json", "Output as JSON instead of canonical text lines")
     .action(locksCheckBatchCommand);
+// Checkout-scoped lock (#901). The per-issue locks above give no mutual
+// exclusion on the shared working tree — two sessions on different issues take
+// different lock files, yet `git checkout`/`reset`/`rebase`/`merge` are global
+// to the tree. This lock represents the tree itself.
+locksCmd
+    .command("checkout <action>")
+    .description("Working-tree lock: acquire|release|check|clear (guards branch-mutating git in the main checkout)")
+    .option("--issue <issue>", "Issue this session is working on (acquire, release; proves ownership on release)")
+    .option("--command <command>", "Human-readable command label", "unknown")
+    .option("--session-id <id>", "Claude Code session id; preferred holder identity for skill shells")
+    .option("--skip-pid-check", "Mark the lock so stale recovery skips same-host PID checks (use from skill shells)")
+    .option("-f, --force", "Clear even a fresh holder (clear)")
+    .option("--json", "Output as JSON")
+    .action(locksCheckoutCommand);
+// Repo-scoped worktree resolution for skill bodies (#899)
+const worktreeCmd = program
+    .command("worktree")
+    .description("Resolve and verify this repository's issue worktrees");
+worktreeCmd
+    .command("resolve <issue>")
+    .description("Print the absolute path of this repo's worktree for an issue (exit 1 if none)")
+    .option("--json", "Output as JSON")
+    .action(worktreeResolveCommand);
+worktreeCmd
+    .command("verify <path>")
+    .description("Confirm a path is a worktree of this repo, not a foreign or stale one (exit 1 if not)")
+    .option("--issue <issue>", "Also require the branch to belong to this issue")
+    .option("--json", "Output as JSON")
+    .action(worktreeVerifyCommand);
 // Auto-sync skills after npm upgrade (version mismatch detection)
 // Only triggers when skills were previously synced (has .sequant-version marker).
 // Projects that manage skills manually (no marker) are not affected.

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

@@ -1,5 +1,6 @@
 /**
- * `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).
  */
 export interface LocksListOptions {
     json?: boolean;
@@ -26,6 +27,24 @@ export interface LocksCheckBatchOptions {
 }
 /** `sequant locks list` — print every active lock with staleness metadata. */
 export declare function locksListCommand(options?: LocksListOptions): Promise<void>;
+export interface LocksCheckoutOptions {
+    issue?: string;
+    command?: string;
+    sessionId?: string;
+    skipPidCheck?: boolean;
+    force?: boolean;
+    json?: boolean;
+}
+/**
+ * `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 declare function locksCheckoutCommand(action: string, options?: LocksCheckoutOptions): Promise<void>;
 /**
  * `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/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) {
@@ -44,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) {
@@ -62,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/ready.d.ts

@@ -25,6 +25,12 @@ 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.

package/dist/src/commands/ready.js

@@ -23,7 +23,8 @@ 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 { 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.
@@ -106,6 +107,10 @@ export async function readyCommand(issueArg, options) {
     const policy = resolvePolicy(options.policy, settings.ready.policy);
     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) {
@@ -198,6 +203,8 @@ export async function readyCommand(issueArg, options) {
             verbose: options.verbose,
             runPhase,
             onProgress,
+            phasePolicies,
+            effortEscalation,
         });
     }
     catch (error) {
@@ -220,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 {

package/dist/src/commands/run-display.js

@@ -90,6 +90,7 @@ function toIssueSummary(r) {
         loopTriggered: r.loopTriggered,
         prNumber: r.prNumber,
         prUrl: r.prUrl,
+        prSkippedReason: r.prSkippedReason,
     };
     if (!r.success) {
         // #879: a PR-creation failure has no failed phase — fall back to its error

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

@@ -0,0 +1,31 @@
+/**
+ * `sequant worktree` — repo-scoped worktree resolution for skill bodies (#899).
+ *
+ * `/fullsolve` uses `resolve` to turn an issue number into a real absolute
+ * path before exporting `SEQUANT_WORKTREE`; `/exec` uses `verify` to refuse a
+ * path that does not exist or belongs to another repository. Both fail closed:
+ * a non-zero exit means the caller must halt, not continue where it stands.
+ */
+export interface WorktreeResolveOptions {
+    json?: boolean;
+}
+export interface WorktreeVerifyOptions {
+    issue?: string;
+    json?: boolean;
+}
+/**
+ * `sequant worktree resolve <issue>` — print the absolute path of this
+ * repository's worktree for an issue.
+ *
+ * On success the path is the *only* thing written to stdout, so callers can
+ * capture it with `WT="$(sequant worktree resolve 123)"`. Everything else goes
+ * to stderr.
+ */
+export declare function worktreeResolveCommand(issueArg: string, options?: WorktreeResolveOptions): Promise<void>;
+/**
+ * `sequant worktree verify <path>` — confirm a path is a worktree of this
+ * repository (and, with `--issue`, that it belongs to that issue).
+ *
+ * Exit 1 with a named error is the signal for `/exec` to halt.
+ */
+export declare function worktreeVerifyCommand(pathArg: string, options?: WorktreeVerifyOptions): Promise<void>;

package/dist/src/commands/worktree.js

@@ -0,0 +1,95 @@
+/**
+ * `sequant worktree` — repo-scoped worktree resolution for skill bodies (#899).
+ *
+ * `/fullsolve` uses `resolve` to turn an issue number into a real absolute
+ * path before exporting `SEQUANT_WORKTREE`; `/exec` uses `verify` to refuse a
+ * path that does not exist or belongs to another repository. Both fail closed:
+ * a non-zero exit means the caller must halt, not continue where it stands.
+ */
+import chalk from "chalk";
+import { resolveIssueWorktree, verifyWorktreePath, } from "../lib/workflow/worktree-resolver.js";
+function parseIssue(arg) {
+    const issue = Number.parseInt(arg, 10);
+    if (!Number.isInteger(issue) || issue <= 0) {
+        console.error(chalk.red(`Invalid issue number: ${arg}`));
+        process.exitCode = 2;
+        return null;
+    }
+    return issue;
+}
+/**
+ * `sequant worktree resolve <issue>` — print the absolute path of this
+ * repository's worktree for an issue.
+ *
+ * On success the path is the *only* thing written to stdout, so callers can
+ * capture it with `WT="$(sequant worktree resolve 123)"`. Everything else goes
+ * to stderr.
+ */
+export async function worktreeResolveCommand(issueArg, options = {}) {
+    const issue = parseIssue(issueArg);
+    if (issue === null)
+        return;
+    const result = resolveIssueWorktree(issue);
+    if (!result.ok) {
+        process.exitCode = 1;
+        if (options.json) {
+            console.error(JSON.stringify({
+                issue,
+                ok: false,
+                error: result.error,
+                message: result.message,
+                candidates: result.candidates,
+            }));
+        }
+        else {
+            console.error(chalk.red(result.message));
+        }
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            issue,
+            ok: true,
+            path: result.path,
+            branch: result.branch,
+        }));
+        return;
+    }
+    // Bare path only — this is consumed by `$(...)` in skill bodies.
+    console.log(result.path);
+}
+/**
+ * `sequant worktree verify <path>` — confirm a path is a worktree of this
+ * repository (and, with `--issue`, that it belongs to that issue).
+ *
+ * Exit 1 with a named error is the signal for `/exec` to halt.
+ */
+export async function worktreeVerifyCommand(pathArg, options = {}) {
+    let issue;
+    if (options.issue !== undefined) {
+        const parsed = parseIssue(options.issue);
+        if (parsed === null)
+            return;
+        issue = parsed;
+    }
+    const result = verifyWorktreePath(pathArg, { issue });
+    if (!result.ok) {
+        process.exitCode = 1;
+        if (options.json) {
+            console.error(JSON.stringify({
+                ok: false,
+                error: result.error,
+                message: result.message,
+            }));
+        }
+        else {
+            console.error(chalk.red(result.message));
+        }
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ ok: true, path: result.path, branch: result.branch }));
+        return;
+    }
+    console.log(chalk.green(`✓ ${result.path} (${result.branch})`));
+}

package/dist/src/lib/cli-flags.d.ts

@@ -31,3 +31,26 @@ export declare function parseWholeNumber(flag: string, opts: WholeNumberOptions)
  * `merge --watch` messages this originally shipped with do not change.
  */
 export declare function parsePositiveSeconds(flag: string): (value: string) => number;
+/**
+ * Build a commander coercion for a `--models`/`--efforts`-shaped flag (#914).
+ *
+ * Validates the spec via `config-resolver.ts`'s `parsePhaseSpec` — a bare
+ * value applies to every phase, a comma list of `phase=value` pairs applies
+ * per phase, and a malformed spec (empty segment, mixed bare/pair form, or
+ * an unrecognized phase name) fails fast here rather than reaching
+ * `resolvePhasePolicies` silently. On success, returns the ORIGINAL raw spec
+ * string unchanged (not the parsed map) — `RunOptions.models`/`.efforts`
+ * stay plain strings, and `resolvePhasePolicies` re-parses for real when
+ * building `ExecutionConfig.phasePolicies`, so parsing has exactly one
+ * source of truth even though it runs twice.
+ *
+ * `allowedValues`, when given, additionally rejects any resolved value not
+ * in the set — used for `--efforts` (closed enum: `settings.ts:EFFORT_LEVELS`)
+ * so a typo like `--efforts exec=mediu` fails at the CLI boundary the same
+ * way it already does when set via `settings.json`, instead of only
+ * surfacing once the value reaches the SDK. `--models` passes no
+ * `allowedValues` — model aliases/IDs are intentionally unvalidated (they
+ * churn independently of sequant releases; the SDK errors clearly on a bad
+ * one).
+ */
+export declare function parsePhaseSpecFlag(flag: string, phaseNames: string[], allowedValues?: readonly string[]): (value: string) => string;

package/dist/src/lib/cli-flags.js

@@ -8,6 +8,7 @@
  * @module
  */
 import { InvalidArgumentError } from "commander";
+import { parsePhaseSpec } from "./workflow/config-resolver.js";
 /**
  * Build a commander coercion for a whole-number flag.
  *
@@ -44,3 +45,45 @@ export function parsePositiveSeconds(flag) {
         unitSingular: "second",
     });
 }
+/**
+ * Build a commander coercion for a `--models`/`--efforts`-shaped flag (#914).
+ *
+ * Validates the spec via `config-resolver.ts`'s `parsePhaseSpec` — a bare
+ * value applies to every phase, a comma list of `phase=value` pairs applies
+ * per phase, and a malformed spec (empty segment, mixed bare/pair form, or
+ * an unrecognized phase name) fails fast here rather than reaching
+ * `resolvePhasePolicies` silently. On success, returns the ORIGINAL raw spec
+ * string unchanged (not the parsed map) — `RunOptions.models`/`.efforts`
+ * stay plain strings, and `resolvePhasePolicies` re-parses for real when
+ * building `ExecutionConfig.phasePolicies`, so parsing has exactly one
+ * source of truth even though it runs twice.
+ *
+ * `allowedValues`, when given, additionally rejects any resolved value not
+ * in the set — used for `--efforts` (closed enum: `settings.ts:EFFORT_LEVELS`)
+ * so a typo like `--efforts exec=mediu` fails at the CLI boundary the same
+ * way it already does when set via `settings.json`, instead of only
+ * surfacing once the value reaches the SDK. `--models` passes no
+ * `allowedValues` — model aliases/IDs are intentionally unvalidated (they
+ * churn independently of sequant releases; the SDK errors clearly on a bad
+ * one).
+ */
+export function parsePhaseSpecFlag(flag, phaseNames, allowedValues) {
+    return (value) => {
+        let parsed;
+        try {
+            parsed = parsePhaseSpec(value, phaseNames);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new InvalidArgumentError(`${flag}: ${message}`);
+        }
+        if (allowedValues) {
+            for (const v of Object.values(parsed)) {
+                if (!allowedValues.includes(v)) {
+                    throw new InvalidArgumentError(`${flag}: '${v}' is not one of ${allowedValues.join("|")}.`);
+                }
+            }
+        }
+        return value;
+    };
+}

package/dist/src/lib/cli-ui/run-renderer-types.d.ts

@@ -117,6 +117,8 @@ export interface IssueSummary {
     loopTriggered?: boolean;
     prNumber?: number;
     prUrl?: string;
+    /** Set when PR creation was skipped for lack of commits ahead of base (#920). */
+    prSkippedReason?: string;
     failureReason?: string;
     qaVerdict?: string;
     unmetCount?: number;