sequant 2.2.0 → 2.4.0

package/dist/src/lib/heuristics/behavior-rule-detector.js

@@ -0,0 +1,467 @@
+/**
+ * Behavior-Rule Detector (issue #552)
+ *
+ * Shared heuristic for `/spec` (proactive) and `/qa` (reactive) phases that
+ * detects when an AC describes a *behavior rule* (e.g. "default becomes X",
+ * "always include Y", "never skip Z") and, when triggered, surfaces all
+ * touchpoints in the codebase that likely implement the rule.
+ *
+ * Behavior rules are routinely duplicated across a skill prompt
+ * (LLM-interpreted) AND the runtime TypeScript that backs it. Without this
+ * detector, edits land at one site and the other goes stale — see issue #533
+ * (motivating miss; documented in `references/behavior-rule-detection.md`).
+ *
+ * Three exported functions:
+ * - `detectBehaviorRule` — cheap keyword check; gates the more expensive greps
+ * - `findTouchpoints`   — used by `/spec` to enumerate likely implementations
+ * - `findSurvivingInverseSymbols` — used by `/qa` to flag OLD-rule survivors
+ *   inside the diff blast radius
+ *
+ * The keyword set is the source of truth in this file (per the /spec Open
+ * Question on keyword location). The reference doc cites it.
+ *
+ * @example
+ * ```typescript
+ * import { detectBehaviorRule, findTouchpoints } from "./behavior-rule-detector.ts";
+ *
+ * const detection = detectBehaviorRule(ac);
+ * if (detection.triggered) {
+ *   const hits = findTouchpoints(ac, process.cwd());
+ *   for (const h of hits) console.log(`${h.path}:${h.line}  ${h.snippet}`);
+ * }
+ * ```
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+/**
+ * Behavior keywords whose presence (≥2 distinct, OR matching the explicit
+ * pattern below) signals an AC describes a rule rather than a localized fix.
+ * Tunable here; cited from `references/behavior-rule-detection.md`.
+ */
+export const BEHAVIOR_KEYWORDS = [
+    "default",
+    "always",
+    "never",
+    "rule",
+    "behavior",
+    "skip",
+];
+/**
+ * Per-stem inflection regex map. Mirrors the stem-aware pattern landed by
+ * #597 in `src/lib/ac-linter.ts`: build `\b<stem>(<suffixes>)?\b` so the
+ * keyword check matches common inflections (`defaults`, `skipping`,
+ * `behaviors`) without over-matching identifier-shaped tokens. Word
+ * boundaries are preserved so e.g. `defaultValue` does NOT match.
+ *
+ *  - `default` → matches `default`/`defaults`/`defaulted`/`defaulting`
+ *  - `always` / `never` — adverbs, no inflections
+ *  - `rule` — e-ending: `rule`/`rules`/`ruled`/`ruling`
+ *  - `behavior` — `behavior`/`behaviors`/`behavioral`/`behaviorally`
+ *  - `skip` — double-`p` per English: `skip`/`skips`/`skipped`/`skipping`
+ *
+ * Source-of-truth lives in this map so the test suite can read it (rather
+ * than each call site rebuilding the regex inline).
+ */
+const KEYWORD_REGEXES = {
+    default: /\bdefault(?:s|ed|ing)?\b/i,
+    always: /\balways\b/i,
+    never: /\bnever\b/i,
+    rule: /\brul(?:e|es|ed|ing)\b/i,
+    behavior: /\bbehavior(?:s|al|ally)?\b/i,
+    skip: /\bskip(?:s|ped|ping)?\b/i,
+};
+/**
+ * Explicit behavior-rule patterns that trigger detection even with a single
+ * keyword (false-positive guard exception). Two families:
+ *
+ * 1. Mid-sentence rule constructs:
+ *    - "always X unless Y", "never X unless Y", "default X when Y"
+ * 2. Imperative AC openers — when an AC description begins with a capitalized
+ *    `Always` / `Never` / `Default` followed by a verb, it's almost certainly
+ *    a behavior rule even with a single keyword. Covers the AC-5 literals
+ *    "Always include Y" and "Never skip Z" which #552's prior threshold missed.
+ *    Case-sensitive on purpose: matches the imperative-rule register, not
+ *    "the system always defaults to..." prose mid-paragraph.
+ */
+const EXPLICIT_PATTERNS = [
+    /\balways\b[^.]*?\bunless\b/i,
+    /\bnever\b[^.]*?\bunless\b/i,
+    /\bdefault\b[^.]*?\bwhen\b/i,
+    /^\s*Always\s+\w+/,
+    /^\s*Never\s+\w+/,
+    /^\s*Default\s+\w+/,
+];
+/**
+ * Inverse-keyword map — used by `findSurvivingInverseSymbols` to derive search
+ * terms for OLD-rule survivors inside the diff blast radius. Asymmetric on
+ * purpose: e.g. an AC asserting the NEW rule "always include spec" should
+ * search for "skip" / "exclude" / "bypass" survivors, not "always" itself.
+ *
+ * High-noise common English words (`include`, `run`, `auto`, `old`,
+ * `previous`) were pruned from this map after QA's self-dogfood pass on
+ * #552 returned 50 survivors entirely from definitional documentation —
+ * those words appear in any English prose. {@link deriveInverseTerms} also
+ * filters terms in {@link COMMON_WORDS} as defense-in-depth for future
+ * tuners.
+ */
+const INVERSE_KEYWORDS = {
+    default: ["skip", "exclude", "bypass", "override"],
+    always: ["skip", "never", "exclude", "conditional", "shortcut"],
+    never: ["always", "default", "exclude"],
+    rule: ["exception", "override", "shortcut", "bypass"],
+    behavior: ["legacy", "deprecated"],
+    skip: ["always", "default", "exclude"],
+};
+/**
+ * Roots scanned by `findTouchpoints`. Order matters when `TOTAL_CAP` is hit:
+ * earlier roots are always represented in the results. `bin/` and
+ * `src/commands/` are scanned because CLI option registration (Commander.js
+ * `.option()` chains in `bin/cli.ts`, `RunOptions` interface in
+ * `src/commands/run.ts`) is a recurring rule-drift site — see the "CLI wiring
+ * gap" pitfall called out in this project's CLAUDE.md memory. `templates/skills/`
+ * and `skills/` are intentionally omitted — they mirror `.claude/skills/` 1:1
+ * and including them would triple-count every hit.
+ */
+const TOUCHPOINT_ROOTS = ["src/lib", "src/commands", "bin", ".claude/skills"];
+const TOUCHPOINT_EXTENSIONS = [".md", ".ts", ".tsx"];
+/**
+ * Total survivor cap on `findSurvivingInverseSymbols` results. Lower than
+ * `findTouchpoints`'s total cap (200) because survivors are surfaced inside
+ * the QA verdict and a long list drowns out the rule-relevant hits — a
+ * tighter cap forces operators to triage the highest-signal blast-radius
+ * lines first.
+ */
+const SURVIVOR_TOTAL_CAP = 50;
+/** Skip these directories when walking — they explode the corpus without value. */
+const WALK_SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    ".next",
+    "coverage",
+    "__tests__",
+    "__snapshots__",
+]);
+/**
+ * Detect whether an AC describes a behavior rule.
+ *
+ * Trigger conditions:
+ * 1. ≥2 distinct {@link BEHAVIOR_KEYWORDS} present in the AC description
+ *    (case-insensitive, word-boundary match), OR
+ * 2. Description matches one of the {@link EXPLICIT_PATTERNS}
+ *    (e.g. "always X unless Y").
+ *
+ * Returns `triggered: false` for empty or undefined descriptions, single
+ * keyword matches without an explicit pattern, and file-specific ACs
+ * ("Update line 42 of foo.ts").
+ */
+export function detectBehaviorRule(ac) {
+    const description = ac?.description ?? "";
+    if (!description) {
+        return { triggered: false, keywords: [] };
+    }
+    const matched = new Set();
+    for (const kw of BEHAVIOR_KEYWORDS) {
+        if (KEYWORD_REGEXES[kw].test(description))
+            matched.add(kw);
+    }
+    // Explicit pattern overrides the ≥2-keyword threshold (e.g. "always X
+    // unless Y" only contains one keyword but is unambiguously a behavior rule).
+    for (const re of EXPLICIT_PATTERNS) {
+        if (re.test(description)) {
+            return {
+                triggered: true,
+                keywords: [...matched],
+                matchedPattern: re.source,
+            };
+        }
+    }
+    return {
+        triggered: matched.size >= 2,
+        keywords: [...matched],
+    };
+}
+/**
+ * Find touchpoints in the codebase that likely implement the behavior rule
+ * described by `ac`. Returns `[]` when {@link detectBehaviorRule} does not
+ * trigger (cheap short-circuit per the /spec performance budget).
+ *
+ * Heuristic:
+ *  - Extract identifier-like symbols from the AC (backticked strings, file
+ *    paths with extensions, ALL_CAPS / camelCase / kebab-case identifiers).
+ *  - Walk {@link TOUCHPOINT_ROOTS}; for each line in matching files, mark a
+ *    hit if the line contains any extracted symbol OR ≥2 distinct AC
+ *    behavior keywords.
+ *  - Hits are deduplicated by `path:line` and capped (per-file: 3, total: 200)
+ *    to keep `/spec` output readable (callers can re-run with a tighter scope
+ *    if needed).
+ */
+export function findTouchpoints(ac, repoRoot) {
+    const detection = detectBehaviorRule(ac);
+    if (!detection.triggered)
+        return [];
+    if (!repoRoot || !existsSync(repoRoot))
+        return [];
+    const symbols = extractSymbols(ac.description);
+    const keywords = detection.keywords;
+    const hits = [];
+    const seen = new Set();
+    const perFileCount = new Map();
+    // Caps tuned to keep /spec output readable while ensuring breadth of
+    // coverage — a per-file ceiling prevents one chatty file from drowning out
+    // the rest of the corpus, and a total ceiling caps the worst case.
+    const PER_FILE_CAP = 3;
+    const TOTAL_CAP = 200;
+    for (const root of TOUCHPOINT_ROOTS) {
+        const fullRoot = join(repoRoot, root);
+        if (!existsSync(fullRoot))
+            continue;
+        for (const file of walkFiles(fullRoot)) {
+            if (!TOUCHPOINT_EXTENSIONS.some((ext) => file.endsWith(ext)))
+                continue;
+            // Test files implement *checks* of behavior rules, not the rules
+            // themselves. Excluding them keeps `findTouchpoints` focused on the
+            // implementation sites a /spec planner needs to enumerate.
+            if (/\.(test|spec)\.(ts|tsx|js|jsx)$/.test(file))
+                continue;
+            const content = safeReadFile(file);
+            if (!content)
+                continue;
+            const relPath = relative(repoRoot, file);
+            const lines = content.split("\n");
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i];
+                if (!matchesBehaviorSite(line, symbols, keywords))
+                    continue;
+                const key = `${relPath}:${i + 1}`;
+                if (seen.has(key))
+                    continue;
+                const count = perFileCount.get(relPath) ?? 0;
+                if (count >= PER_FILE_CAP)
+                    break;
+                seen.add(key);
+                perFileCount.set(relPath, count + 1);
+                hits.push({
+                    path: relPath,
+                    line: i + 1,
+                    snippet: line.trim().slice(0, 200),
+                });
+                if (hits.length >= TOTAL_CAP)
+                    return hits;
+            }
+        }
+    }
+    return hits;
+}
+/**
+ * Find OLD-rule survivors inside the diff blast radius. Used by `/qa` to flag
+ * an AC `NOT_MET` when the inverse of the asserted rule still has live code.
+ *
+ * Differs from {@link findTouchpoints}:
+ *  - Scope is `diffPaths` (caller is responsible for pre-expanding to 1-hop
+ *    importers when desired — this avoids embedding a TS-only importer scanner
+ *    here and keeps the function language-agnostic).
+ *  - Search terms are *inverse* keywords derived from the AC's keywords (and
+ *    inverse English phrasing as a fallback when no symbols match).
+ */
+export function findSurvivingInverseSymbols(ac, repoRoot, diffPaths) {
+    const detection = detectBehaviorRule(ac);
+    if (!detection.triggered)
+        return [];
+    if (!repoRoot || !existsSync(repoRoot))
+        return [];
+    if (!Array.isArray(diffPaths) || diffPaths.length === 0)
+        return [];
+    const inverseTerms = deriveInverseTerms(detection.keywords);
+    if (inverseTerms.length === 0)
+        return [];
+    const hits = [];
+    const seen = new Set();
+    for (const relPath of diffPaths) {
+        if (!relPath)
+            continue;
+        const fullPath = join(repoRoot, relPath);
+        if (!existsSync(fullPath))
+            continue;
+        let stat;
+        try {
+            stat = statSync(fullPath);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        if (!TOUCHPOINT_EXTENSIONS.some((ext) => fullPath.endsWith(ext)))
+            continue;
+        const content = safeReadFile(fullPath);
+        if (!content)
+            continue;
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (!matchesAnyTerm(line, inverseTerms))
+                continue;
+            const key = `${relPath}:${i + 1}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            hits.push({
+                path: relPath,
+                line: i + 1,
+                snippet: line.trim().slice(0, 200),
+            });
+            if (hits.length >= SURVIVOR_TOTAL_CAP)
+                return hits;
+        }
+    }
+    return hits;
+}
+// ---------- helpers ----------
+const SYMBOL_REGEXES = [
+    /`([^`\n]+)`/g, //                backtick-quoted: `spec`, `BUG_LABELS`
+    /"([^"\n]{3,})"/g, //             double-quoted phrase
+    /\*\*([^*\n]+)\*\*/g, //          bold: **always X unless Y**
+    /\b([A-Z][A-Z0-9_]{2,})\b/g, //   SCREAMING_SNAKE: BUG_LABELS, DOCS_LABELS
+    /\b([a-z][A-Za-z0-9]+(?:[A-Z][A-Za-z0-9]+){1,})\b/g, // camelCase
+    /([a-zA-Z][\w-]*\.(?:ts|tsx|js|jsx|md|json))/g, // file paths
+    /([a-z][\w-]+\/[\w./-]+)/g, //    directory paths: src/lib/...
+];
+function extractSymbols(text) {
+    if (!text)
+        return [];
+    const out = new Set();
+    for (const re of SYMBOL_REGEXES) {
+        const r = new RegExp(re.source, re.flags);
+        let m;
+        while ((m = r.exec(text)) !== null) {
+            const sym = (m[1] || "").trim();
+            // Reject common English words and very short tokens.
+            if (sym.length < 3)
+                continue;
+            if (BEHAVIOR_KEYWORDS.includes(sym.toLowerCase()))
+                continue;
+            if (COMMON_WORDS.has(sym.toLowerCase()))
+                continue;
+            out.add(sym);
+        }
+    }
+    return [...out];
+}
+const COMMON_WORDS = new Set([
+    "the",
+    "and",
+    "for",
+    "with",
+    "from",
+    "this",
+    "that",
+    "into",
+    "when",
+    "then",
+    "than",
+    "given",
+    "should",
+    "becomes",
+    "include",
+    "exists",
+    "true",
+    "false",
+    "not",
+    "yes",
+    "no",
+    "are",
+    "was",
+    "but",
+    "out",
+    "all",
+    "any",
+    "use",
+    "via",
+    "etc",
+    "issue",
+    "code",
+    "line",
+    "ok",
+]);
+function matchesBehaviorSite(line, symbols, keywords) {
+    if (!line.trim())
+        return false;
+    for (const sym of symbols) {
+        if (line.includes(sym))
+            return true;
+    }
+    let count = 0;
+    for (const kw of keywords) {
+        if (KEYWORD_REGEXES[kw].test(line)) {
+            count++;
+            if (count >= 2)
+                return true;
+        }
+    }
+    return false;
+}
+function matchesAnyTerm(line, terms) {
+    if (!line.trim())
+        return false;
+    for (const t of terms) {
+        if (!t)
+            continue;
+        if (new RegExp(`\\b${escapeRegex(t)}\\b`, "i").test(line))
+            return true;
+    }
+    return false;
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function deriveInverseTerms(keywords) {
+    const out = new Set();
+    for (const k of keywords) {
+        for (const inv of INVERSE_KEYWORDS[k] ?? []) {
+            // Defense-in-depth: drop any inverse term that's a common English
+            // word, even if a future tuner adds it to INVERSE_KEYWORDS. Common
+            // words produce false-positive survivors on every prose line.
+            if (COMMON_WORDS.has(inv.toLowerCase()))
+                continue;
+            out.add(inv);
+        }
+    }
+    return [...out];
+}
+function safeReadFile(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function* walkFiles(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (WALK_SKIP_DIRS.has(entry))
+            continue;
+        const full = join(dir, entry);
+        let stat;
+        try {
+            stat = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            yield* walkFiles(full);
+        }
+        else if (stat.isFile()) {
+            yield full;
+        }
+    }
+}

package/dist/src/lib/locks/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Public surface for the issue-level concurrency lock (#625).
+ */
+export { LockManager, classifyStaleness, defaultIsPidAlive, formatLockedMessage, isOrchestratorMode, resolveLocksDir, } from "./lock-manager.js";
+export type { LockManagerOptions } from "./lock-manager.js";
+export { DEFAULT_LOCKS_DIR, DEFAULT_STALE_AGE_MS, LockFileSchema, } from "./types.js";
+export type { AcquireResult, LockFile, LockListing, SignalOtherResult, SignalReason, } from "./types.js";

package/dist/src/lib/locks/index.js

@@ -0,0 +1,5 @@
+/**
+ * Public surface for the issue-level concurrency lock (#625).
+ */
+export { LockManager, classifyStaleness, defaultIsPidAlive, formatLockedMessage, isOrchestratorMode, resolveLocksDir, } from "./lock-manager.js";
+export { DEFAULT_LOCKS_DIR, DEFAULT_STALE_AGE_MS, LockFileSchema, } from "./types.js";

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

@@ -0,0 +1,168 @@
+/**
+ * LockManager — per-issue filesystem lock to prevent concurrent sequant
+ * sessions from targeting the same issue (#625).
+ *
+ * Each lock is a single file at `<locksDir>/<issue>.lock`, claimed via
+ * `open(O_CREAT|O_EXCL)`. A separate file (rather than a field inside
+ * `state.json`) keeps acquisition atomic — no read-modify-write race.
+ *
+ * Stale detection (in order):
+ *   1. `hostname === os.hostname()`: check `process.kill(pid, 0)`.
+ *      Not alive → cleared.
+ *   2. Cross-host: PID check is meaningless. Use age only.
+ *   3. Age fallback (any host): `startedAt > staleAgeMs ago` → cleared.
+ *
+ * MCP / orchestrator mode: when `SEQUANT_ORCHESTRATOR` is set, every public
+ * method is a no-op (no fs touches, no warnings). Mirrors the
+ * `OrchestratorRenderer` pattern at `src/lib/cli-ui/run-renderer.ts:244`.
+ */
+import { type AcquireResult, type LockFile, type LockListing, type SignalOtherResult } from "./types.js";
+export interface LockManagerOptions {
+    /** Directory holding `<issue>.lock` files (default: `.sequant/locks`). */
+    locksDir?: string;
+    /**
+     * Age cutoff (ms) before a cross-host lock is considered stale by time.
+     * Default 2h. Does NOT apply to skill-shell locks — see `skillLockTtlMs`.
+     */
+    staleAgeMs?: number;
+    /**
+     * Age cutoff (ms) for skill-shell locks (`skipPidCheck: true`). Default 6h.
+     * Longer than `staleAgeMs` because skill shells can't refresh PID liveness;
+     * the lock has to bridge long /fullsolve runs with multi-iteration QA loops.
+     */
+    skillLockTtlMs?: 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;
+}
+/** Detect orchestrator mode purely from env (no caching) so tests can mutate. */
+export declare function isOrchestratorMode(): boolean;
+/** Resolve the locks directory honoring `SEQUANT_LOCKS_DIR` for test isolation. */
+export declare function resolveLocksDir(explicit?: string): string;
+/**
+ * Resolve `SEQUANT_SKILL_LOCK_TTL_MS` (milliseconds) — env override for the
+ * skill-shell lock TTL. Returns `null` when unset or unparseable so the
+ * caller can fall back to the constructor option / default.
+ */
+export declare function resolveSkillLockTtlMs(): number | null;
+/** Default same-host PID check. `process.kill(pid, 0)` throws if not alive. */
+export declare function defaultIsPidAlive(pid: number): boolean;
+/** Build the canonical "issue is in use" error message (AC: error format). */
+export declare function formatLockedMessage(issue: number, holder: LockFile): string;
+/**
+ * Decide whether a lock should be treated as stale.
+ * Pure function: no I/O. Returns `null` if the lock is fresh.
+ */
+export declare function classifyStaleness(args: {
+    holder: LockFile;
+    myHostname: string;
+    now: number;
+    staleAgeMs: number;
+    /** TTL for skill-shell (skipPidCheck) locks; falls back to staleAgeMs. */
+    skillLockTtlMs?: number;
+    isPidAlive: (pid: number) => boolean;
+}): "pid-dead" | "age-exceeded" | null;
+export declare class LockManager {
+    private readonly locksDir;
+    private readonly staleAgeMs;
+    private readonly skillLockTtlMs;
+    private readonly orchestratorMode;
+    private readonly hostname;
+    private readonly pid;
+    private readonly isPidAlive;
+    private readonly now;
+    /** Issues this instance has claimed and not yet released. */
+    private readonly held;
+    constructor(options?: LockManagerOptions);
+    /** True if all operations are no-ops (orchestrator/MCP mode). */
+    get isNoop(): boolean;
+    /** Absolute path to the locks directory. */
+    getLocksDir(): string;
+    /** Path to the lock file for a given issue. */
+    lockPathFor(issue: number): string;
+    /**
+     * Try to acquire the lock for `issue`. Returns a discriminated union.
+     *
+     * Behavior:
+     *   - Same-host stale (PID dead): silently cleared, then acquired.
+     *   - Cross-host within age window: blocked.
+     *   - Cross-host beyond `staleAgeMs`: silently cleared, then acquired.
+     *   - Orchestrator mode: returns `{ acquired: true, lockPath: '' }` no-op.
+     *
+     * `options.skipPidCheck` marks the lock so future stale checks skip the
+     * same-host PID probe and fall back to age-only — used for skill shells
+     * whose Node PID dies between acquire and release.
+     */
+    acquire(issue: number, command: string, options?: {
+        skipPidCheck?: boolean;
+    }): AcquireResult;
+    /**
+     * Take over the lock unconditionally (writes a new lock). Used by --force.
+     * Does NOT signal the prior PID — caller invokes `signal()` separately
+     * to opt in to that behavior (AC: --force does NOT signal).
+     */
+    forceAcquire(issue: number, command: string, options?: {
+        skipPidCheck?: boolean;
+    }): {
+        lockPath: string;
+        previous: LockFile | null;
+    };
+    /**
+     * SIGTERM the prior PID iff it is alive on this host. The `reason` discriminator
+     * lets callers produce accurate log lines for each refusal branch (#637).
+     * No-op in orchestrator mode or for cross-host holders.
+     */
+    signalOther(holder: LockFile, signal?: NodeJS.Signals): SignalOtherResult;
+    /**
+     * Release the lock for `issue` if this process is its holder.
+     * Safe to call repeatedly; safe to call when no lock exists.
+     */
+    release(issue: number): void;
+    /**
+     * Release a lock claimed by a previous, now-dead, short-lived process on
+     * the same host — the skill-shell pattern (`skipPidCheck: true`). Used by
+     * `sequant locks release` to let skills hand back ownership. Returns
+     * `true` when a lock was removed.
+     */
+    releaseExternal(issue: number): boolean;
+    /** Release every lock this instance holds. */
+    releaseAll(): void;
+    /**
+     * Read the holder for `issue` without acquiring. Returns null when missing
+     * or unparseable. Used by read-only commands (`status`, `merge`, `assess`).
+     */
+    check(issue: number): LockFile | null;
+    /** List every active lock with computed staleness metadata. */
+    list(): LockListing[];
+    /**
+     * Manually clear a lock. Used by `sequant locks clear`. Returns true if a
+     * lock was removed. With `safetyCheck` (default), refuses to clear a
+     * fresh same-host lock whose PID is alive — the caller should use
+     * `--force` semantics for that.
+     */
+    clearLock(issue: number, options?: {
+        safetyCheck?: boolean;
+    }): {
+        cleared: boolean;
+        reason: string;
+    };
+    private ensureLocksDir;
+    /**
+     * Write a new lock atomically using `O_CREAT | O_EXCL`. Races safely:
+     * if another process wins, returns `{ acquired: false }` with the winner.
+     */
+    private writeAtomic;
+    private readLockSafe;
+    private unlinkSafe;
+    /** True iff the lock file at `path` is missing (test helper). */
+    static missing(path: string): boolean;
+    /** Stat helper for tests — returns mtime or null. */
+    static mtime(path: string): Date | null;
+}