sequant 2.8.0 → 2.10.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.8.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.8.0",
+  "version": "2.10.0",
   "author": {
     "name": "sequant-io",
     "email": "hello@sequant.io"

package/README.md

@@ -16,10 +16,24 @@ 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).
+- **Rate limits stop burning hours** — a rate limit hit inside a phase now skips doomed cold-start retries, and the run summary labels the chain halt with its cause and how to resume, instead of cascading into a ~2h retry ladder (#761).
+- **Stale plugin-cache warning** — `pre-tool.sh` now prints a once-per-day, network-free reminder (`claude plugin update sequant@sequant`) when a plugin-channel install has drifted behind the marketplace (#784, #788).
+
 ### 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
@@ -42,14 +56,14 @@ See the [CHANGELOG](CHANGELOG.md) for release notes, or the [migration guide](CH
 ### Prerequisites
 
 **An AI coding agent — one of:**
-- [Claude Code](https://claude.ai/code) — default agent
+- [Claude Code](https://claude.ai/code) — default agent. **Recommended: Claude Code ≥ 2.1.208.** The pre-tool hooks lean on Claude Code's native dangerous-`rm` analyzer (which fires even under `bypassPermissions`) instead of re-implementing catastrophic-delete detection; that analyzer's command-substitution coverage landed in 2.1.208. This is a recommendation, not an enforced floor — plugins cannot declare a minimum Claude Code version, so nothing gates install, and the pre-2.1.208 command-substitution gap (e.g. `echo "$(rm -rf ~)"`) is accepted rather than guarded.
 - [Aider](https://aider.chat/) — alternative, via `--agent aider`
 
 **Always required (both):**
 - [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
@@ -68,6 +82,8 @@ Pick the path that matches **where you run Sequant**:
 /sequant:setup
 ```
 
+> **Plugins do not auto-update.** Claude Code pins a plugin to the version you installed and never updates it on its own — even as new releases ship. To pick up a new version, run `claude plugin update sequant@sequant`, then restart Claude Code. Sequant's pre-tool hook warns once a day when your installed version falls behind the marketplace.
+
 **Headless / CI (npm package)** — drive runs from the terminal or a CI job:
 ```bash
 npm install sequant          # or: pnpm add / yarn add / bun add sequant
@@ -75,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:
@@ -228,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
 
@@ -239,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. |

package/dist/bin/cli.js

@@ -18,6 +18,7 @@ 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 { isCI, isStdoutTTY } from "../src/lib/tty.js";
 import { detectPackageManagerSync, getPackageManagerCommands, } from "../src/lib/stacks.js";
 // Read version from package.json dynamically
@@ -48,6 +49,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";
@@ -60,6 +62,7 @@ import { locksListCommand, locksClearCommand, locksAcquireCommand, locksReleaseC
 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 +145,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 +158,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 +182,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,25 +194,55 @@ 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")
     .option("--testgen", "Run testgen phase after spec")
     .option("--security-review", "Run security-review phase after spec")
     .option("-s, --quiet", "Suppress version warnings and non-essential output (heartbeat-only)")
-    .option("--chain", "Chain issues: each branches from previous (implies --sequential)")
+    .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")
     .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")')
@@ -219,12 +254,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({
@@ -252,7 +301,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];
@@ -274,6 +331,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);
@@ -282,13 +342,34 @@ 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("--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")
@@ -300,9 +381,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")
@@ -321,7 +402,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);
@@ -329,7 +410,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) {
@@ -363,7 +444,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)

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.8.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
 
@@ -20,6 +20,8 @@ Or browse in `/plugin > Discover`.
 
 After installing, run `/sequant:setup` to configure your project.
 
+> **Plugins do not auto-update.** Claude Code pins a plugin to the version you installed. To pick up a new release, run `claude plugin update sequant@sequant`, then restart Claude Code.
+
 ### npm (power users / CI)
 
 ```bash
@@ -29,7 +31,7 @@ sequant init
 
 ## What You Get
 
-### 17 Workflow Skills
+### 19 Workflow Skills
 
 | Skill | Purpose |
 |-------|---------|
@@ -49,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)
@@ -81,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

@@ -51,33 +51,61 @@ fi
 
 _TMPDIR="${TMPDIR:-/tmp}"
 
-# Use CLAUDE_PLUGIN_DATA for persistent logs (survives plugin updates)
-if [[ -n "${CLAUDE_PLUGIN_DATA}" ]]; then
+# Log sink (#763 AC-5c: blocked-command history must survive to be a useful
+# regression corpus, so $TMPDIR — which macOS purges — is a last resort only).
+#
+# This block MUST stay identical to the one in pre-tool.sh. The two hooks
+# write the *same* claude-timing.log (START there, END here) and the same
+# claude-quality.log, so any divergence silently splits every START/END pair
+# across two files.
+#
+# Every candidate is absolute and lives outside the repo. A repo-local or
+# relative path is wrong three times over: it resolves against the hook's cwd
+# (which Claude Code does not pin), it yields one sink per directory instead
+# of the single corpus AC-5 asks for, and — worst — creating it inside a repo
+# makes `git status --porcelain` non-empty, which silently defeats pre-tool.sh's
+# no-changes guard that reads exactly that output.
+if [[ -n "${CLAUDE_PLUGIN_DATA:-}" ]]; then
   _LOG_DIR="${CLAUDE_PLUGIN_DATA}/logs"
-  mkdir -p "$_LOG_DIR"
+elif [[ -n "${HOME:-}" ]]; then
+  _LOG_DIR="${HOME}/.sequant/logs"
 else
   _LOG_DIR="${_TMPDIR}"
 fi
+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)
@@ -238,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"