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

package/dist/bin/cli.js

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

package/dist/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
 ```