sequant 2.10.0 → 2.12.0

package/dist/src/lib/ac-parser.d.ts

@@ -30,6 +30,20 @@
  * ```
  */
 import { type AcceptanceCriterion, type AcceptanceCriteria, type ACVerificationMethod } from "./workflow/state-schema.js";
+/**
+ * Build a word-boundary-anchored, case-insensitive matcher for a keyword.
+ * `\b` sits correctly around spaces and hyphens too, so this is safe for
+ * both single words ("ui") and phrases ("end-to-end", "unit test") — a
+ * phrase already reads as self-anchoring under plain substring matching,
+ * and anchoring it doesn't change that (#946).
+ *
+ * @param allowPlural - Also match a trailing "s" (e.g. `flag` -> `flags`).
+ *   Only meaningful for single nouns/verbs that commonly appear inflected
+ *   in prose; multi-word phrases never need it.
+ *
+ * @internal Exported for testing only — not part of the module's public API.
+ */
+export declare function keywordMatcher(keyword: string, allowPlural?: boolean): RegExp;
 /**
  * Infer verification method from description text
  *
@@ -37,6 +51,32 @@ import { type AcceptanceCriterion, type AcceptanceCriteria, type ACVerificationM
  * @returns The inferred verification method (defaults to 'manual')
  */
 export declare function inferVerificationMethod(description: string): ACVerificationMethod;
+/**
+ * Resolve the verification method for an AC, preferring a declared
+ * `Evidence:` clause over keyword inference (#938).
+ *
+ * - Evidence names a backtick-quoted command containing a unit-test
+ *   token (`test`, `vitest`, `jest`) → `unit_test`.
+ * - Evidence names any other backtick-quoted command → `integration_test`.
+ * - Evidence is prose with no backtick command (e.g. "human review") →
+ *   `manual`.
+ * - No evidence declared → falls back to {@link inferVerificationMethod}.
+ *
+ * @param description - The AC description text (evidence clause stripped)
+ * @param evidence - The declared evidence clause, if any
+ * @returns The resolved verification method
+ */
+export declare function resolveVerificationMethod(description: string, evidence?: string): ACVerificationMethod;
+/**
+ * Whether a declared `Evidence:` clause describes a CLAUDE.md-style gate
+ * test — a fixture-exists / section-present / flag-wired assertion — rather
+ * than an ordinary behavioral unit/integration test or a human sign-off.
+ *
+ * @param evidence - The declared evidence clause text (from {@link splitEvidenceClause})
+ * @returns True when the evidence text matches the gate-test keyword set and
+ *   does not read as a manual-review attestation
+ */
+export declare function isGateTestEvidence(evidence: string): boolean;
 /**
  * Parse acceptance criteria from GitHub issue markdown
  *

package/dist/src/lib/ac-parser.js

@@ -30,6 +30,7 @@
  * ```
  */
 import { createAcceptanceCriterion, createAcceptanceCriteria, } from "./workflow/state-schema.js";
+import { computeFenceMask } from "./markdown-fence.js";
 /**
  * Regex patterns for AC extraction
  *
@@ -115,6 +116,39 @@ const VERIFICATION_KEYWORDS = {
     "manual test": "manual",
     verify: "manual",
 };
+/**
+ * Escape regex metacharacters in a literal keyword before embedding it in a
+ * constructed RegExp.
+ */
+function escapeRegExp(literal) {
+    return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Build a word-boundary-anchored, case-insensitive matcher for a keyword.
+ * `\b` sits correctly around spaces and hyphens too, so this is safe for
+ * both single words ("ui") and phrases ("end-to-end", "unit test") — a
+ * phrase already reads as self-anchoring under plain substring matching,
+ * and anchoring it doesn't change that (#946).
+ *
+ * @param allowPlural - Also match a trailing "s" (e.g. `flag` -> `flags`).
+ *   Only meaningful for single nouns/verbs that commonly appear inflected
+ *   in prose; multi-word phrases never need it.
+ *
+ * @internal Exported for testing only — not part of the module's public API.
+ */
+export function keywordMatcher(keyword, allowPlural = false) {
+    const escaped = escapeRegExp(keyword);
+    const pattern = allowPlural ? `\\b${escaped}s?\\b` : `\\b${escaped}\\b`;
+    return new RegExp(pattern, "i");
+}
+/**
+ * Precompiled, longest-keyword-first matchers for {@link VERIFICATION_KEYWORDS}.
+ * Longest-first preserves the original precedence (e.g. "unit test" wins
+ * over a lone "unit").
+ */
+const VERIFICATION_KEYWORD_MATCHERS = Object.entries(VERIFICATION_KEYWORDS)
+    .sort((a, b) => b[0].length - a[0].length)
+    .map(([keyword, method]) => ({ regex: keywordMatcher(keyword), method }));
 /**
  * Infer verification method from description text
  *
@@ -122,16 +156,156 @@ const VERIFICATION_KEYWORDS = {
  * @returns The inferred verification method (defaults to 'manual')
  */
 export function inferVerificationMethod(description) {
-    const lowerDesc = description.toLowerCase();
-    // Check for explicit keywords (longer phrases first)
-    const sortedKeywords = Object.keys(VERIFICATION_KEYWORDS).sort((a, b) => b.length - a.length);
-    for (const keyword of sortedKeywords) {
-        if (lowerDesc.includes(keyword)) {
-            return VERIFICATION_KEYWORDS[keyword];
+    for (const { regex, method } of VERIFICATION_KEYWORD_MATCHERS) {
+        if (regex.test(description)) {
+            return method;
         }
     }
     return "manual";
 }
+/**
+ * Matches a trailing `Evidence:` clause on an AC line (#938). Only the
+ * LAST occurrence is honored — the clause is defined as trailing, and AC
+ * prose can legitimately contain the word "Evidence:" earlier in the
+ * sentence (e.g. "the report cites strong Evidence: peer review ..."
+ * before the real declaration). Splitting on the first match would corrupt
+ * extraction by swallowing the real trailing clause into the description.
+ */
+const EVIDENCE_CLAUSE_RE = /\bEvidence:\s*/gi;
+/**
+ * Split a trailing `Evidence:` clause out of an AC description (#938).
+ *
+ * @param description - The AC description text (post ID-stripping)
+ * @returns The description with the clause removed, plus the declared
+ *   evidence text if present
+ */
+function splitEvidenceClause(description) {
+    const matches = [...description.matchAll(EVIDENCE_CLAUSE_RE)];
+    if (matches.length === 0)
+        return { description };
+    const last = matches[matches.length - 1];
+    const before = description.slice(0, last.index).trim();
+    const evidence = description.slice(last.index + last[0].length).trim();
+    if (!before || !evidence)
+        return { description };
+    return { description: before, evidence };
+}
+/**
+ * Matches a backtick-quoted command inside a declared evidence clause.
+ * A command (vs. prose like "human review") is what makes evidence
+ * runnable/checkable rather than a manual attestation.
+ */
+const EVIDENCE_COMMAND_RE = /`([^`]+)`/;
+/**
+ * Command tokens that indicate a unit-test invocation. Anything else
+ * backtick-quoted (CLI commands, curl, scripts) is treated as an
+ * integration-level check.
+ */
+const UNIT_TEST_COMMAND_RE = /\b(test|vitest|jest)\b/i;
+/**
+ * Resolve the verification method for an AC, preferring a declared
+ * `Evidence:` clause over keyword inference (#938).
+ *
+ * - Evidence names a backtick-quoted command containing a unit-test
+ *   token (`test`, `vitest`, `jest`) → `unit_test`.
+ * - Evidence names any other backtick-quoted command → `integration_test`.
+ * - Evidence is prose with no backtick command (e.g. "human review") →
+ *   `manual`.
+ * - No evidence declared → falls back to {@link inferVerificationMethod}.
+ *
+ * @param description - The AC description text (evidence clause stripped)
+ * @param evidence - The declared evidence clause, if any
+ * @returns The resolved verification method
+ */
+export function resolveVerificationMethod(description, evidence) {
+    if (evidence) {
+        const commandMatch = EVIDENCE_COMMAND_RE.exec(evidence);
+        if (commandMatch) {
+            return UNIT_TEST_COMMAND_RE.test(commandMatch[1])
+                ? "unit_test"
+                : "integration_test";
+        }
+        return "manual";
+    }
+    return inferVerificationMethod(description);
+}
+/**
+ * Keywords matching the CLAUDE.md "gate test" definition — a test whose job
+ * is to gate a claim that "a fixture exists, a skill section is present, a
+ * flag is wired" (#830, #939). Distinct from {@link VERIFICATION_KEYWORDS}:
+ * those classify *how* an AC is checked (unit/integration/browser/manual),
+ * this classifies *what kind of claim* the test makes, independent of
+ * verification method.
+ *
+ * A heuristic, not a hard classifier — same caveat {@link inferVerificationMethod}
+ * already carries. Over-firing sweeps ordinary tests into the gate-test
+ * population (inflating the mutation-verification gate's authoring burden);
+ * under-firing lets a real gate test slip through ungated, the exact defect
+ * class #830 exists to prevent.
+ */
+/**
+ * Single-word gate-test keywords that commonly appear inflected/pluralized
+ * in evidence prose ("flags are wired", "fixtures exist", "the section
+ * presents..."). Matched with an optional trailing "s" (#946 AC-4) so
+ * anchoring to word boundaries doesn't lose those forms.
+ */
+const GATE_TEST_PLURAL_KEYWORDS = ["fixture", "section", "flag", "present"];
+/**
+ * Single-word gate-test keywords with no natural plural/inflection needed
+ * for this AC's evidence phrasing — matched as exact words only.
+ */
+const GATE_TEST_SINGULAR_KEYWORDS = ["wired", "exists", "registered"];
+/**
+ * Multi-word gate-test phrases, matched as substrings (already
+ * self-anchoring, same rationale as {@link VERIFICATION_KEYWORDS} phrases).
+ *
+ * The mutation-verification rule (CLAUDE.md, #830) IS the gate-test
+ * definition — an AC that already names its own mutation-verified record
+ * is self-identifying, even when it doesn't separately name a
+ * fixture/section/flag (e.g. "lint test fails when the §7 entry is
+ * deleted (mutation-verified)").
+ */
+const GATE_TEST_PHRASE_KEYWORDS = [
+    "skill gate",
+    "mutation-verified",
+    "mutation test",
+];
+const GATE_TEST_KEYWORD_MATCHERS = [
+    ...GATE_TEST_PLURAL_KEYWORDS.map((k) => keywordMatcher(k, true)),
+    ...GATE_TEST_SINGULAR_KEYWORDS.map((k) => keywordMatcher(k)),
+    ...GATE_TEST_PHRASE_KEYWORDS.map((k) => keywordMatcher(k)),
+];
+/**
+ * Phrases that mark evidence as a human-review attestation rather than an
+ * automated gate test, even when a {@link GATE_TEST_KEYWORD_MATCHERS} term also
+ * appears (#939 QA finding: "reviewed manually, fixture exists in the demo
+ * env" false-positived on `fixture` alone). Checked first and short-circuits
+ * to `false` — a human sign-off is not the mutation-verifiable claim §6i
+ * gates on, regardless of which nouns it happens to mention.
+ */
+const MANUAL_REVIEW_NEGATIVE_SIGNALS = [
+    "reviewed manually",
+    "manual review",
+    "human review",
+    "manually verified",
+    "manually confirmed",
+];
+/**
+ * Whether a declared `Evidence:` clause describes a CLAUDE.md-style gate
+ * test — a fixture-exists / section-present / flag-wired assertion — rather
+ * than an ordinary behavioral unit/integration test or a human sign-off.
+ *
+ * @param evidence - The declared evidence clause text (from {@link splitEvidenceClause})
+ * @returns True when the evidence text matches the gate-test keyword set and
+ *   does not read as a manual-review attestation
+ */
+export function isGateTestEvidence(evidence) {
+    const lower = evidence.toLowerCase();
+    if (MANUAL_REVIEW_NEGATIVE_SIGNALS.some((signal) => lower.includes(signal))) {
+        return false;
+    }
+    return GATE_TEST_KEYWORD_MATCHERS.some((regex) => regex.test(evidence));
+}
 /**
  * Parse a single line and extract AC if present
  *
@@ -146,12 +320,14 @@ function parseACLine(line) {
         if (match) {
             // Combine groups 2 and 3 for bold-wrapped format (Pattern 3)
             // where group 3 captures optional text after closing **
-            const description = match[3]
+            const rawDescription = match[3]
                 ? `${match[2].trim()} ${match[3].trim()}`.trim()
                 : match[2].trim();
+            const { description, evidence } = splitEvidenceClause(rawDescription);
             return {
                 id: match[1].toUpperCase(),
                 description,
+                ...(evidence !== undefined ? { evidence } : {}),
             };
         }
     }
@@ -181,11 +357,11 @@ function parseACLine(line) {
 export function parseAcceptanceCriteria(issueBody) {
     const criteria = [];
     const seenIds = new Set();
-    const push = (id, description) => {
+    const push = (id, description, evidence) => {
         if (seenIds.has(id))
             return;
         seenIds.add(id);
-        criteria.push(createAcceptanceCriterion(id, description, inferVerificationMethod(description)));
+        criteria.push(createAcceptanceCriterion(id, description, resolveVerificationMethod(description, evidence), evidence));
     };
     // Split into lines and process each. `inAcSection` tracks whether the
     // current line falls under an `## Acceptance Criteria` heading; it toggles on
@@ -193,6 +369,10 @@ export function parseAcceptanceCriteria(issueBody) {
     // rule as `parseNonGoals` in ready-gate.ts). `bareCount` numbers synthesized
     // IDs for bare checkboxes in appearance order.
     const lines = issueBody.split("\n");
+    // Lines inside a fenced code block (#947) — an AC-authoring example shown
+    // in a fence must not be scanned as a real AC, or toggle the AC-section
+    // heading state, in either pass below.
+    const fenceMask = computeFenceMask(lines);
     let inAcSection = false;
     let bareCount = 0;
     // Pre-scan for explicit IDs anywhere in the body. Synthesis must skip IDs
@@ -201,12 +381,17 @@ export function parseAcceptanceCriteria(issueBody) {
     // synthesizes AC-1 first and the author's explicit AC-1 is silently dropped
     // by the first-occurrence dedupe.
     const explicitIds = new Set();
-    for (const line of lines) {
-        const parsed = parseACLine(line);
+    for (let i = 0; i < lines.length; i++) {
+        if (fenceMask[i])
+            continue;
+        const parsed = parseACLine(lines[i]);
         if (parsed)
             explicitIds.add(parsed.id);
     }
-    for (const line of lines) {
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (fenceMask[i])
+            continue;
         if (HEADING_RE.test(line)) {
             inAcSection = AC_HEADING_RE.test(line);
             continue;
@@ -215,14 +400,15 @@ export function parseAcceptanceCriteria(issueBody) {
         // so previously-parsable issues are unaffected (AC-4).
         const parsed = parseACLine(line);
         if (parsed) {
-            push(parsed.id, parsed.description);
+            push(parsed.id, parsed.description, parsed.evidence);
             continue;
         }
         // Bare-checkbox fallback: only inside the AC section (AC-1/AC-2).
         if (inAcSection) {
             const bare = line.match(BARE_CHECKBOX_RE);
-            const description = bare?.[1].trim();
-            if (description) {
+            const bareText = bare?.[1].trim();
+            if (bareText) {
+                const { description, evidence } = splitEvidenceClause(bareText);
                 // Synthesize `AC-<n>`, skipping any ID already taken by an explicit
                 // marker — before OR after this line — so a synthesized ID can never
                 // collide with (and be silently dropped against) a hand-written one.
@@ -230,7 +416,7 @@ export function parseAcceptanceCriteria(issueBody) {
                 do {
                     id = `AC-${++bareCount}`;
                 } while (seenIds.has(id) || explicitIds.has(id));
-                push(id, description);
+                push(id, description, evidence);
             }
         }
     }

package/dist/src/lib/cli-flags.d.ts

@@ -31,3 +31,26 @@ export declare function parseWholeNumber(flag: string, opts: WholeNumberOptions)
  * `merge --watch` messages this originally shipped with do not change.
  */
 export declare function parsePositiveSeconds(flag: string): (value: string) => number;
+/**
+ * Build a commander coercion for a `--models`/`--efforts`-shaped flag (#914).
+ *
+ * Validates the spec via `config-resolver.ts`'s `parsePhaseSpec` — a bare
+ * value applies to every phase, a comma list of `phase=value` pairs applies
+ * per phase, and a malformed spec (empty segment, mixed bare/pair form, or
+ * an unrecognized phase name) fails fast here rather than reaching
+ * `resolvePhasePolicies` silently. On success, returns the ORIGINAL raw spec
+ * string unchanged (not the parsed map) — `RunOptions.models`/`.efforts`
+ * stay plain strings, and `resolvePhasePolicies` re-parses for real when
+ * building `ExecutionConfig.phasePolicies`, so parsing has exactly one
+ * source of truth even though it runs twice.
+ *
+ * `allowedValues`, when given, additionally rejects any resolved value not
+ * in the set — used for `--efforts` (closed enum: `settings.ts:EFFORT_LEVELS`)
+ * so a typo like `--efforts exec=mediu` fails at the CLI boundary the same
+ * way it already does when set via `settings.json`, instead of only
+ * surfacing once the value reaches the SDK. `--models` passes no
+ * `allowedValues` — model aliases/IDs are intentionally unvalidated (they
+ * churn independently of sequant releases; the SDK errors clearly on a bad
+ * one).
+ */
+export declare function parsePhaseSpecFlag(flag: string, phaseNames: string[], allowedValues?: readonly string[]): (value: string) => string;

package/dist/src/lib/cli-flags.js

@@ -8,6 +8,7 @@
  * @module
  */
 import { InvalidArgumentError } from "commander";
+import { parsePhaseSpec } from "./workflow/config-resolver.js";
 /**
  * Build a commander coercion for a whole-number flag.
  *
@@ -44,3 +45,45 @@ export function parsePositiveSeconds(flag) {
         unitSingular: "second",
     });
 }
+/**
+ * Build a commander coercion for a `--models`/`--efforts`-shaped flag (#914).
+ *
+ * Validates the spec via `config-resolver.ts`'s `parsePhaseSpec` — a bare
+ * value applies to every phase, a comma list of `phase=value` pairs applies
+ * per phase, and a malformed spec (empty segment, mixed bare/pair form, or
+ * an unrecognized phase name) fails fast here rather than reaching
+ * `resolvePhasePolicies` silently. On success, returns the ORIGINAL raw spec
+ * string unchanged (not the parsed map) — `RunOptions.models`/`.efforts`
+ * stay plain strings, and `resolvePhasePolicies` re-parses for real when
+ * building `ExecutionConfig.phasePolicies`, so parsing has exactly one
+ * source of truth even though it runs twice.
+ *
+ * `allowedValues`, when given, additionally rejects any resolved value not
+ * in the set — used for `--efforts` (closed enum: `settings.ts:EFFORT_LEVELS`)
+ * so a typo like `--efforts exec=mediu` fails at the CLI boundary the same
+ * way it already does when set via `settings.json`, instead of only
+ * surfacing once the value reaches the SDK. `--models` passes no
+ * `allowedValues` — model aliases/IDs are intentionally unvalidated (they
+ * churn independently of sequant releases; the SDK errors clearly on a bad
+ * one).
+ */
+export function parsePhaseSpecFlag(flag, phaseNames, allowedValues) {
+    return (value) => {
+        let parsed;
+        try {
+            parsed = parsePhaseSpec(value, phaseNames);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new InvalidArgumentError(`${flag}: ${message}`);
+        }
+        if (allowedValues) {
+            for (const v of Object.values(parsed)) {
+                if (!allowedValues.includes(v)) {
+                    throw new InvalidArgumentError(`${flag}: '${v}' is not one of ${allowedValues.join("|")}.`);
+                }
+            }
+        }
+        return value;
+    };
+}

package/dist/src/lib/cli-ui/run-renderer-types.d.ts

@@ -117,6 +117,8 @@ export interface IssueSummary {
     loopTriggered?: boolean;
     prNumber?: number;
     prUrl?: string;
+    /** Set when PR creation was skipped for lack of commits ahead of base (#920). */
+    prSkippedReason?: string;
     failureReason?: string;
     qaVerdict?: string;
     unmetCount?: number;

package/dist/src/lib/cli-ui/run-renderer.js

@@ -1332,7 +1332,13 @@ function renderSummaryDetail(r, ctx) {
             .map((p) => (p.success ? c.green(p.name) : c.red(p.name)))
             .join(" → ");
         const pr = r.prNumber ? ` · PR #${r.prNumber}` : "";
-        return { summary: `${phaseSeq}${pr}`, extras: [] };
+        // #920: a phase-restricted run (no PR, no failure) still needs the reason
+        // stated — otherwise a passing spec-only run looks indistinguishable from
+        // one where PR creation was simply never attempted for no stated reason.
+        const extras = !r.prNumber && r.prSkippedReason
+            ? [c.dim(`PR skipped — ${r.prSkippedReason}`)]
+            : [];
+        return { summary: `${phaseSeq}${pr}`, extras };
     }
     // Failed → multi-line detail.
     const reason = r.failureReason ?? "failure";

package/dist/src/lib/locks/checkout-lock.d.ts

@@ -0,0 +1,193 @@
+/**
+ * CheckoutLock — working-tree-scoped lock (#901).
+ *
+ * The per-issue lock from #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. This lock represents the checkout.
+ *
+ * Relationship to `LockManager`:
+ *   - Stale semantics are *shared code*, not a parallel implementation — this
+ *     class calls the same exported `classifyStaleness`, so the same-host
+ *     dead-PID rule, the age ceiling and `SEQUANT_MAX_LOCK_AGE_MS` behave
+ *     identically by construction (AC-4).
+ *   - `LockManager`'s numeric key is left alone. Widening `lockPathFor` /
+ *     `acquire` / `release` / `list` / `held` from `number` to `string` would
+ *     ripple through `status.ts`, `merge.ts`, `resume.ts` and
+ *     `run-orchestrator.ts`, all of which pass real issue numbers, for the
+ *     benefit of exactly one new key. The cost of not widening is the
+ *     duplicated `O_CREAT|O_EXCL` write below (~30 lines).
+ *
+ * Orchestrator / MCP mode: every public method is a no-op, mirroring
+ * `LockManager` (AC-5).
+ */
+import { type CheckoutAcquireResult, type CheckoutHolderIdentity, type CheckoutLockFile, type CheckoutLockListing } from "./types.js";
+/**
+ * Reserved holder id for `/release`, which mutates the main checkout but has
+ * no issue of its own (#911). The lock file and the `pre-tool.sh` guard both
+ * key on a positive integer, so the skill claims the tree under this sentinel
+ * rather than a symbolic label (which would require schema + CLI + hook
+ * changes — tracked in #911 as a follow-up).
+ */
+export declare const RELEASE_SENTINEL_ISSUE = 999999999;
+/**
+ * Render a checkout-lock holder's issue for CLI display. The sentinel is not
+ * a real issue, and printing it as `#999999999` invites readers to go looking
+ * for one.
+ */
+export declare function describeCheckoutHolderIssue(issue: number): string;
+export interface CheckoutLockOptions {
+    /** Directory holding lock files (default: `.sequant/locks`). */
+    locksDir?: string;
+    /** Age cutoff (ms) for cross-host locks. Default 2h. */
+    staleAgeMs?: number;
+    /** Age cutoff (ms) for skill-shell locks (`skipPidCheck`). Default 6h. */
+    skillLockTtlMs?: number;
+    /** Absolute age ceiling (ms). Default 24h (#856). */
+    maxLockAgeMs?: number;
+    /** Override for orchestrator detection (test seam). */
+    orchestratorMode?: boolean;
+    /** Override for `os.hostname()` (test seam). */
+    hostname?: string;
+    /** Override for current process PID (test seam). */
+    pid?: number;
+    /** Predicate: is PID alive on this host? (test seam) */
+    isPidAlive?: (pid: number) => boolean;
+    /** Clock (ms since epoch). Test seam. */
+    now?: () => number;
+}
+/**
+ * Does `identity` own the checkout `holder` claimed? (#906)
+ *
+ * One predicate for both `acquire`'s reentrancy check and `release`'s
+ * permission check, so the two cannot disagree about who the holder is: a
+ * session able to release by a given identity is exactly the one able to
+ * re-acquire by it. Exported for the hook-parity tests.
+ *
+ * The rules are ordered, and the order is load-bearing:
+ *
+ *  1. Cross-host callers never own the lock. Checked first — no weaker rule
+ *     below may overturn it.
+ *  2. When *both* sides carry a `sessionId`, equality decides and nothing
+ *     falls through: a mismatch is positive proof of non-ownership, so
+ *     consulting a weaker signal afterwards could only overturn a stronger
+ *     one. (Dormant in the shipped flow — no env var carries Claude Code's
+ *     session id into a skill shell, so `acquire` never passes one. Kept
+ *     because leaking a lock for its TTL is the safer failure.)
+ *  3. Same PID on the same host: a live process releasing its own lock.
+ *  4. `skipPidCheck` locks only: the holder's issue number. A skill shell's
+ *     PID is dead by the time the next block runs — that is what
+ *     `skipPidCheck` marks — so the issue is the only identity left, and the
+ *     hook's blocking side (`pre-tool.sh`) already decides holder-ness the
+ *     same way. Deliberately a *courtesy* check, not a security boundary:
+ *     the issue number is readable from the lock file and `clear --force`
+ *     exists. It defends against the accident this rule was written for — a
+ *     *blocked* session running its release contract, which by construction
+ *     carries a different issue.
+ *  5. Anything else is refused.
+ */
+export declare function isCheckoutOwner(holder: CheckoutLockFile, identity: CheckoutHolderIdentity): boolean;
+/**
+ * Build the refusal text for a blocked session (AC-2 + AC-3).
+ *
+ * AC-2 requires the message name the holding session and its issue; AC-3
+ * requires it say how to proceed rather than only reporting the block. Both
+ * halves are produced here, in one place, so the CLI and the hook cannot
+ * drift on wording.
+ *
+ * @param holder    The session currently holding the checkout.
+ * @param blocked   The issue the *refused* session is working on, when known —
+ *                  used to name the worktree it should be using instead.
+ * @param nowMs     Clock, for the human-readable age.
+ */
+export declare function formatCheckoutLockedMessage(holder: CheckoutLockFile, blocked?: {
+    issue?: number;
+}, nowMs?: number): string;
+export declare class CheckoutLock {
+    private readonly locksDir;
+    private readonly staleAgeMs;
+    private readonly skillLockTtlMs;
+    private readonly maxLockAgeMs;
+    private readonly orchestratorMode;
+    private readonly hostname;
+    private readonly pid;
+    private readonly isPidAlive;
+    private readonly now;
+    constructor(options?: CheckoutLockOptions);
+    /** True if all operations are no-ops (orchestrator/MCP mode). */
+    get isNoop(): boolean;
+    /** Absolute path to the checkout lock file. */
+    get lockPath(): string;
+    /**
+     * This process's identity, for callers that don't have a session id.
+     *
+     * Deliberately carries no `issue` (#906): a bare `release()` losing the
+     * power to remove a *skill-shell* lock is the fix working, not an omission.
+     * A caller that legitimately owns such a lock knows its issue and must say
+     * so — `release({ ...lock.selfIdentity, issue })`.
+     */
+    get selfIdentity(): CheckoutHolderIdentity;
+    /**
+     * Claim the checkout for `issue`.
+     *
+     * Re-acquiring while already the holder succeeds idempotently
+     * (`reentrant: true`) — a session must not be able to block itself part-way
+     * through its own run.
+     */
+    acquire(issue: number, command: string, options?: {
+        sessionId?: string;
+        skipPidCheck?: boolean;
+    }): CheckoutAcquireResult;
+    /**
+     * Release the checkout if `identity` owns it. Returns true when a lock was
+     * removed — `false` covers both "nothing held" and "held, but not yours".
+     *
+     * Ownership is `isCheckoutOwner`, the same predicate `acquire` uses. Before
+     * #906 this method took any same-host caller's word for a `skipPidCheck`
+     * lock, which made acquire and release asymmetric in the one scenario the
+     * lock exists for: a second session's *acquire* was correctly refused while
+     * the holder was fresh, but its *release* — which every `/fullsolve` halt
+     * branch runs — succeeded and handed the tree away mid-run.
+     *
+     * `LockManager.releaseExternal` keeps the looser same-host rule safely
+     * because its lock *file* is issue-keyed: naming the file already proves the
+     * caller knows the issue. `checkout.lock` has a constant filename, so that
+     * proof has to move into the identity — which is exactly what rule 4 of
+     * `isCheckoutOwner` asks for.
+     */
+    release(identity?: CheckoutHolderIdentity): boolean;
+    /** Read the holder without acquiring. Null when free or unparseable. */
+    check(): CheckoutLockFile | null;
+    /** Holder plus computed staleness metadata, for `locks list`. */
+    listing(): CheckoutLockListing | null;
+    /**
+     * Manually clear the checkout lock. With `safetyCheck` (default), refuses to
+     * clear a holder that is still fresh — mirrors `LockManager.clearLock`.
+     *
+     * A file that exists but does not parse is removed unconditionally (#906).
+     * That state is reachable: `writeAtomic` creates the file with `openSync`
+     * and writes to it as a second step, so a process killed in between leaves a
+     * zero-byte `checkout.lock` (#856 documents the group-SIGKILL that does it).
+     * Before this branch existed such a file was unclearable by any command —
+     * `clear` read it, saw `null`, and reported `no-lock` without unlinking
+     * (`--force` only ever reached the *staleness* check, never the read), while
+     * `acquire` threw raw `EEXIST` and the hook, unable to parse any field,
+     * blocked on it forever. `safetyCheck` is not consulted because there is no
+     * holder to protect: unparseable bytes name no session.
+     */
+    clear(options?: {
+        safetyCheck?: boolean;
+    }): {
+        cleared: boolean;
+        reason: string;
+    };
+    /**
+     * Delegates wholesale to the per-issue lock's classifier so the two locks
+     * cannot drift on staleness (AC-4).
+     */
+    private staleness;
+    private writeAtomic;
+    private readSafe;
+    private unlinkSafe;
+}