sequant 2.10.0 → 2.12.0

package/dist/src/lib/workflow/worktree-resolver.js

@@ -0,0 +1,126 @@
+/**
+ * Repo-scoped worktree resolution and verification (#899).
+ *
+ * Skill-driven `/fullsolve` used to hand `/exec` an unexpanded glob
+ * (`../worktrees/feature/<issue>-` followed by a star and a slash) and `/exec`
+ * was instructed to trust it without checking. Two things went wrong:
+ *
+ * 1. When nothing had created the worktree, the `cd` failed and the agent
+ *    silently kept working in the main checkout.
+ * 2. `../worktrees/` is one flat namespace shared by every repo under the same
+ *    parent directory, and issue numbers are per-repo — so where the glob *did*
+ *    match, it could match a sibling project's worktree.
+ *
+ * Both are fixed the same way: never resolve worktrees through the filesystem.
+ * `git worktree list` reports only the worktrees of the repository containing
+ * `cwd`, so scoping is structural rather than a filter that can be forgotten,
+ * and it reports the *branch*, which is the real identity — a worktree
+ * directory slug can drift from its branch after a rename.
+ */
+import { existsSync, realpathSync, statSync } from "fs";
+import path from "path";
+import { listWorktrees } from "./worktree-manager.js";
+/**
+ * Find the worktree of the *current* repository that holds issue `issue`.
+ *
+ * Selection keys on the branch git reports, never on the directory name, so a
+ * worktree whose slug has drifted from its branch still resolves — and a
+ * directory that merely looks like a match (a sibling repo's worktree, or a
+ * stray directory) never does.
+ *
+ * @param issue - Issue number to look up.
+ * @param cwd - Directory inside the repository to search. Defaults to process cwd.
+ */
+export function resolveIssueWorktree(issue, cwd) {
+    const matches = listWorktrees(cwd)
+        .filter((w) => w.issue === issue)
+        .map(({ path: p, branch }) => ({ path: p, branch }));
+    if (matches.length === 0) {
+        return {
+            ok: false,
+            error: "WORKTREE_NOT_FOUND",
+            message: `WORKTREE_NOT_FOUND: no worktree of this repository has a branch for issue #${issue}. ` +
+                `Create one with \`./scripts/new-feature.sh ${issue}\`.`,
+            candidates: [],
+        };
+    }
+    if (matches.length > 1) {
+        const list = matches.map((m) => `${m.branch} -> ${m.path}`).join("; ");
+        return {
+            ok: false,
+            error: "WORKTREE_AMBIGUOUS",
+            message: `WORKTREE_AMBIGUOUS: ${matches.length} worktrees claim issue #${issue} (${list}). ` +
+                `Remove the stale one, or set SEQUANT_WORKTREE explicitly.`,
+            candidates: matches,
+        };
+    }
+    return { ok: true, ...matches[0] };
+}
+/**
+ * Canonicalize a path for comparison, tolerating paths that do not exist.
+ *
+ * `realpathSync` throws on a missing path, so fall back to resolving the
+ * deepest existing ancestor and re-appending the remainder — enough to make
+ * `/tmp/...` and `/private/tmp/...` compare equal on macOS.
+ */
+function canonicalize(target) {
+    const absolute = path.resolve(target);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        const parent = path.dirname(absolute);
+        if (parent === absolute)
+            return absolute;
+        return path.join(canonicalize(parent), path.basename(absolute));
+    }
+}
+/**
+ * Verify that a caller-supplied worktree path is safe to work in.
+ *
+ * This is the guard `/exec` runs before trusting `SEQUANT_WORKTREE`. It fails
+ * closed on every uncertain case — a bad path must halt the run, never degrade
+ * into "keep going in whatever directory we happen to be in".
+ *
+ * @param worktreePath - The path to check (typically `$SEQUANT_WORKTREE`).
+ * @param options.issue - When set, the branch must belong to this issue.
+ * @param options.cwd - Directory inside the repository to check against.
+ */
+export function verifyWorktreePath(worktreePath, options = {}) {
+    const raw = worktreePath.trim();
+    if (raw.length === 0 || raw.includes("*")) {
+        return {
+            ok: false,
+            error: "SEQUANT_WORKTREE_NOT_FOUND",
+            message: `SEQUANT_WORKTREE_NOT_FOUND: ${raw.length === 0 ? "empty path" : `unexpanded glob "${raw}"`}. Expected a resolved absolute directory.`,
+        };
+    }
+    const absolute = path.resolve(raw);
+    if (!existsSync(absolute) || !statSync(absolute).isDirectory()) {
+        return {
+            ok: false,
+            error: "SEQUANT_WORKTREE_NOT_FOUND",
+            message: `SEQUANT_WORKTREE_NOT_FOUND: "${raw}" is not an existing directory.`,
+        };
+    }
+    const canonical = canonicalize(absolute);
+    const known = listWorktrees(options.cwd);
+    const match = known.find((w) => canonicalize(w.path) === canonical);
+    if (!match) {
+        return {
+            ok: false,
+            error: "SEQUANT_WORKTREE_FOREIGN",
+            message: `SEQUANT_WORKTREE_FOREIGN: "${raw}" is not a worktree of this repository. ` +
+                `It belongs to another project or is stale; \`../worktrees/\` is shared across repos.`,
+        };
+    }
+    if (options.issue !== undefined && match.issue !== options.issue) {
+        return {
+            ok: false,
+            error: "SEQUANT_WORKTREE_ISSUE_MISMATCH",
+            message: `SEQUANT_WORKTREE_ISSUE_MISMATCH: "${raw}" has branch "${match.branch}", ` +
+                `which is not issue #${options.issue}.`,
+        };
+    }
+    return { ok: true, path: match.path, branch: match.branch };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sequant",
-  "version": "2.10.0",
+  "version": "2.12.0",
   "description": "AI coding agent orchestrator — resolve GitHub issues end-to-end with isolated git worktrees, quality gates, and an MCP server. Works with Claude Code or Aider.",
   "type": "module",
   "bin": {
@@ -24,10 +24,11 @@
     "build": "rm -rf dist/src dist/bin dist/dashboard && tsc && chmod +x dist/bin/cli.js",
     "dev": "tsx bin/cli.ts",
     "test": "vitest run",
-    "lint": "eslint src/ bin/ --max-warnings 0",
+    "lint": "eslint src/ bin/ scripts/ --max-warnings 0",
     "sync:skills": "npx tsx scripts/check-skill-sync.ts --fix",
     "sync:hooks": "bash scripts/sync-hooks.sh",
     "validate:skills": "for skill in templates/skills/*/; do case \"$skill\" in *_shared*|*/references/*) continue;; esac; npx skills-ref validate \"$skill\"; done",
+    "typecheck:scripts": "tsc --noEmit -p tsconfig.scripts.json",
     "lint:skill-calls": "npx tsx scripts/lint-skill-calls.ts",
     "lint:skill-gates": "npx tsx scripts/lint-skill-gates.ts",
     "lint:skill-sync": "npx tsx scripts/check-skill-sync.ts",
@@ -93,7 +94,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.142",
     "@hono/node-server": "^2.0.0",
     "boxen": "^8.0.1",
-    "chalk": "^5.3.0",
+    "chalk": "^6.0.0",
     "chokidar": "^5.0.0",
     "cli-table3": "^0.6.5",
     "commander": "^14.0.3",

package/templates/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/templates/scripts/cleanup-worktree.sh

@@ -357,26 +357,47 @@ else
     echo -e "${YELLOW}⏭️  Skipped remote-branch delete (PR not merged; pass --delete-remote or --force to override).${NC}"
 fi
 
-# Update main
+# Refresh local main WITHOUT switching the main checkout's branch (#910). The
+# old flow ran `git checkout main` here unconditionally — a branch switch of
+# the shared main checkout, exactly the mutation the #901 checkout lock exists
+# to serialize. The pre-tool guard cannot see it (the top-level command is this
+# script, which carries no guarded git verb), so a session that lost the lock
+# could still yank the holder off its branch — the same bypass #910 closed in
+# new-feature.sh. Two cases:
+#   - already on main: update in place (fetch + ff-only pull; rebase only on
+#     divergence). Same landing point as before; no branch switch involved.
+#   - on any other branch (or detached HEAD): leave the checkout alone and
+#     fast-forward the local `main` REF via `git fetch origin main:main`,
+#     which never touches the working tree. When that is not fast-forwardable
+#     (local main diverged/ahead, or main is checked out in another worktree),
+#     report and skip — resolving that is the holder's call, not this script's.
 echo -e "${BLUE}📥 Updating main branch...${NC}"
-git checkout main
 git fetch origin main
-
-# Handle divergent branches gracefully
-if ! git merge-base --is-ancestor HEAD origin/main 2>/dev/null; then
-    # Local is behind or diverged - fast-forward or rebase
-    if git merge-base --is-ancestor origin/main HEAD 2>/dev/null; then
-        # Local is ahead - nothing to do
-        echo -e "${BLUE}   Local main is ahead of origin${NC}"
-    else
-        # Diverged or behind - try fast-forward first
-        if ! git pull --ff-only origin main 2>/dev/null; then
-            echo -e "${YELLOW}   Divergent branches detected, rebasing...${NC}"
-            git rebase origin/main
+CURRENT_BRANCH=$(git symbolic-ref --quiet --short HEAD || echo "")
+
+if [ "$CURRENT_BRANCH" = "main" ]; then
+    # Handle divergent branches gracefully
+    if ! git merge-base --is-ancestor HEAD origin/main 2>/dev/null; then
+        # Local is behind or diverged - fast-forward or rebase
+        if git merge-base --is-ancestor origin/main HEAD 2>/dev/null; then
+            # Local is ahead - nothing to do
+            echo -e "${BLUE}   Local main is ahead of origin${NC}"
+        else
+            # Diverged or behind - try fast-forward first
+            if ! git pull --ff-only origin main 2>/dev/null; then
+                echo -e "${YELLOW}   Divergent branches detected, rebasing...${NC}"
+                git rebase origin/main
+            fi
         fi
+    else
+        git pull --ff-only origin main 2>/dev/null || true
     fi
 else
-    git pull --ff-only origin main 2>/dev/null || true
+    if git fetch origin main:main 2>/dev/null; then
+        echo -e "${BLUE}   Updated local main ref (checkout left on ${CURRENT_BRANCH:-detached HEAD})${NC}"
+    else
+        echo -e "${YELLOW}   ⏭️  Skipped local main update (not fast-forwardable); checkout left on ${CURRENT_BRANCH:-detached HEAD}${NC}"
+    fi
 fi
 
 echo ""