sequant 2.9.0 → 2.11.0

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "sequant",
       "description": "AI coding agent orchestrator for Claude Code — resolve GitHub issues end-to-end with isolated git worktrees, quality gates, and an MCP server. Includes 17 skills, workflow MCP tools, and pre/post-tool hooks.",
-      "version": "2.9.0",
+      "version": "2.10.0",
       "author": {
         "name": "sequant-io",
         "email": "hello@sequant.io"

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.9.0",
+  "version": "2.11.0",
   "author": {
     "name": "sequant-io",
     "email": "hello@sequant.io"

package/README.md

@@ -16,6 +16,14 @@ AI coding agents write code well, but leave you to run the workflow around it
 
 See the [CHANGELOG](CHANGELOG.md) for release notes, or the [migration guide](CHANGELOG.md#migration-from-v1x) if upgrading from v1.x.
 
+### What's new in 2.10
+
+- **`--auto-wait <minutes>` rides out a rate-limit window** — opt in and a run whose limit window is hours out sleeps until it reopens and continues, instead of halting for a manual restart (#804). **Off by default**; the value is a *total* budget per issue, capped at 2 waits. Never waits on out-of-credits failures (credits are purchased, not waited out). The wait is in-process — for waits that must survive closing the terminal or a reboot, see halt-and-resume below; an exhausted `--auto-wait` budget still writes the halt record so `sequant resume` can pick up where it gave up. See [run-command.md](docs/reference/run-command.md#auto-wait-for-a-rate-limit-window).
+- **Durable halt-and-resume + `sequant resume`** — a run that fails on an exhausted rate-limit window now writes a durable halt record (with its `resumeAt` time) and exits cleanly, releasing the per-issue lock. `sequant resume` re-enters after the window reopens, skipping completed phases and issues — safe to invoke from cron/launchd for unattended machines (recipes in [halt-and-resume.md](docs/reference/halt-and-resume.md)) (#892).
+- **`--ready-gate` runs the post-QA ready gate inside `sequant run`** — opt in and, once an issue's standard phases succeed, `run` drives it through the same full-weight `qa → loop → qa` gate as `sequant ready` (to the configured `ready.policy`) **before** opening the PR, so the gate's fixes land in it. It automates the manual any-gaps/fix-gaps second look and **still stops at the human merge gate — it never merges** (#817). **Off by default**; without the flag the run path is unchanged (an `AC_MET_BUT_NOT_A_PLUS` verdict still breaks to PR per #749). Reuses `ready`'s policy, iteration cap, and stagnation guard — no new settings. See [run-command.md](docs/reference/run-command.md#ready-gate-post-qa-second-look).
+- **`sequant merge --watch` waits for CI, then reports** — instead of polling checks by hand, `merge --watch` waits for each PR's CI checks to finish, then runs the merge-check and reports the result. It never merges (#818).
+- **Stricter CLI contract for scripting** — malformed numeric flags (`--timeout 30m`, `--timeout abc`) are rejected with a clear error instead of silently coerced (#833, #845), and pre-flight rejections (uninitialized project, missing prerequisites) exit non-zero across `run`/`update`/`state`/`status`/`init` (#848). Runs terminated by a signal exit `128+signum` instead of `0` (#856).
+
 ### What's new in 2.9
 
 - **`--chain` survives a failed link** — re-running a partially-completed chain resumes from its last good link, skipping the completed prefix and rebasing onto that committed tip instead of redoing hours of finished work (#760). A warn-by-default content pre-flight also runs before the first worktree is provisioned, flagging missing ACs, mis-ordered dependencies, predicted file overlaps, and closed issues; `--strict-preflight` makes any warning a hard stop (#762).
@@ -25,7 +33,7 @@ See the [CHANGELOG](CHANGELOG.md) for release notes, or the [migration guide](CH
 ### What's new in 2.8
 
 - **Clearer failures when an agent stops early** — phases that hit a turn cap now preserve their partial work and halt cleanly for resume instead of discarding it (#739, #733), and rate-limit/out-of-credits failures are named for what they are (with reset time and credit-purchase hints) rather than buried under generic retry noise (#732).
-- **Runtime Node-version guard** — `sequant` checks the running Node against its `engines.node` floor (`>=22.12.0`) at startup and exits with a friendly upgrade message instead of crashing later on a Node-22-only API (#734).
+- **Runtime Node-version guard** — `sequant` checks the running Node against its `engines.node` floor (`>=22.13.0`) at startup and exits with a friendly upgrade message instead of crashing later on a Node-22-only API (#734).
 - **`/assess` avoids npx version skew** — it now emits `sequant run …` when a global install is on `PATH` (and the unchanged `npx sequant run …` otherwise), so copy-pasted commands don't silently run a stale binary (#740).
 
 ### What's new in 2.7
@@ -55,7 +63,7 @@ See the [CHANGELOG](CHANGELOG.md) for release notes, or the [migration guide](CH
 - [GitHub CLI](https://cli.github.com/) — run `gh auth login`
 - Git — for worktree-based isolation
 
-**For the npm/CLI install path:** Node.js 22.12+
+**For the npm/CLI install path:** Node.js 22.13+
 
 **Optional MCP (Model Context Protocol) servers — enhanced features:**
 - `chrome-devtools` — enables `/test` for browser-based UI testing
@@ -83,6 +91,8 @@ npx sequant init             # install skills into your project
 npx sequant doctor           # verify setup
 ```
 
+> **Commit `.claude/skills/`.** It is a runtime dependency, not a cache: `sequant run` phase agents load skills from that directory only, so a checkout (or cleanup) that drops it breaks every run. `sequant run` pre-flights the directory and fails fast with the fix (`sequant sync`) if it is missing.
+
 ### Your first run
 
 Inside Claude Code, solve an issue end-to-end:
@@ -236,7 +246,7 @@ Most work goes through a handful of top-level commands. The rest are either pipe
 | `/assess <issues…>` | Triage one or more issues; emits a dashboard + ready-to-paste `run` commands (6-action vocabulary). |
 | `npx sequant run <issues…>` | Headless equivalent of `/fullsolve`; batches run in parallel. Add `-Q` for the quality loop. |
 | `/qa <issue>` | Code review + quality gate; posts findings as issue comments. |
-| `npx sequant merge <issues…>` | Batch integration QA before merging. |
+| `npx sequant merge <issues…>` | Batch integration QA before merging. Add `--watch` to wait for each PR's CI checks to finish (configurable `--interval`/`--timeout`), then run the checks and report — it never merges. |
 
 ### Pipeline internals
 
@@ -247,6 +257,7 @@ Most work goes through a handful of top-level commands. The rest are either pipe
 | Command | What it does |
 |---------|--------------|
 | `sequant ready <issue>` | Post-resolve full-weight A+ QA gate; drives to merge-readiness, then stops at the human merge gate (never merges). |
+| `sequant resume` | Re-enter runs halted on a rate-limit window once it reopens; no-op before `resumeAt`, so it is safe to schedule via cron/launchd. See [halt-and-resume.md](docs/reference/halt-and-resume.md). |
 | `/merger` | Multi-issue merge coordination. |
 | `/improve` | Codebase analysis and improvement discovery. |
 | `/security-review` | Deep security analysis. |
@@ -285,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,6 +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, 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
@@ -48,6 +51,7 @@ import { updateCommand } from "../src/commands/update.js";
 import { doctorCommand } from "../src/commands/doctor.js";
 import { statusCommand } from "../src/commands/status.js";
 import { runCommand } from "../src/commands/run.js";
+import { resumeCommand } from "../src/commands/resume.js";
 import { logsCommand } from "../src/commands/logs.js";
 import { statsCommand } from "../src/commands/stats.js";
 import { dashboardCommand } from "../src/commands/dashboard.js";
@@ -56,10 +60,12 @@ 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";
+import { assessRenderCommand } from "../src/commands/assess-render.js";
 import { getManifest } from "../src/lib/manifest.js";
 import { phaseRegistry } from "../src/lib/workflow/phase-registry.js";
 /**
@@ -142,7 +148,7 @@ program
 program
     .command("sync")
     .description("Sync skills and templates from the Sequant package (non-interactive)")
-    .option("-f, --force", "Sync even if versions match")
+    .option("-f, --force", "Sync even if versions match; also overwrites in-place customizations (e.g. the constitution)")
     .option("-q, --quiet", "Suppress output")
     .option("-d, --dry-run", "Show what sync would write without making changes (exits non-zero if work is pending)")
     .action(syncCommand);
@@ -155,13 +161,13 @@ program
 program
     .command("status")
     .description("Show Sequant version, configuration, and workflow state")
-    .argument("[issue]", "Issue number to show details for", parseInt)
+    .argument("[issue]", "Issue number to show details for", parseWholeNumber("issue", { min: 1 }))
     .option("--issues", "Show all tracked issues")
     .option("--json", "Output as JSON")
     .option("--rebuild", "Rebuild state from run logs")
     .option("--cleanup", "Clean up stale/orphaned entries")
     .option("--dry-run", "Preview cleanup without changes")
-    .option("--max-age <days>", "Remove entries older than N days", parseInt)
+    .option("--max-age <days>", "Remove entries older than N days", parseWholeNumber("--max-age", { min: 1, unit: "days" }))
     .option("--all", "Show all entries including expired; with --cleanup removes all orphaned")
     .option("--offline", "Skip GitHub queries (pure local state)")
     .action((issue, options) => {
@@ -179,7 +185,9 @@ program
     .option("--sequential", "Stop on first issue failure (default: continue)")
     .option("-d, --dry-run", "Preview without execution")
     .option("-v, --verbose", "Verbose output with streaming")
-    .option("--timeout <seconds>", "Timeout per phase in seconds", parseInt)
+    // #833: `parseInt` here let `--timeout abc` reach `setTimeout` as `NaN`,
+    // which clamps to 0 and aborts every phase the moment it starts.
+    .option("--timeout <seconds>", "Timeout per phase in seconds", parsePositiveSeconds("--timeout"))
     .option("--log-json", "Enable structured JSON logging (default: true)")
     .option("--no-log", "Disable JSON logging for this run")
     .option("--log-path <path>", "Custom log directory path")
@@ -189,7 +197,13 @@ program
     // `runCommand` ORs `qualityLoopAlias` into `qualityLoop`. `-q` no longer maps
     // to --quiet, which moved to `-s` to end the `-q`/`-Q` collision.
     .addOption(new Option("-q, --quality-loop-alias", "Alias for -Q/--quality-loop").hideHelp())
-    .option("--max-iterations <n>", "Max iterations for quality loop (default: 3)", parseInt)
+    // #833: a `NaN` bound makes `while (iteration < maxIterations)` in
+    // `batch-executor.ts` false on entry, so the issue silently runs zero phases.
+    .option("--max-iterations <n>", "Max iterations for quality loop (default: 3)", parseWholeNumber("--max-iterations", {
+    min: 1,
+    unit: "iterations",
+    unitSingular: "iteration",
+}))
     .option("--batch <issues>", 'Group of issues to run together (e.g., --batch "1 2" --batch "3")', (value, prev) => prev.concat([value]), [])
     .option("--smart-tests", "Enable smart test detection (default)")
     .option("--no-smart-tests", "Disable smart test detection")
@@ -198,17 +212,48 @@ program
     .option("-s, --quiet", "Suppress version warnings and non-essential output (heartbeat-only)")
     .option("--chain", "Chain issues: each successor is rebased onto the previous issue's committed work before it runs (implies --sequential)")
     .option("--stacked", "Stack PRs: middle PRs target predecessor branch instead of main; first/last target main (implies --chain)")
-    .option("--qa-gate", "Wait for QA pass before starting next issue in chain (requires --chain)")
+    // #795: deliberately a visible `.option()`, NOT `.hideHelp()` like
+    // `--experimental-tui` below. The two are different cases: `--qa-gate`
+    // shipped in #133 and was documented across four user-facing docs, so users
+    // need to find the deprecation notice; `--experimental-tui` was never
+    // advertised. A flag that still works but is absent from --help is the worst
+    // of both worlds — scripts keep passing it and nothing explains why to stop.
+    .option("--qa-gate", "DEPRECATED (#795): no-op, still accepted. --chain already halts on any failed issue, QA included")
     .option("--strict-preflight", "Make --chain content pre-flight warnings (missing AC, dependency/overlap order, closed issues) fatal before any worktree is provisioned")
     .option("--base <branch>", "Base branch for worktree creation (default: main or settings.run.defaultBase)")
     .option("--no-mcp", "Disable MCP server injection in headless mode")
     .option("--no-retry", "Disable automatic retry with MCP fallback (useful for debugging)")
+    .option("--auto-wait <minutes>", "Total minutes to wait for an exhausted rate-limit window to reopen instead of halting (default: 0, off)", 
+// #833: min 0 — #804 defines 0 as "off", so 0 is a meaningful value here
+// and must keep parsing. `NaN` was silently coerced to 0 by
+// `createAutoWaitLedger`, so `--auto-wait 30m` quietly bought 30 minutes.
+parseWholeNumber("--auto-wait", {
+    min: 0,
+    unit: "minutes",
+    unitSingular: "minute",
+}))
     .option("--resume", "Resume from last completed phase (reads phase markers from GitHub)")
     .option("--no-rebase", "Skip pre-PR rebase onto origin/main (use when you want to handle rebasing manually)")
     .option("--no-pr", "Skip PR creation after successful QA (manual PR workflow)")
+    // #817: opt-in post-QA ready gate. Reuses the `sequant ready` engine and its
+    // 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)", parseInt)
+    .option("--concurrency <n>", "Max concurrent issues in parallel mode (default: 3)", 
+// #833: `run.ts` already rejects non-integers, but only after `parseInt`
+// has silently turned `--concurrency 3x` into 3. Validating the raw string
+// catches that; the downstream check stays as a programmatic backstop.
+parseWholeNumber("--concurrency", { min: 1 }))
     .option("--isolate-parallel", "Isolate parallel agent groups in separate worktrees (prevents file conflicts)")
     .option("--reflect", "Analyze run results and suggest improvements")
     .option("--agent <name>", 'Agent driver for phase execution (default: "claude-code")')
@@ -220,12 +265,26 @@ program
     .addOption(new Option("--experimental-tui").hideHelp())
     .option("--no-relay", "Disable interactive relay (#383); `sequant prompt` cannot reach this run")
     .action(runCommand);
+// Durable halt-and-resume re-entry (#892). Safe to invoke from cron/launchd:
+// a no-op (exit 0) until a halted issue's `resumeAt` passes.
+program
+    .command("resume")
+    .description("Re-enter runs halted on a rate-limit window (no-op until resumeAt; see docs/reference/halt-and-resume.md)")
+    .argument("[issues...]", "Issue numbers to resume (default: all halted)")
+    .option("-d, --dry-run", "Show what would be resumed without running")
+    // Arrow wrapper: commander passes the Command instance as a third
+    // positional, which must not land in resumeCommand's injectable deps param.
+    .action((issues, options) => resumeCommand(issues, options));
 program
     .command("prompt")
     .description("Send a message into a running headless sequant session (#383)")
     .argument("[args...]", '[<issue>] "<message>"')
     .option("--type <type>", "Message type: query (default), directive, abort", "query")
-    .option("--wait <seconds>", "Block until a reply arrives or the timeout elapses (#645, Gap 4)", parseInt)
+    .option("--wait <seconds>", "Block until a reply arrives or the timeout elapses (#645, Gap 4)", parseWholeNumber("--wait", {
+    min: 0,
+    unit: "seconds",
+    unitSingular: "second",
+}))
     .option("--json", "Output as JSON")
     .action((args, options) => {
     return promptCommand({
@@ -253,7 +312,15 @@ program
     .description("Out-of-band abort: signal a running sequant session directly (#645)")
     .argument("[issue]", "Issue number (auto-resolved when a single run is active)")
     .option("--force", "Skip the SIGINT grace period; SIGTERM immediately")
-    .option("--grace <seconds>", "Seconds to wait after SIGINT before escalating (default: 10)", parseInt)
+    .option("--grace <seconds>", "Seconds to wait after SIGINT before escalating (default: 10)", 
+// #833: min 0 — `--grace 0` means "escalate immediately" and is meaningful.
+// `NaN` was worse than useless: `Math.max(0, NaN * 1000)` is `NaN`, so the
+// grace period was skipped entirely and SIGTERM followed at once.
+parseWholeNumber("--grace", {
+    min: 0,
+    unit: "seconds",
+    unitSingular: "second",
+}))
     .option("--json", "Output as JSON")
     .action((issueArg, options) => {
     const args = issueArg === undefined ? [] : [issueArg];
@@ -275,6 +342,9 @@ program
     .option("--review", "Run Phase 1 + 2 + 3 AI briefing")
     .option("--all", "Run all phases")
     .option("--post", "Post report to GitHub as PR comments")
+    .option("--watch", "Poll each PR's CI checks until terminal, then run merge-check (never merges)")
+    .option("--interval <seconds>", "Watch poll interval in seconds (default 30)", parsePositiveSeconds("--interval"))
+    .option("--timeout <seconds>", "Watch give-up timeout in seconds (default 1800)", parsePositiveSeconds("--timeout"))
     .option("--json", "Output as JSON")
     .option("-v, --verbose", "Enable verbose output")
     .action(mergeCommand);
@@ -283,13 +353,39 @@ program
     .description("Post-resolve A+ QA gate — drive an issue to merge-readiness, then stop at the human merge gate (never merges)")
     .argument("<issue>", "Issue number to drive to readiness")
     .option("--policy <policy>", "Gate policy: 'ac' (default, stop at ACs met) or 'a-plus' (loop to READY_FOR_MERGE)")
-    .option("--max-iterations <n>", "Max QA passes before halting for human review (default: settings.run.maxIterations)", parseInt)
-    .option("--budget <tokens>", "Token budget; halt cleanly with a 'needs human' message on exhaustion", parseInt)
-    .option("--timeout <seconds>", "Timeout per phase in seconds", parseInt)
+    .option("--max-iterations <n>", "Max QA passes before halting for human review (default: settings.run.maxIterations)", 
+// #833: `ready.ts` guards each of these three with `> 0`, so `NaN` already
+// fell back to the default rather than reaching a timer. What it could not
+// catch is the silent misparse — `--budget 10k` became 10, `--timeout 30m`
+// became 30 seconds — and a fallback is not the same as telling the user.
+parseWholeNumber("--max-iterations", {
+    min: 1,
+    unit: "iterations",
+    unitSingular: "iteration",
+}))
+    .option("--budget <tokens>", "Token budget; halt cleanly with a 'needs human' message on exhaustion", parseWholeNumber("--budget", {
+    min: 1,
+    unit: "tokens",
+    unitSingular: "token",
+}))
+    .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));
+// #823: internal surface for the /assess skill, deliberately hidden from the
+// top-level help — it takes a JSON payload no human hand-writes. `sequant
+// assess-render --help` still works for debugging.
+program
+    .command("assess-render", { hidden: true })
+    .description("(internal) Render an /assess AssessResult JSON payload to stdout")
+    .argument("<file>", "Path to an AssessResult JSON file")
+    .action(assessRenderCommand);
 program
     .command("conventions")
     .description("View and manage codebase conventions")
@@ -301,9 +397,9 @@ program
     .command("logs")
     .description("View and analyze workflow run logs")
     .option("-p, --path <path>", "Custom log directory path")
-    .option("-n, --last <n>", "Show last N runs", parseInt)
+    .option("-n, --last <n>", "Show last N runs", parseWholeNumber("--last", { min: 1 }))
     .option("--json", "Output as JSON")
-    .option("-i, --issue <number>", "Filter by issue number", parseInt)
+    .option("-i, --issue <number>", "Filter by issue number", parseWholeNumber("--issue", { min: 1 }))
     .option("--failed", "Show only failed runs")
     .option("--rotate", "Rotate logs (delete oldest to meet thresholds)")
     .option("-d, --dry-run", "Show what would be rotated without deleting")
@@ -322,7 +418,7 @@ program
 program
     .command("dashboard")
     .description("Start visual workflow dashboard in browser")
-    .option("-p, --port <port>", "Port to run server on", parseInt)
+    .option("-p, --port <port>", "Port to run server on", parseWholeNumber("--port", { min: 1 }))
     .option("--no-open", "Don't automatically open browser")
     .option("-v, --verbose", "Enable verbose logging")
     .action(dashboardCommand);
@@ -330,7 +426,7 @@ program
     .command("serve")
     .description("Start MCP server for workflow orchestration")
     .option("--transport <type>", "Transport type: stdio (default) or sse", "stdio")
-    .option("--port <port>", "Port for SSE transport (default: 3100)", parseInt)
+    .option("--port <port>", "Port for SSE transport (default: 3100)", parseWholeNumber("--port", { min: 1 }))
     .action(async (options) => {
     const mod = await import("../src/commands/serve.js").catch(() => null);
     if (!mod) {
@@ -364,7 +460,7 @@ stateCmd
     .option("--json", "Output as JSON")
     .option("-v, --verbose", "Enable verbose output")
     .option("-d, --dry-run", "Preview cleanup without changes")
-    .option("--max-age <days>", "Remove entries older than N days", parseInt)
+    .option("--max-age <days>", "Remove entries older than N days", parseWholeNumber("--max-age", { min: 1, unit: "days" }))
     .option("--all", "Remove all orphaned entries (merged and abandoned)")
     .action(stateCleanCommand);
 // Per-issue concurrency locks (#625)
@@ -406,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/marketplace/external_plugins/sequant/.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.9.0",
+  "version": "2.10.0",
   "author": {
     "name": "sequant-io",
     "email": "hello@sequant.io"

package/dist/marketplace/external_plugins/sequant/.mcp.json

@@ -1,6 +1,6 @@
 {
   "sequant": {
     "command": "npx",
-    "args": ["-y", "sequant@latest", "serve"]
+    "args": ["-y", "sequant@2.10.0", "serve"]
   }
 }

package/dist/marketplace/external_plugins/sequant/README.md

@@ -6,7 +6,7 @@ AI coding agent orchestrator for Claude Code — resolve GitHub issues end-to-en
 
 - **Git** with a GitHub remote
 - **GitHub CLI** (`gh`) authenticated (`gh auth status`)
-- **Node.js 22.12+** (for MCP server via `npx`)
+- **Node.js 22.13+** (for MCP server via `npx`)
 
 ## Installation
 
@@ -31,7 +31,7 @@ sequant init
 
 ## What You Get
 
-### 17 Workflow Skills
+### 19 Workflow Skills
 
 | Skill | Purpose |
 |-------|---------|
@@ -51,6 +51,8 @@ sequant init
 | `/security-review` | Deep security analysis |
 | `/solve` | Generate the recommended workflow for one or more issues |
 | `/merger` | Multi-issue integration and merge |
+| `/release` | Version bump, git tag, GitHub release, npm publish |
+| `/upstream` | Monitor Claude Code releases for breaking changes |
 | `/setup` | Project initialization for plugin users |
 
 ### MCP Tools (automatic with plugin)
@@ -83,6 +85,58 @@ sequant ready        # Boxed pre-flight: which issues are ready to run?
 
 See the [`sequant ready` command reference](https://github.com/sequant-io/sequant/blob/main/docs/reference/ready-command.md) for the full pre-flight readiness check.
 
+## Riding out a rate-limit window
+
+By default, a rate limit whose window reopens hours from now halts the run, so a multi-hour job needs a manual restart. `--auto-wait <minutes>` opts into waiting instead:
+
+```bash
+sequant run 42 --auto-wait 360   # wait up to 6 hours total for the window to reopen
+```
+
+- **Off by default** (`0`) — the halt behavior is unchanged unless you ask for the wait.
+- The value is a **total** budget per issue, not per occurrence, capped at 2 waits.
+- **Never waits on out-of-credits failures** — credits are purchased, not waited out. (These do carry a reset timestamp, so the gate is the error type, not the timestamp.)
+- The wait is shown live and Ctrl-C ends it promptly.
+- **In-process only: it does not survive closing the terminal** — for waits that must survive a closed terminal or reboot, use halt-and-resume below.
+- Worktree and issue locks are held throughout — deliberate, since Claude rate limits are account-wide and no other run could progress during the window anyway.
+
+Also settable as `run.autoWaitMinutes` or `SEQUANT_AUTO_WAIT_MINUTES`. Full details in the [run command reference](https://github.com/sequant-io/sequant/blob/main/docs/reference/run-command.md#auto-wait-for-a-rate-limit-window).
+
+### Durable recovery: `sequant resume`
+
+Without `--auto-wait` (or once its budget is exhausted), a run that fails on a waitable rate-limit window writes a durable halt record with its reset time and exits cleanly, releasing the per-issue lock. `sequant resume` re-enters after the window reopens, skipping completed phases and issues — safe to invoke repeatedly, so a single cron/launchd entry handles unattended machines. Recipes and full mechanics in the [halt-and-resume reference](https://github.com/sequant-io/sequant/blob/main/docs/reference/halt-and-resume.md).
+
+## Wait for CI, then verify (`merge --watch`)
+
+`sequant merge <issue> --watch` kills the "merge after green" polling loop: it waits for the PR's CI checks to finish before running merge-check, so the verdict is real the moment the command exits.
+
+```bash
+sequant merge 818 --watch                 # poll CI to terminal, then run merge-check
+sequant merge 818 --watch --scan --post   # composes with depth flags and --post
+```
+
+- **It never merges** — `--watch` only decides _when_ the existing report runs; the human merge gate stays.
+- **Foreground only** — a plain poll loop, no daemon or OS notifications. Chain on the exit code to notify yourself.
+- **Configurable** `--interval <seconds>` (default 30) and `--timeout <seconds>` (default 1800); a timeout exits with a distinct code (3).
+- **Dispatch blocks short-circuit to BLOCKED** with the cause — merge conflicts (`CONFLICTING`), zero checks after a dispatch block, and a runner-never-started billing lockout — instead of polling until timeout.
+
+Full details in the [merge command reference](https://github.com/sequant-io/sequant/blob/main/docs/reference/merge-command.md).
+
+## Running the ready gate inside `run`
+
+`--ready-gate` opts a `sequant run` into the same post-QA gate as `sequant ready`, without the second manual command — it automates the habitual any-gaps → fix-gaps second look:
+
+```bash
+sequant run 42 --ready-gate   # phases, then the gate, then a PR — never merges
+```
+
+- **Off by default** — without the flag the run path is unchanged.
+- Once the standard phases pass, the gate runs a full-weight `qa → loop → qa` pass (to `ready.policy`) **before** the PR opens, so its fixes land in the PR.
+- **It never merges.** The run stops at the human merge gate with the issue `waiting_for_human_merge` (threshold reached) or `blocked` (a guard halted it).
+- Reuses `ready`'s policy, iteration cap, and stagnation guard — **no new settings**.
+
+Full details in the [run command reference](https://github.com/sequant-io/sequant/blob/main/docs/reference/run-command.md#ready-gate-post-qa-second-look).
+
 ## Documentation
 
 - [Getting Started](https://github.com/sequant-io/sequant/tree/main/docs/getting-started)

package/dist/marketplace/external_plugins/sequant/hooks/parallel-marker.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# Shared naming contract for /exec parallel-group marker files (#881).
+#
+# One writer (the /exec skill) and two readers (pre-tool.sh, post-tool.sh) must
+# agree on (a) the marker filename and (b) how the owning project is identified.
+# Before #881 the filename was a global constant, so a parallel group in ONE
+# project silently redirected worktree enforcement for EVERY concurrent Claude
+# session on the machine — the first matching marker in the shared temp dir won,
+# regardless of which project wrote it. Keeping the scheme in this single sourced
+# file is what stops the writer and the readers from drifting apart (AC-4).
+#
+# Marker filename: ${TMPDIR}/claude-parallel-<project-hash>-<group-id>.marker
+# Marker contents: line 1 = worktree path, line 2 = owning project root.
+
+# parallel_marker_project_root — the canonical identity of the current project,
+# derived identically in skill-context and hook-context. CLAUDE_PROJECT_DIR is
+# set by Claude Code for both the skill's shell and the hook's shell within the
+# same session; the git-toplevel fallback resolves to the same worktree when it
+# is unset. A mismatch here would silently re-introduce the cross-project
+# collision this fix exists to close, so the two contexts MUST agree.
+parallel_marker_project_root() {
+    if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
+        printf '%s' "$CLAUDE_PROJECT_DIR"
+    else
+        git rev-parse --show-toplevel 2>/dev/null || printf '%s' "$PWD"
+    fi
+}
+
+# parallel_marker_hash — a stable per-project hash used in the marker filename so
+# two projects running parallel groups at once cannot collide (AC-1). Reuses the
+# md5-with-md5sum-fallback idiom already used for the per-file lock in
+# pre-tool.sh. printf (no trailing newline) keeps writer and reader identical.
+parallel_marker_hash() {
+    local root
+    root="$(parallel_marker_project_root)"
+    printf '%s' "$root" | md5 -q 2>/dev/null || printf '%s' "$root" | md5sum | cut -d' ' -f1
+}
+
+# parallel_marker_prefix — the ${TMPDIR}-anchored, project-scoped filename prefix
+# that both the writer and the readers glob on (AC-2). Honors $TMPDIR (macOS's
+# per-user temp) with a /tmp fallback, matching the hooks' own _TMPDIR.
+parallel_marker_prefix() {
+    local tmp="${TMPDIR:-/tmp}"
+    printf '%s/claude-parallel-%s-' "$tmp" "$(parallel_marker_hash)"
+}
+
+# parallel_marker_path <group-id> — the full marker path for one group.
+parallel_marker_path() {
+    printf '%s%s.marker' "$(parallel_marker_prefix)" "$1"
+}

package/dist/marketplace/external_plugins/sequant/hooks/post-tool.sh

@@ -77,22 +77,35 @@ mkdir -p "$_LOG_DIR" 2>/dev/null || _LOG_DIR="${_TMPDIR}"
 TIMING_LOG="${_LOG_DIR}/claude-timing.log"
 QUALITY_LOG="${_LOG_DIR}/claude-quality.log"
 TESTS_LOG="${_LOG_DIR}/claude-tests.log"
-PARALLEL_MARKER_PREFIX="${_TMPDIR}/claude-parallel-"
+
+# Parallel-group marker naming (#881). Source the shared helper next to this
+# hook so the project-scoped prefix stays identical to the writer and pre-tool.sh.
+_MARKER_HELPER="$(dirname "${BASH_SOURCE[0]:-$0}")/parallel-marker.sh"
+if [[ -f "$_MARKER_HELPER" ]]; then
+    # shellcheck source=parallel-marker.sh disable=SC1091
+    source "$_MARKER_HELPER"
+    PARALLEL_MARKER_PREFIX="$(parallel_marker_prefix)"
+else
+    PARALLEL_MARKER_PREFIX="${_TMPDIR}/claude-parallel-"
+fi
 
 # === AGENT ID DETECTION ===
-# For parallel agents, detect group ID from marker files
-# Format: ${_TMPDIR}/claude-parallel-<group-id>.marker
+# For parallel agents, detect group ID from marker files. The glob is scoped to
+# the current project's marker prefix (#881) so a foreign project's marker never
+# labels this session's timing rows.
 AGENT_ID=""
 IS_PARALLEL_AGENT="false"
+_MARKER_BASE=$(basename "$PARALLEL_MARKER_PREFIX")
 # Find marker files using find (works in both bash and zsh)
 while IFS= read -r marker; do
     if [[ -n "$marker" && -f "$marker" ]]; then
-        # Extract group ID from marker filename
-        AGENT_ID=$(basename "$marker" | sed 's/claude-parallel-//' | sed 's/\.marker//')
+        # Extract group ID: strip the project-scoped prefix and the suffix.
+        AGENT_ID=$(basename "$marker" .marker)
+        AGENT_ID=${AGENT_ID#"$_MARKER_BASE"}
         IS_PARALLEL_AGENT="true"
         break
     fi
-done < <(find "${_TMPDIR}" -maxdepth 1 -name "claude-parallel-*.marker" 2>/dev/null)
+done < <(find "${_TMPDIR}" -maxdepth 1 -name "${_MARKER_BASE}*.marker" 2>/dev/null)
 
 # === TIMING END ===
 # Include agent ID in log format if available (AC-4)
@@ -253,7 +266,7 @@ if [[ "${CLAUDE_HOOKS_COVERAGE:-}" == "true" ]]; then
             COVERAGE_LOG="${_LOG_DIR}/claude-coverage.log"
 
             # Get changed source files (excluding tests)
-            changed_files=$(git diff main...HEAD --name-only 2>/dev/null | grep -E '\.(ts|tsx|js|jsx)$' | grep -v -E '\.test\.|\.spec\.|__tests__' || true)
+            changed_files=$(git diff origin/main...HEAD --name-only 2>/dev/null | grep -E '\.(ts|tsx|js|jsx)$' | grep -v -E '\.test\.|\.spec\.|__tests__' || true)
 
             if [[ -n "$changed_files" ]]; then
                 echo "$(date +%H:%M:%S) COVERAGE_ANALYSIS: Checking test coverage for changed files" >> "$QUALITY_LOG"