sequant 2.11.0 → 2.13.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.10.0",
+      "version": "2.13.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.11.0",
+  "version": "2.13.0",
   "author": {
     "name": "sequant-io",
     "email": "hello@sequant.io"

package/README.md

@@ -1,8 +1,8 @@
 # Sequant
 
-**Spec-driven AI coding agents — every acceptance criterion verified, stops at the human merge gate.**
+**AI coding agents that prove their work — every acceptance criterion verified, and you hold the merge button.**
 
-For teams that can't ship un-reviewed AI code. Solve GitHub issues with structured phases and quality gates — from issue to merge-ready PR.
+For developers who won't merge what they can't trust — solo or on a team. Solve GitHub issues with structured phases and quality gates, from issue to merge-ready PR.
 
 **[sequant.io](https://sequant.io)** — docs, guides, and getting started.
 
@@ -12,10 +12,30 @@ For teams that can't ship un-reviewed AI code. Solve GitHub issues with structur
 [![CI](https://github.com/sequant-io/sequant/actions/workflows/ci.yml/badge.svg)](https://github.com/sequant-io/sequant/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-AI coding agents write code well, but leave you to run the workflow around it — planning, isolation, review, and merge safety. Sequant wraps an agent in a structured **spec → exec → qa** pipeline with isolated git worktrees and quality gates, taking a GitHub issue from triage to a merge-ready PR without babysitting each step.
+AI coding agents write code well, but leave you to run the workflow around it — planning, isolation, review, and merge safety. Sequant wraps an agent in a structured **spec → exec → qa** pipeline with isolated git worktrees and quality gates, taking a GitHub issue from triage to a merge-ready PR without babysitting each step. The PR arrives with evidence — each acceptance criterion checked against the code — and the merge is always yours.
 
 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.13
+
+- **NEEDS_VERIFICATION verdicts stop blocking their own follow-up** — a QA verdict of NEEDS_VERIFICATION now maps to a dedicated `awaiting_verification` state instead of `ready_for_merge`, so after you execute the ACs the qa re-run just runs — no `--force`, no editing `state.json` by hand. The state shows up in `sequant status` and the dashboard with a re-run hint, and an issue whose PR you merge directly still sweeps to `merged`. MCP `sequant_run` also gains a real `force` parameter (previously silently ignored). The full verdict→state contract is documented in [qa-verdict-workflow-states.md](docs/features/qa-verdict-workflow-states.md) (#972).
+- **A bad model name is now a loud failure, not a silent no-op** — when a phase's session ends on an API error (e.g. a typo'd or roster-stale model string), the driver now fails the phase with the API error text and structured `terminal_reason`/`api_error_status` context, instead of reporting a zero-work "success" that only surfaced downstream as an empty diff entering QA (#973).
+- **Model roles: name the tier, not the model** — `run.modelRoles` maps semantic roles (defaults: `fast`, `strong`, `frontier`) to model strings, and phase policy or `--models` can reference them as `role:fast`. Raw model strings still pass through verbatim, a missing role fails loudly at config-resolution before any session spawns, and run metrics record both the requested value and the concrete model ID actually dispatched — so a roster change means editing one map, not every settings file (#975). `agents.model` now accepts any model string instead of a stale three-model enum.
+- **A constitution with teeth** — the constitution template is now the enforceable agent contract: its Definition of Done table is *generated* from `/qa`'s real gate list and drift-gated in CI (`lint:constitution-dod`), an AC authoring standard is cross-linked from `/spec`'s lint output, and every Boundaries/Budgets rule names its actual enforcing mechanism — a gate test asserts every cited settings key and hook path resolves. Customized constitutions are preserved by `update`/`sync`; the new template reaches fresh `init` projects only (#943).
+
+### What's new in 2.12
+
+- **QA gates you can parse, not just read** — `/qa` now closes every review with a structured findings marker (six-category taxonomy, evidence, recommended action) that `/loop` and `sequant ready` consume directly, so a finding QA itself called non-blocking is never burned as a fix iteration (#937). Gate-test ACs must ship a machine-checkable `SEQUANT_MUTATION` record in the PR body, enforced by `/qa` (#939), and an AC can declare its own verification command via a trailing `Evidence:` clause that QA must actually execute (#938). A new advisory CI job annotates PRs with likely-vacuous tests (#940).
+- **`/fullsolve` stops at the PR** — it no longer merges the PR it creates; pass `--auto-merge` (or set `run.autoMerge: true`) for the previous end-to-end behavior (#958). `/merger` gains a Named-Set Boundary: it merges only the issues you name, halting with a report if a dependency outside that set turns up (#961).
+- **Phase agents get an MCP allowlist, not your desktop config** — headless phase agents now receive the sequant MCP server plus the project's own `.mcp.json`, never a passthrough of Claude Desktop config (which can carry literal secrets into process argv). `run.mcpAllowlist` opts specific desktop-only servers back in deliberately (#936). See [run-command.md](docs/reference/run-command.md#allowlisting-a-desktop-only-server).
+
+### What's new in 2.11
+
+- **Per-phase `model`/`effort` configuration** — the new `sequant run`/`sequant ready` flags `--models`/`--efforts` (bare value applies to every phase, or a comma list of `phase=model` pairs) let a phase's Agent SDK session use a different Claude model or reasoning effort than the CLI default — e.g. planning with a stronger model and delegating implementation to a cheaper one. Absent by default: nothing changes unless configured. See [run-command.md](docs/reference/run-command.md#per-phase-model--effort).
+- **Evidence-based effort escalation on retries** — `--escalate-effort` raises a retried phase execution's reasoning effort one tier above its resolved base, built on the per-phase effort resolver above. Escalates only on *observed* retry (an outer quality-loop iteration ≥ 2, or a `sequant ready` QA-pass ≥ 2) — never speculatively — so it can only trade cost for quality, never the reverse. See [run-command.md](docs/reference/run-command.md#effort-escalation-on-retries).
+- **Checkout-scoped lock for the shared working tree** — the per-issue lock never protected the *checkout itself*: two sessions on different issues could still interleave `git checkout`/`reset`/`rebase`/`merge` in the same main working tree. `sequant locks checkout <acquire|release|check|clear>` and a `pre-tool.sh` hook now guard branch-mutating git in the main checkout directly, refusing a foreign session with the holder's identity and how to proceed (#901).
+- **`sequant worktree resolve/verify`** — resolves and verifies an issue's worktree by the branch git reports rather than a directory-name glob, closing a shared-namespace collision that could point `/fullsolve`, `/exec`, `/qa`, `/loop`, `/testgen`, `/merger` or `/assess` at the wrong worktree (#899, #904).
+
 ### 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).
@@ -162,6 +182,17 @@ your-project/           # Main repo (stays on main branch)
 - Each issue has its own dependencies and build
 - Safe to discard failed experiments
 
+### Agent Contract
+
+Every project gets `.claude/memory/constitution.md` — the machine-enforceable agent contract that answers "what will the agent refuse to do, what must every PR satisfy, and where does it stop for me?":
+
+- **Definition of Done** — generated from `/qa`'s §7 gate list; a CI check (`lint:constitution-dod`) fails when the table drifts from the live gates. These are project-wide — issue ACs don't restate them.
+- **AC Authoring Standard** — the house format for writing ACs (single-line, `Evidence:`/`Risk:`/`Human decision` fields, Non-Goals); referenced by `/spec`'s lint warnings.
+- **Boundaries** — every rule names its enforcer: the force-push hook, the worktree-only editing guard, the mutation-verification gate.
+- **Budgets & Stop Conditions** — iteration caps, the human merge gate, hold states, and gap-prompt discipline.
+
+The file is a `CUSTOMIZABLE_FILES` entry: plain `sequant update` and `sync` preserve your edits. Only `--force` replaces it.
+
 ### Quality Gates
 
 Every `/qa` runs automated checks:
@@ -177,6 +208,19 @@ Every `/qa` runs automated checks:
 
 When checks fail, `/loop` automatically fixes and re-runs (up to 3x).
 
+### Thinking of building this on a graph framework?
+
+You could assemble this workflow yourself on LangGraph, CrewAI, Mastra, or the Claude Agent SDK — they sell the primitives and leave the workflow as an exercise. Sequant is the finished, hardened version of what you'd end up building, in the frameworks' own vocabulary:
+
+- **Isolated execution** — one git worktree per issue, resolved by the branch git reports rather than directory globs
+- **Human-in-the-loop approval gate** — the pipeline stops at the PR and never merges; this is an invariant, not optional wiring
+- **Guardrails** — QA verdicts with an enforced floor, mutation-verified gate tests, scope and security checks
+- **Durable execution** — a rate-limit halt writes a resumable record; `sequant resume` picks up where it left off, skipping completed phases
+- **State management** — per-issue and checkout-scoped locks, so concurrent sessions can't interleave git operations in the same tree
+- **Deterministic control flow** — dependency-ordered batch scheduling over `blocked by #N` relationships
+
+On a general framework, every one of these is something you wire up — and can wire wrong or skip. Here they hold for every run. The boring 80% (retries, resume, locking, exit codes your scripts can trust) has already been run in anger; the [CHANGELOG](CHANGELOG.md) is the receipts.
+
 ---
 
 ## Using Sequant

package/dist/dashboard/server.js

@@ -42,6 +42,8 @@ function getStatusClass(status) {
             return "primary";
         case "waiting_for_qa_gate":
             return "warning";
+        case "awaiting_verification":
+            return "warning";
         case "ready_for_merge":
             return "success";
         case "blocked":
@@ -347,6 +349,7 @@ function renderIssuesList(issues) {
         in_progress: [],
         waiting_for_qa_gate: [],
         waiting_for_human_merge: [],
+        awaiting_verification: [],
         ready_for_merge: [],
         blocked: [],
         not_started: [],
@@ -364,6 +367,7 @@ function renderIssuesList(issues) {
     const statusOrder = [
         "in_progress",
         "waiting_for_qa_gate",
+        "awaiting_verification",
         "ready_for_merge",
         "blocked",
         "not_started",

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.10.0",
+  "version": "2.13.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@2.10.0", "serve"]
+    "args": ["-y", "sequant@2.13.0", "serve"]
   }
 }

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

@@ -75,6 +75,15 @@ sequant init
 - **Pre-tool guardrails** — blocks dangerous commands, enforces worktree safety
 - **Post-tool tracking** — timing, quality metrics, smart test runner
 
+### Agent Contract
+
+Every project gets `.claude/memory/constitution.md` — the machine-enforceable agent contract that answers "what must every PR satisfy, and where does the agent stop?":
+
+- **Definition of Done** — generated from `/qa`'s §7 gate list; a CI check fails on drift
+- **AC Authoring Standard** — the house format for ACs; referenced by `/spec`'s lint warnings
+- **Boundaries** — every rule names its enforcer (hook, gate, or settings key)
+- **Budgets & Stop Conditions** — iteration caps, the human merge gate, and hold states
+
 ## Quick Start
 
 ```

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

@@ -17,6 +17,16 @@ INPUT_JSON=$(cat)
 # Parse JSON using jq (preferred) or fallback to grep
 if command -v jq &>/dev/null; then
     TOOL_NAME=$(echo "$INPUT_JSON" | jq -r '.tool_name // empty')
+    # Claude Code's hook envelope carries the session id (same field
+    # capture-tokens.sh reads). Preferred holder identity for the checkout
+    # lock (#901): a skill shell's PID dies right after acquire, the session
+    # id does not. `// empty` keeps this safe if the field is ever absent —
+    # the guard then falls back to SEQUANT_ISSUE.
+    SESSION_ID=$(echo "$INPUT_JSON" | jq -r '.session_id // empty')
+    # The shell cwd the tool will run in. Distinct from CLAUDE_PROJECT_DIR,
+    # which stays pinned to the main checkout even while the agent works in a
+    # worktree — see the checkout-lock guard (#901).
+    HOOK_CWD=$(echo "$INPUT_JSON" | jq -r '.cwd // empty')
     # For Bash tool, extract .command from tool_input; for others, stringify the whole object
     if [[ "$(echo "$INPUT_JSON" | jq -r '.tool_name // empty')" == "Bash" ]]; then
         TOOL_INPUT=$(echo "$INPUT_JSON" | jq -r '.tool_input.command // empty')
@@ -25,9 +35,59 @@ if command -v jq &>/dev/null; then
     fi
 else
     TOOL_NAME=$(echo "$INPUT_JSON" | grep -oE '"tool_name"\s*:\s*"[^"]+"' | head -1 | cut -d'"' -f4)
+    SESSION_ID=$(echo "$INPUT_JSON" | grep -oE '"session_id"\s*:\s*"[^"]+"' | head -1 | cut -d'"' -f4)
+    HOOK_CWD=$(echo "$INPUT_JSON" | grep -oE '"cwd"\s*:\s*"[^"]+"' | head -1 | cut -d'"' -f4)
     # For Bash tool, extract command from tool_input; for others, extract the whole object
     if [[ "$TOOL_NAME" == "Bash" ]]; then
-        TOOL_INPUT=$(echo "$INPUT_JSON" | grep -oE '"command"\s*:\s*"[^"]+"' | head -1 | cut -d'"' -f4)
+        # Escape-aware extraction (#963 gap B): the naive `grep -oE '"[^"]+"'`
+        # form (still used for the simpler fields above, where an embedded
+        # `\"` is implausible) stops at the FIRST escaped quote inside the
+        # JSON string, truncating any command containing one — e.g.
+        # `git commit -m "msg with \"quotes\""` would be cut down to just
+        # `git commit -m ` before it ever reaches the guards below.
+        #
+        # sed's `(([^"\\]|\\.)*)` captures the full escaped run — any run of
+        # non-quote/non-backslash chars, or a backslash paired with whatever
+        # follows it — up to the closing unescaped `"`. `JSON.stringify`
+        # guarantees the whole payload is one physical line, so a single
+        # sed pass is enough (no multi-line `-z` needed, which BSD sed lacks
+        # anyway).
+        #
+        # The captured text still carries JSON string escapes literally
+        # (`\"`, `\\`, `\n`, `\t`, ...); the awk pass resolves them in ONE
+        # left-to-right scan, consuming two characters per recognized
+        # escape. That ordering is what a chain of separate sed/tr
+        # substitutions cannot get right without a placeholder: a literal
+        # `\\n` in the original command is an escaped backslash (`\\`)
+        # immediately followed by a literal `n`, and must stay a backslash
+        # plus 'n' — not become an escaped-newline (`\n`) if the two escapes
+        # were resolved out of order. Scanning once and advancing past both
+        # characters of whichever escape is recognized sidesteps that
+        # ambiguity entirely.
+        TOOL_INPUT=$(printf '%s' "$INPUT_JSON" \
+            | sed -E -n 's/.*"command"[[:space:]]*:[[:space:]]*"(([^"\\]|\\.)*)".*/\1/p' \
+            | head -1 \
+            | awk '
+                {
+                    s = $0; out = ""; n = length(s)
+                    for (i = 1; i <= n; i++) {
+                        c = substr(s, i, 1)
+                        if (c == "\\" && i < n) {
+                            nc = substr(s, i + 1, 1)
+                            if (nc == "\"") { out = out "\""; i++ }
+                            else if (nc == "\\") { out = out "\\"; i++ }
+                            else if (nc == "n") { out = out "\n"; i++ }
+                            else if (nc == "t") { out = out "\t"; i++ }
+                            else if (nc == "r") { out = out "\r"; i++ }
+                            else if (nc == "/") { out = out "/"; i++ }
+                            else { out = out c }
+                        } else {
+                            out = out c
+                        }
+                    }
+                    print out
+                }
+            ')
     else
         TOOL_INPUT=$(echo "$INPUT_JSON" | grep -oE '"tool_input"\s*:\s*\{[^}]+\}' | head -1)
     fi
@@ -246,6 +306,51 @@ seg_match() {
     [[ -n "$SEGMENTS" ]] && grep -qE "$1" <<< "$SEGMENTS"
 }
 
+# resolve_cd_target <tool_input> — print the target directory of the LAST
+# `cd <path>` line in a (possibly multi-line) Bash command, if and only if
+# the path is a static literal (quoted or unquoted) that resolves to an
+# existing directory. Scans the raw command, not $SEGMENTS — emit_segments
+# drops double-quoted regions, so `cd "$WT"` would vanish there before this
+# ever saw it. Prints nothing when there is no `cd` line, the target is
+# dynamic (contains `$` or a backtick), or the path doesn't exist — callers
+# must treat empty output as "fail open", never as license to guess a
+# directory (#963).
+resolve_cd_target() {
+    local input="$1" line target
+    line=$(printf '%s\n' "$input" | grep -E '^[[:space:]]*cd[[:space:]]+' | tail -1)
+    [[ -z "$line" ]] && return 0
+
+    target=$(printf '%s' "$line" | sed -E 's/^[[:space:]]*cd[[:space:]]+//; s/[[:space:]]*[;&|].*$//; s/[[:space:]]+$//')
+
+    # Strip one layer of surrounding matching quotes.
+    case "$target" in
+        \"*\") target="${target#\"}"; target="${target%\"}" ;;
+        \'*\') target="${target#\'}"; target="${target%\'}" ;;
+    esac
+
+    # Fail open on anything dynamic — resolving shell expansions means
+    # reimplementing the shell, which is disproportionate; `git commit`
+    # itself already rejects a genuinely empty commit. A backslash is
+    # rejected too: it can escape a following `$`/`` ` `` into a form this
+    # literal-string check would otherwise miss, and a backslash also carries
+    # its own shell meaning (line continuation, escaped chars) that this
+    # function does not attempt to resolve — failing open is the safe
+    # direction either way (#963).
+    case "$target" in
+        *'$'*|*'`'*|*'\'*) return 0 ;;
+    esac
+
+    [[ -n "$target" && -d "$target" ]] && printf '%s' "$target"
+}
+
+# Path of the session->issue binding the checkout guard maintains (#906).
+# $1 = repo toplevel, $2 = session id. The id is opaque, so squash everything
+# outside a filename-safe set — it must not be able to escape the directory.
+_co_binding_path() {
+    printf '%s/.sequant/locks/session-%s.issue' \
+        "$1" "$(printf '%s' "$2" | tr -c 'A-Za-z0-9_-' '_')"
+}
+
 # Precompute the segment list once, for Bash commands only.
 SEGMENTS=""
 if [[ "$TOOL_NAME" == "Bash" ]]; then
@@ -458,6 +563,213 @@ if seg_match 'git reset.*(--hard|origin)'; then
     fi
 fi
 
+# --- Session -> issue binding for the checkout guard (Issue #906) ---
+# `SEQUANT_ISSUE` cannot identify the holder interactively, and never could:
+# PreToolUse runs OUTSIDE and BEFORE the command's shell, so nothing a skill
+# bash block exports is visible here — not even an export prepended to the same
+# block as the guarded command. The one path that does export it (`sequant run`)
+# also sets SEQUANT_ORCHESTRATOR, where this guard stands down. So the env
+# fallback below was unreachable in every real flow, and the holder was
+# routinely blocked by its own lock.
+#
+# The hook does see both the acquire and every later command of the same
+# session, and `session_id` survives the shell boundary that kills the
+# acquiring PID. Record the binding when we observe the acquire; read it back
+# when deciding whether the caller is the holder.
+if [[ -n "${SESSION_ID:-}" ]] && seg_match 'locks +checkout +(acquire|release)'; then
+    _CO_SB_ROOT=$(git -C "${HOOK_CWD:-$PWD}" rev-parse --show-toplevel 2>/dev/null || echo "")
+    if [[ -n "$_CO_SB_ROOT" && -d "$_CO_SB_ROOT/.git" ]]; then
+        _CO_SB_FILE=$(_co_binding_path "$_CO_SB_ROOT" "$SESSION_ID")
+        _CO_SB_ISSUE=$(printf '%s' "$TOOL_INPUT" \
+            | grep -oE '\-\-issue[= ]+[0-9]+' | head -1 | grep -oE '[0-9]+$' || true)
+        if seg_match 'locks +checkout +acquire'; then
+            if [[ -n "$_CO_SB_ISSUE" ]]; then
+                mkdir -p "$(dirname "$_CO_SB_FILE")" 2>/dev/null \
+                    && printf '%s' "$_CO_SB_ISSUE" > "$_CO_SB_FILE" 2>/dev/null || true
+            fi
+        elif [[ -f "$_CO_SB_FILE" ]]; then
+            # Clear only when the session releases its OWN claim. A refused
+            # release (wrong --issue) must not strip the real holder's identity
+            # and leave it blocked by its own lock.
+            if [[ -n "$_CO_SB_ISSUE" \
+                  && "$_CO_SB_ISSUE" == "$(cat "$_CO_SB_FILE" 2>/dev/null)" ]]; then
+                rm -f "$_CO_SB_FILE" 2>/dev/null || true
+            fi
+        fi
+    fi
+fi
+
+# --- Checkout-scoped lock enforcement (Issue #901) ---
+# The per-issue lock (#625) keys on issue number, so two sessions working
+# *different* issues take different lock files and never contend. But
+# `git checkout`, `switch`, `reset`, `rebase`, `merge` and `cherry-pick` are
+# global to a working tree — the contended resource is the checkout, not the
+# issue. `.sequant/locks/checkout.lock` represents the tree; this guard is what
+# makes it binding, because the racing actor is an agent's Bash command, not
+# sequant's TypeScript (which mutates git almost exclusively via `git -C
+# <worktree>`).
+#
+# STALENESS IS A DELIBERATELY WEAKER SUBSET, NOT A MIRROR. The authoritative
+# rules live in `classifyStaleness` (src/lib/locks/lock-manager.ts) and are
+# shared by CheckoutLock. Transcribing them into shell would drift (#871), so
+# this guard checks only the absolute age ceiling and FAILS OPEN past it. A
+# lock this guard lets through is still caught by the TypeScript path; a lock
+# it blocks on is always genuinely fresh. Weaker-but-honest beats a mirror.
+#
+# AC-5: orchestrator/MCP mode is a no-op here too, matching LockManager and
+# CheckoutLock — `sequant run` drives its own worktree isolation and must not
+# be blocked by a lock its own skills took.
+if [[ -z "${SEQUANT_ORCHESTRATOR:-}" ]] \
+   && seg_match 'git (checkout|switch|reset|rebase|merge|cherry-pick)( |$)' \
+   && ! seg_match 'git +-C ' \
+   && ! seg_match 'git checkout ([^ ]+ )?--( |$)'; then
+
+    # Only the MAIN checkout is protected — a command run inside a worktree
+    # touches only that worktree's HEAD and must never be blocked.
+    #
+    # Resolve where the command will ACTUALLY run. This must NOT use
+    # CLAUDE_PROJECT_DIR / PARALLEL_MARKER_PROJECT_ROOT: those name the
+    # *project* directory, which stays pinned to the main checkout even while
+    # the agent's shell sits in a worktree. Keying off them blocked legitimate
+    # in-worktree work — the guard's worst failure mode, since the whole point
+    # of the lock is to push sessions *into* worktrees.
+    #
+    # `.cwd` is part of Claude Code's PreToolUse envelope (verified against a
+    # live payload alongside `session_id`), with $PWD as the fallback.
+    _CO_CWD="${HOOK_CWD:-$PWD}"
+    # Honor a `cd <dir>` the same way the commit guard below does — including
+    # multi-line commands and quoted/dynamic targets (#963).
+    _CO_CD=$(resolve_cd_target "$TOOL_INPUT")
+    [[ -n "$_CO_CD" ]] && _CO_CWD="$_CO_CD"
+
+    # A linked worktree's toplevel has `.git` as a FILE; the main checkout has
+    # it as a directory.
+    _CO_ROOT=$(git -C "$_CO_CWD" rev-parse --show-toplevel 2>/dev/null || echo "")
+    if [[ -n "$_CO_ROOT" && -d "$_CO_ROOT/.git" ]]; then
+        _CO_LOCK="$_CO_ROOT/.sequant/locks/checkout.lock"
+
+        if [[ -f "$_CO_LOCK" ]]; then
+            if command -v jq &>/dev/null; then
+                _CO_HOLDER_ISSUE=$(jq -r '.issue // empty' "$_CO_LOCK" 2>/dev/null)
+                _CO_HOLDER_SESSION=$(jq -r '.sessionId // empty' "$_CO_LOCK" 2>/dev/null)
+                _CO_HOLDER_PID=$(jq -r '.pid // empty' "$_CO_LOCK" 2>/dev/null)
+                _CO_HOLDER_HOST=$(jq -r '.hostname // empty' "$_CO_LOCK" 2>/dev/null)
+                _CO_HOLDER_STARTED=$(jq -r '.startedAt // empty' "$_CO_LOCK" 2>/dev/null)
+                _CO_HOLDER_CMD=$(jq -r '.command // empty' "$_CO_LOCK" 2>/dev/null)
+            else
+                _CO_HOLDER_ISSUE=$(grep -oE '"issue"[[:space:]]*:[[:space:]]*[0-9]+' "$_CO_LOCK" | head -1 | grep -oE '[0-9]+$')
+                _CO_HOLDER_SESSION=$(grep -oE '"sessionId"[[:space:]]*:[[:space:]]*"[^"]*"' "$_CO_LOCK" | head -1 | cut -d'"' -f4)
+                _CO_HOLDER_PID=$(grep -oE '"pid"[[:space:]]*:[[:space:]]*[0-9]+' "$_CO_LOCK" | head -1 | grep -oE '[0-9]+$')
+                _CO_HOLDER_HOST=$(grep -oE '"hostname"[[:space:]]*:[[:space:]]*"[^"]*"' "$_CO_LOCK" | head -1 | cut -d'"' -f4)
+                _CO_HOLDER_STARTED=$(grep -oE '"startedAt"[[:space:]]*:[[:space:]]*"[^"]*"' "$_CO_LOCK" | head -1 | cut -d'"' -f4)
+                _CO_HOLDER_CMD=$(grep -oE '"command"[[:space:]]*:[[:space:]]*"[^"]*"' "$_CO_LOCK" | head -1 | cut -d'"' -f4)
+            fi
+
+            # Staleness. These branches mirror `classifyStaleness`
+            # (src/lib/locks/lock-manager.ts) in the same order, because AC-4
+            # requires the checkout lock's stale recovery to match the per-issue
+            # lock's — same-host dead PID, age ceiling, and the env overrides.
+            # Implementing only a subset here would let a *dead* holder block
+            # the tree for up to 24h, which is the wedge AC-4 forbids.
+            #
+            # The three rules are plain comparisons plus one `kill -0`, so this
+            # is a small enough surface to keep honest; the "hook/TypeScript
+            # staleness parity" cases in checkout-lock.integration.test.ts pin
+            # both sides to the same verdict so they cannot drift silently
+            # (#871 — the repo's drift guard compares literal strings only and
+            # would not see a semantic divergence here).
+            _CO_MAX_AGE_MS="${SEQUANT_MAX_LOCK_AGE_MS:-86400000}"     # 24h ceiling
+            _CO_SKILL_TTL_MS="${SEQUANT_SKILL_LOCK_TTL_MS:-21600000}" # 6h skill-shell
+            _CO_STALE_AGE_MS=7200000                                  # 2h cross-host
+            _CO_FRESH=true
+
+            # `startedAt` is ISO-8601 **UTC**. BSD `date -j -f` parses in LOCAL
+            # time, so without TZ=UTC the age comes out shifted by the UTC
+            # offset — west of UTC that is *negative*, and a stale lock then
+            # reads as fresh forever, wedging the tree. TZ=UTC pins the BSD
+            # branch; Linux/CI falls through to GNU `date -u -d`, which honors
+            # the trailing Z.
+            _CO_AGE_MS=""
+            if [[ -n "$_CO_HOLDER_STARTED" ]]; then
+                _CO_STARTED_EPOCH=$(TZ=UTC date -j -f "%Y-%m-%dT%H:%M:%S" "${_CO_HOLDER_STARTED%%.*}" +%s 2>/dev/null \
+                    || date -u -d "$_CO_HOLDER_STARTED" +%s 2>/dev/null || echo "")
+                if [[ -n "$_CO_STARTED_EPOCH" ]]; then
+                    _CO_AGE_MS=$(( ( $(date +%s) - _CO_STARTED_EPOCH ) * 1000 ))
+                    # Negative age = clock skew between hosts. Treat as unknown
+                    # rather than stale: refusing is recoverable, silently
+                    # ignoring a live holder is not.
+                    [[ "$_CO_AGE_MS" -lt 0 ]] && _CO_AGE_MS=""
+                fi
+            fi
+
+            _CO_SKIP_PID=false
+            grep -q '"skipPidCheck"[[:space:]]*:[[:space:]]*true' "$_CO_LOCK" 2>/dev/null && _CO_SKIP_PID=true
+
+            # 0. Absolute ceiling, checked first and unconditionally (#856):
+            #    past it a PID is no longer trustworthy identity.
+            if [[ -n "$_CO_AGE_MS" && "$_CO_AGE_MS" -gt "$_CO_MAX_AGE_MS" ]]; then
+                _CO_FRESH=false
+            # 1. Same-host PID check is authoritative — unless the holder asked
+            #    us to skip it (a skill shell whose PID dies after acquire).
+            elif [[ "$_CO_HOLDER_HOST" == "$(hostname)" && "$_CO_SKIP_PID" == "false" ]]; then
+                # `kill -0` is a bash builtin: no subprocess on the hot path.
+                if [[ -n "$_CO_HOLDER_PID" ]] && ! kill -0 "$_CO_HOLDER_PID" 2>/dev/null; then
+                    _CO_FRESH=false
+                fi
+            # 2. Cross-host or skipPidCheck: the PID is meaningless, use age.
+            elif [[ -n "$_CO_AGE_MS" ]]; then
+                if [[ "$_CO_SKIP_PID" == "true" ]]; then
+                    _CO_TTL_MS="$_CO_SKILL_TTL_MS"
+                else
+                    _CO_TTL_MS="$_CO_STALE_AGE_MS"
+                fi
+                [[ "$_CO_AGE_MS" -gt "$_CO_TTL_MS" ]] && _CO_FRESH=false
+            fi
+
+            # Is this session the holder? sessionId is the only identity that
+            # survives a skill shell exiting between acquire and this call, so
+            # it wins when both sides have one. Otherwise fall back to the
+            # issue this session is working on.
+            _CO_IS_HOLDER=false
+            if [[ -n "$_CO_HOLDER_SESSION" && -n "$SESSION_ID" ]]; then
+                [[ "$_CO_HOLDER_SESSION" == "$SESSION_ID" ]] && _CO_IS_HOLDER=true
+            elif [[ -n "${SEQUANT_ISSUE:-}" && -n "$_CO_HOLDER_ISSUE" ]]; then
+                # Reachable only from a parent process that exported it — never
+                # from a skill bash block (#906). Kept for `sequant run`-shaped
+                # callers; the binding below is what works interactively.
+                [[ "${SEQUANT_ISSUE}" == "$_CO_HOLDER_ISSUE" ]] && _CO_IS_HOLDER=true
+            elif [[ -n "${SESSION_ID:-}" && -n "$_CO_HOLDER_ISSUE" ]]; then
+                # The binding this hook recorded when it saw THIS session run
+                # `locks checkout acquire --issue=N` (#906).
+                _CO_BIND=$(_co_binding_path "$_CO_ROOT" "$SESSION_ID")
+                [[ -f "$_CO_BIND" \
+                   && "$(cat "$_CO_BIND" 2>/dev/null)" == "$_CO_HOLDER_ISSUE" ]] \
+                    && _CO_IS_HOLDER=true
+            fi
+
+            if [[ "$_CO_FRESH" == "true" && "$_CO_IS_HOLDER" == "false" ]]; then
+                log_block "checkout-lock"
+                {
+                    echo "HOOK_BLOCKED: Checkout held by another session"
+                    echo ""
+                    echo "  The working tree is held by the session working #${_CO_HOLDER_ISSUE:-?}"
+                    echo "  (PID ${_CO_HOLDER_PID:-?} on ${_CO_HOLDER_HOST:-?}, started ${_CO_HOLDER_STARTED:-?})."
+                    echo "  Command: ${_CO_HOLDER_CMD:-?}"
+                    echo ""
+                    echo "  Branch-mutating git here would race with that session."
+                    echo ""
+                    echo "  To proceed:"
+                    echo "    • Work in your own worktree: ../worktrees/feature/<your-issue>-*/"
+                    echo "      (create it with: ./scripts/new-feature.sh <your-issue>)"
+                    echo "    • Or target it explicitly: git -C <worktree> <command>"
+                    echo "    • If that session is gone: sequant locks checkout clear --force"
+                } >&2
+                exit 2
+            fi
+        fi
+    fi
+fi
+
 # CI/CD triggers (automation shouldn't trigger more automation)
 if seg_match 'gh workflow run'; then
     log_block "workflow-trigger"
@@ -554,18 +866,25 @@ fi
 # Skips for --amend since amending doesn't require new changes
 if [[ "$TOOL_NAME" == "Bash" ]] && seg_match 'git commit'; then
     if ! echo "$TOOL_INPUT" | grep -qE -- '--amend|--allow-empty'; then
-        # Extract target directory from cd command if present (for worktree commits)
-        # Handles: "cd /path && git commit" or "cd /path; git commit"
-        TARGET_DIR=""
-        if echo "$TOOL_INPUT" | grep -qE '^cd [^;&|]+'; then
-            TARGET_DIR=$(echo "$TOOL_INPUT" | grep -oE '^cd [^;&|]+' | head -1 | sed 's/^cd //' | tr -d ' ')
-        fi
-
-        # Check for changes in the target directory (or current if no cd)
-        if [[ -n "$TARGET_DIR" && -d "$TARGET_DIR" ]]; then
-            CHANGES=$(cd "$TARGET_DIR" && git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+        # Resolve where to check for changes: the last resolvable `cd`
+        # target if the command has one (multi-line commands included —
+        # #963), else the command's own cwd from the hook payload (never
+        # this hook process's own cwd, which need not match).
+        TARGET_DIR=$(resolve_cd_target "$TOOL_INPUT")
+        HAS_CD_LINE=false
+        echo "$TOOL_INPUT" | grep -qE '^[[:space:]]*cd[[:space:]]+' && HAS_CD_LINE=true
+
+        if [[ -n "$TARGET_DIR" ]]; then
+            CHANGES=$(git -C "$TARGET_DIR" status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+        elif [[ "$HAS_CD_LINE" == true ]]; then
+            # A `cd` line is present but its target is dynamic (a shell
+            # variable/command substitution) or doesn't exist as a
+            # directory — fail open rather than check the wrong
+            # directory. `git commit` itself already rejects a genuinely
+            # empty commit, so this costs one harmless git error (#963).
+            CHANGES=1
         else
-            CHANGES=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+            CHANGES=$(git -C "${HOOK_CWD:-$PWD}" status --porcelain 2>/dev/null | wc -l | tr -d ' ')
         fi
 
         if [[ "$CHANGES" -eq 0 ]]; then

package/dist/marketplace/external_plugins/sequant/skills/_shared/references/subagent-types.md

@@ -15,7 +15,7 @@ Claude Code supports exactly **4 built-in subagent types**:
 
 ## Custom Agents (Sequant)
 
-Sequant defines **4 custom agents** in `.claude/agents/`. These centralize model, permissions, effort, and tool restrictions that were previously duplicated inline.
+Sequant defines **3 custom agents** in `.claude/agents/`. These centralize model, permissions, effort, and tool restrictions that were previously duplicated inline.
 
 > **Upstream caveat:** `Model` values below are *declared* in the agent files but
 > currently ignored at runtime per anthropics/claude-code#43869 — every subagent
@@ -24,20 +24,10 @@ Sequant defines **4 custom agents** in `.claude/agents/`. These centralize model
 
 | Agent Name | Based On | Model (declared) | Permission Mode | Used By |
 |------------|----------|------------------|-----------------|---------|
-| `sequant-explorer` | Explore | haiku | (default) | `/spec` |
 | `sequant-qa-checker` | general-purpose | sonnet | bypassPermissions | `/qa` |
 | `sequant-implementer` | general-purpose | (inherits) | bypassPermissions | `/exec` |
 | `sequant-testgen` | general-purpose | haiku | (default) | `/testgen` |
 
-### sequant-explorer
-
-Read-only codebase exploration for the `/spec` phase. No Bash, Edit, or Write access.
-
-```
-Agent(subagent_type="sequant-explorer",
-     prompt="Find similar features in components/. Report patterns.")
-```
-
 ### sequant-qa-checker
 
 Quality check agent for the `/qa` phase. Has `bypassPermissions` for Bash access (git diff, npm test). Effort: low.
@@ -175,12 +165,11 @@ Agent(subagent_type="sequant-qa-checker",
 ```
 
 ### Context Gathering (via /spec)
+
+`/spec` defaults to targeted inline `Read`/`Grep`, not an agent spawn. It escalates to a single `Explore` agent only for open-ended discovery:
 ```
-Agent(subagent_type="sequant-explorer",
+Agent(subagent_type="Explore",
      prompt="Find similar features in components/. Report patterns.")
-
-Agent(subagent_type="sequant-explorer",
-     prompt="Explore database schema for user tables. Report structure.")
 ```
 
 ### Background Execution (via /exec)
@@ -215,7 +204,7 @@ inline when spawning them.
 | Task | Recommended Agent | Why |
 |------|-------------------|-----|
 | Quality checks (git diff, npm test) | `sequant-qa-checker` | bypassPermissions + effort:low (declared model: sonnet, inert per #43869) |
-| Codebase exploration | `sequant-explorer` | Read-only, focused tools (declared model: haiku, inert per #43869) |
+| Codebase exploration (open-ended only) | `Explore` | Read-only, built-in; `/spec` prefers inline Read/Grep by default |
 | Implementation subtask | `sequant-implementer` | Full access, inherits model |
 | Test stub generation | `sequant-testgen` | Write access, no Bash (declared model: haiku, inert per #43869) |
 | One-off custom task | `general-purpose` | Flexible, specify model/mode inline |
@@ -239,8 +228,8 @@ inline when spawning them.
 These types do **not exist** and will cause silent failures:
 
 - ~~`quality-checker`~~ → Use `sequant-qa-checker` or `general-purpose`
-- ~~`pattern-scout`~~ → Use `sequant-explorer` or `Explore`
-- ~~`schema-inspector`~~ → Use `sequant-explorer` or `Explore`
+- ~~`pattern-scout`~~ → Use `Explore`
+- ~~`schema-inspector`~~ → Use `Explore`
 - ~~`code-reviewer`~~ → Use `sequant-qa-checker` or `general-purpose`
 - ~~`implementation`~~ → Use `sequant-implementer` or `general-purpose`
 

package/dist/marketplace/external_plugins/sequant/skills/assess/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   author: sequant
   version: "3.0"
 allowed-tools:
+  - Bash(npx sequant worktree:*)
   - Read
   - Glob
   - Grep
@@ -99,7 +100,10 @@ gh issue view <N> --json title,body,labels,state,comments,assignees
 
 ```bash
 git branch -a | grep <N> || true
-git worktree list | grep <N> || true
+# Resolve by branch, not by grepping the printed path (#899/#904) — a bare
+# number match is cross-issue (89 matches 899-...) and keys on the directory
+# slug, which can diverge from the branch after a rename.
+npx sequant worktree resolve <N> || true
 gh pr list --search "<N> in:title" --json number,title,state,headRefName,mergeable || true
 ```