sequant 2.11.0 → 2.12.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.12.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.12.0",
   "author": {
     "name": "sequant-io",
     "email": "hello@sequant.io"

package/README.md

@@ -16,6 +16,19 @@ 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.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).

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.12.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.12.0", "serve"]
   }
 }

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
 ```
 

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

@@ -29,6 +29,7 @@ allowed-tools:
   # Worktree management
   - Bash(./scripts/new-feature.sh:*)
   - Bash(./scripts/cleanup-worktree.sh:*)
+  - Bash(npx sequant worktree:*)
   # GitHub CLI
   - Bash(gh issue view:*)
   - Bash(gh issue comment:*)
@@ -136,7 +137,7 @@ When running as part of an orchestrated workflow (e.g., `sequant run` or `/fulls
 
 1. **Skip pre-flight git checks** - The orchestrator has already verified git state
 2. **Skip worktree creation** - Orchestrator creates worktrees before invoking skills
-3. **Use provided worktree path** - Work in `SEQUANT_WORKTREE` instead of creating a new one
+3. **Verify, then use, the provided path** - `SEQUANT_WORKTREE` is authoritative *when valid*, but it is never trusted unchecked: run the existence guard in "Feature Worktree Workflow" below and halt if it fails (#899)
 4. **Reduce GitHub comment frequency** - Defer progress updates to the orchestrator
 5. **Trust issue context** - The orchestrator has already fetched and validated issue data
 
@@ -472,15 +473,68 @@ echo "Current branch: $CURRENT_BRANCH"
 **Why this matters:** Work done directly on main can be lost during sync operations (git reset, git pull --rebase, etc.). Worktrees provide isolation and safe recovery through branches.
 
 **If orchestrated (SEQUANT_WORKTREE is set):**
-- Use the provided worktree path directly: `cd $SEQUANT_WORKTREE`
-- Skip steps 1-2 below (worktree already created by orchestrator)
-- Continue with step 3 (Work in the worktree)
+
+<!-- BEGIN: worktree-existence-guard (#899) -->
+
+**Verify the path before you use it. Never `cd` into it unchecked.** An
+orchestrator can hand over a path that was never created, or one that resolves
+into a *different repository's* worktree — `../worktrees/` is one flat
+namespace shared by every repo under the same parent, and issue numbers are
+per-repo. A bare `cd` fails silently and leaves you implementing in the main
+checkout, on whatever branch it happens to be on.
+
+```bash
+npx sequant worktree verify "$SEQUANT_WORKTREE" --issue <issue-number> || {
+  echo "❌ HALT: SEQUANT_WORKTREE is not a usable worktree of this repository."
+  exit 1
+}
+cd "$SEQUANT_WORKTREE"
+```
+
+`verify` exits non-zero with one of these named errors. **Every one of them is
+a halt** — report it and stop; do not fall back to creating a worktree, and do
+not continue in the current directory:
+
+| Error | Meaning |
+|-------|---------|
+| `SEQUANT_WORKTREE_NOT_FOUND` | Path is empty, an unexpanded glob, or not an existing directory |
+| `SEQUANT_WORKTREE_FOREIGN` | Real directory, but not a worktree of *this* repository (another project's, or stale) |
+| `SEQUANT_WORKTREE_ISSUE_MISMATCH` | A worktree of this repo, but its branch belongs to a different issue |
+
+Once verify passes, skip steps 1-2 below and continue with step 3 (Work in the
+worktree).
+
+<!-- END: worktree-existence-guard (#899) -->
 
 **If standalone:**
 
-1. **Check if worktree already exists:**
-   - Check if you're already in a worktree: `git worktree list` or check if `../worktrees/` contains a directory for this issue
-   - If worktree exists, navigate to it and continue work there
+<!-- BEGIN: worktree-standalone-lookup (#899) -->
+
+1. **Check if a worktree already exists for this issue:**
+
+   Resolve through git, not the filesystem. `sequant worktree resolve` reads
+   `git worktree list` in the current repository — which reports only *this*
+   repo's worktrees — and selects on the **branch** git reports, not on the
+   directory name. That matters twice over: a directory slug is shared across
+   repositories, and it can drift from its own branch after a rename
+   (`578-seo-expand-city-coverage` holding branch `feature/578-city-expansion-clean`),
+   so a name match proves nothing about which branch you would land on.
+
+   ```bash
+   if WORKTREE="$(npx sequant worktree resolve <issue-number>)"; then
+     echo "Existing worktree: $WORKTREE"
+     cd "$WORKTREE"
+     # Continue work there — skip step 2.
+   else
+     echo "No worktree for #<issue-number> in this repository — create one (step 2)."
+   fi
+   ```
+
+   **Do not glob `../worktrees/feature/<issue-number>-*` to find it.** That
+   directory is shared by every sibling repository, so the match may belong to
+   another project entirely.
+
+<!-- END: worktree-standalone-lookup (#899) -->
 
 2. **Create worktree if needed (with parallel context gathering):**
 
@@ -1901,7 +1955,7 @@ The goal is to satisfy AC with the smallest, safest change possible.
 ### 6. Progress Summary and Draft Issue Update
 
 **If orchestrated (SEQUANT_ORCHESTRATOR is set):**
-- Skip posting progress comments to GitHub (orchestrator handles summary)
+- Skip posting progress comments to GitHub — no per-phase comment is posted under `sequant run`; progress surfaces through the run summary and the PR body (#964)
 - Still provide AC coverage summary in output for orchestrator to capture
 - Let orchestrator handle final GitHub update