sequant 2.2.0 → 2.3.0

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "sequant",
       "description": "Structured workflow system for Claude Code - GitHub issue resolution with spec, exec, test, and QA phases. Includes 17 skills, MCP server with workflow tools, and pre/post-tool hooks.",
-      "version": "2.2.0",
+      "version": "2.3.0",
       "author": {
         "name": "sequant-io",
         "email": "hello@sequant.io"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sequant",
   "description": "Structured workflow system for Claude Code - GitHub issue resolution with spec, exec, test, and QA phases",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "author": {
     "name": "sequant-io",
     "email": "hello@sequant.io"

package/README.md

@@ -207,14 +207,87 @@ npx sequant status            # Show version and config
 npx sequant run <issues...>   # Execute workflow
 npx sequant merge <issues...> # Batch integration QA before merging
 npx sequant state <cmd>       # Manage workflow state (init/rebuild/clean)
+npx sequant locks <cmd>       # Inspect/clear per-issue concurrency locks
 npx sequant stats             # View local workflow analytics
 npx sequant dashboard         # Launch real-time workflow dashboard
 ```
 
+Cohort filtering: `npx sequant stats --label docs --since 2026-01-01`. See [Analytics — Filtering by Label or Date](docs/reference/analytics.md#filtering-by-label-or-date) for details.
+
 See [Run Command Options](docs/reference/run-command.md), [Merge Command](docs/reference/merge-command.md), [State Command](docs/reference/state-command.md), and [Analytics](docs/reference/analytics.md) for details.
 
 ---
 
+## Concurrency
+
+Sequant prevents two sessions from working on the same GitHub issue at the
+same time. When `sequant run` starts, each issue claims a per-issue lock at
+`.sequant/locks/<issue>.lock` containing the holder's PID, hostname, start
+time, and command. A second session attempting the same issue is skipped
+with a clear error and the rest of the batch continues.
+
+**Stale recovery.** Locks are auto-cleared in three situations:
+
+1. Same host, PID no longer alive → cleared immediately (covers SIGKILL and
+   crashes).
+2. Cross-host, lock older than 2 hours → cleared by age.
+3. Manual: `sequant locks clear <issue>` (with safety check by default).
+
+**Taking over an active session.** `sequant run --force <issue>` writes a
+new lock claiming the issue. Add `--signal-other` to also SIGTERM the prior
+PID (same host, alive only). Plain `--force` does not signal — use it when
+you already know the other session is dead.
+
+**Inspecting locks.**
+
+```bash
+npx sequant locks list                # Show every active lock
+npx sequant locks clear 123           # Clear lock for #123 (refuses fresh)
+npx sequant locks clear 123 --force   # Clear unconditionally
+```
+
+**Skill wiring** (`/fullsolve`, `/assess`). The `/fullsolve` skill claims the
+lock at Phase 0.3, releases it at Phase 5.5, AND releases on every halt
+branch (spec failure, exec exhausted, etc.) so an aborted run frees the
+lock immediately. `/assess` probes it read-only and surfaces a dashboard
+warning when any issue is in use. Both use these subcommands directly from
+bash:
+
+```bash
+npx sequant locks acquire 123 --command="/fullsolve 123" --skip-pid-check
+npx sequant locks release 123                    # idempotent; safe on every error path
+npx sequant locks check   123 --json             # exit 1 when held, prints holder JSON
+npx sequant locks check-batch 100 101 102        # /assess: emits ⚠ lines for held issues only
+```
+
+`--skip-pid-check` is required for skill shells: the Node process that runs
+`locks acquire` exits immediately, so its PID is dead before the lock is
+released. With the flag set, stale detection falls back to age-only on the
+holder's own host. The default skill-lock TTL is **6h** (separate from the
+2h cross-host TTL) — long enough to cover virtually every `/fullsolve` run
+including multi-iteration QA loops. Override per-process via
+`SEQUANT_SKILL_LOCK_TTL_MS=<milliseconds>`.
+
+A skill that crashes mid-run leaves at most a 6h orphan; clear it manually
+with `sequant locks clear <issue>` to recover sooner. The skill's explicit
+release calls on every halt branch (see `.claude/skills/fullsolve/SKILL.md`
+Phase 0.3 release contract) mean this corner case should be rare in practice.
+
+**Read-only commands** (`status`, `merge`, `/assess`) warn when an issue is
+locked but do not block.
+
+**MCP / orchestrator mode.** When the `SEQUANT_ORCHESTRATOR` env var is set
+(in-process or remote MCP-driven runs), all lock operations are no-ops —
+the orchestrator caller is responsible for any coordination.
+
+**Caveats.** The lock relies on `open(O_CREAT | O_EXCL)` and is reliable on
+local filesystems. NFS and other network filesystems may not honor those
+semantics; users on networked repos may see false positives. The
+`SEQUANT_LOCKS_DIR` env var overrides the lock directory (used in tests
+and unusual layouts).
+
+---
+
 ## Configuration
 
 ```json

package/dist/bin/cli.js

@@ -10,7 +10,7 @@ import { fileURLToPath } from "url";
 import { dirname, resolve } from "path";
 import { readFileSync } from "fs";
 import { initCommand } from "../src/commands/init.js";
-import { isLocalNodeModulesInstall } from "../src/lib/version-check.js";
+import { buildHomeStrayWarning, getInstallRoot, isHomeStrayInstall, isLocalNodeModulesInstall, } from "../src/lib/version-check.js";
 import { configureUI, banner } from "../src/lib/cli-ui.js";
 import { isCI, isStdoutTTY } from "../src/lib/tty.js";
 import { detectPackageManagerSync, getPackageManagerCommands, } from "../src/lib/stacks.js";
@@ -47,6 +47,9 @@ import { stateInitCommand, stateRebuildCommand, stateCleanCommand, } from "../sr
 import { syncCommand, areSkillsOutdated } from "../src/commands/sync.js";
 import { mergeCommand } from "../src/commands/merge.js";
 import { conventionsCommand } from "../src/commands/conventions.js";
+import { locksListCommand, locksClearCommand, locksAcquireCommand, locksReleaseCommand, locksCheckCommand, locksCheckBatchCommand, } from "../src/commands/locks.js";
+import { promptCommand } from "../src/commands/prompt.js";
+import { watchCommand } from "../src/commands/watch.js";
 import { getManifest } from "../src/lib/manifest.js";
 const program = new Command();
 // Handle --no-color before parsing
@@ -62,13 +65,22 @@ configureUI({
     isCI: isCI(),
     minimal: process.env.SEQUANT_MINIMAL === "1",
 });
-// Warn if running from local node_modules (not npx cache or global)
-// This helps users who accidentally have a stale local install
-if (!process.argv.includes("--quiet") && isLocalNodeModulesInstall()) {
-    const pmCommands = getPackageManagerCommands(detectPackageManagerSync());
-    console.warn(chalk.yellow("!  Running sequant from local node_modules\n" +
-        "   For latest version: npx sequant@latest\n" +
-        `   To remove local: ${pmCommands.removePkg} sequant\n`));
+// Warn if running from a problematic install location.
+// The home-stray case ($HOME/node_modules/sequant) gets a distinct warning
+// because it pollutes resolution for every subdirectory of $HOME, which the
+// generic "local node_modules" message doesn't communicate. Resolve the
+// install root once and pass it to both predicates to avoid a second walk.
+if (!process.argv.includes("--quiet")) {
+    const installRoot = getInstallRoot();
+    if (installRoot && isHomeStrayInstall(installRoot)) {
+        console.warn(chalk.yellow(buildHomeStrayWarning(installRoot)));
+    }
+    else if (isLocalNodeModulesInstall()) {
+        const pmCommands = getPackageManagerCommands(detectPackageManagerSync());
+        console.warn(chalk.yellow("!  Running sequant from local node_modules\n" +
+            "   For latest version: npx sequant@latest\n" +
+            `   To remove local: ${pmCommands.removePkg} sequant\n`));
+    }
 }
 program
     .name("sequant")
@@ -104,6 +116,7 @@ program
     .command("doctor")
     .description("Check your Sequant installation for issues")
     .option("--skip-issue-check", "Skip closed-issue verification check")
+    .option("-q, --quiet", "Suppress informational warnings")
     .action(doctorCommand);
 program
     .command("status")
@@ -142,8 +155,10 @@ program
     .option("--smart-tests", "Enable smart test detection (default)")
     .option("--no-smart-tests", "Disable smart test detection")
     .option("--testgen", "Run testgen phase after spec")
+    .option("--security-review", "Run security-review phase after spec")
     .option("--quiet", "Suppress version warnings and non-essential output")
     .option("--chain", "Chain issues: each branches from previous (implies --sequential)")
+    .option("--stacked", "Stack PRs: middle PRs target predecessor branch instead of main; first/last target main (implies --chain)")
     .option("--qa-gate", "Wait for QA pass before starting next issue in chain (requires --chain)")
     .option("--base <branch>", "Base branch for worktree creation (default: main or settings.run.defaultBase)")
     .option("--no-mcp", "Disable MCP server injection in headless mode")
@@ -151,12 +166,41 @@ program
     .option("--resume", "Resume from last completed phase (reads phase markers from GitHub)")
     .option("--no-rebase", "Skip pre-PR rebase onto origin/main (use when you want to handle rebasing manually)")
     .option("--no-pr", "Skip PR creation after successful QA (manual PR workflow)")
-    .option("-f, --force", "Force re-execution of completed issues (bypass pre-flight state guard)")
+    .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)", parseInt)
     .option("--isolate-parallel", "Isolate parallel agent groups in separate worktrees (prevents file conflicts)")
     .option("--reflect", "Analyze run results and suggest improvements")
     .option("--agent <name>", 'Agent driver for phase execution (default: "claude-code")')
+    .option("--experimental-tui", "Render live multi-issue dashboard (requires TTY; falls back to linear output when piped)")
+    .option("--no-relay", "Disable interactive relay (#383); `sequant prompt` cannot reach this run")
     .action(runCommand);
+program
+    .command("prompt")
+    .description("Send a message into a running headless sequant session (#383)")
+    .argument("[args...]", '[<issue>] "<message>"')
+    .option("--type <type>", "Message type: query (default), directive, abort", "query")
+    .option("--json", "Output as JSON")
+    .action((args, options) => {
+    return promptCommand({
+        args,
+        options: {
+            type: options.type,
+            json: Boolean(options.json),
+        },
+    });
+});
+program
+    .command("watch")
+    .description("Tail the relay outbox for replies from a running sequant session (#383)")
+    .argument("<issue>", "Issue number to watch")
+    .option("--json", "Output as JSON lines")
+    .action((issueArg, options) => {
+    return watchCommand({
+        args: [issueArg],
+        options: { json: Boolean(options.json) },
+    });
+});
 program
     .command("merge")
     .description("Batch-level integration QA — verify feature branches before merging")
@@ -195,6 +239,8 @@ program
     .option("--csv", "Output as CSV")
     .option("--json", "Output as JSON")
     .option("--detailed", "Show detailed analytics (QA verdicts, trends, label segmentation)")
+    .option("--label <name>", "Filter to runs whose issues carry the given label")
+    .option("--since <date>", "Filter to runs with startTime on/after YYYY-MM-DD (UTC)")
     .action(statsCommand);
 program
     .command("dashboard")
@@ -244,6 +290,45 @@ stateCmd
     .option("--max-age <days>", "Remove entries older than N days", parseInt)
     .option("--all", "Remove all orphaned entries (merged and abandoned)")
     .action(stateCleanCommand);
+// Per-issue concurrency locks (#625)
+const locksCmd = program
+    .command("locks")
+    .description("Inspect and clear per-issue concurrency locks");
+locksCmd
+    .command("list")
+    .description("List active locks with staleness metadata")
+    .option("--json", "Output as JSON")
+    .action(locksListCommand);
+locksCmd
+    .command("clear <issue>")
+    .description("Manually clear the lock for an issue (safety check unless --force)")
+    .option("-f, --force", "Skip safety check; clear even a fresh same-host alive lock")
+    .option("--json", "Output as JSON")
+    .action(locksClearCommand);
+locksCmd
+    .command("acquire <issue>")
+    .description("Claim the lock for an issue (used by /fullsolve, /assess; exits 1 if held)")
+    .option("--command <command>", "Human-readable command label", "unknown")
+    .option("--skip-pid-check", "Mark the lock so stale recovery skips same-host PID checks (use from skill shells)")
+    .option("-f, --force", "Take over even if another holder is alive")
+    .option("--signal-other", "When forcing, SIGTERM the prior same-host holder if alive")
+    .option("--json", "Output as JSON")
+    .action(locksAcquireCommand);
+locksCmd
+    .command("release <issue>")
+    .description("Release a lock previously acquired on this host (skill or current process)")
+    .option("--json", "Output as JSON")
+    .action(locksReleaseCommand);
+locksCmd
+    .command("check <issue>")
+    .description("Read-only probe: print lock holder if any; exit 1 when held (for /assess)")
+    .option("--json", "Output as JSON")
+    .action(locksCheckCommand);
+locksCmd
+    .command("check-batch <issues...>")
+    .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);
 // 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/src/commands/doctor.d.ts

@@ -3,7 +3,32 @@
  */
 export interface DoctorOptions {
     skipIssueCheck?: boolean;
+    /** Suppress informational warnings (e.g., upstream subagent routing notice) */
+    quiet?: boolean;
 }
+/**
+ * Upstream subagent routing bug notice (anthropics/claude-code#43869).
+ * Subagent `model:` declarations are silently ignored; agents run on the
+ * parent session's model. Exported as a constant so tests can match it.
+ */
+export declare const UPSTREAM_SUBAGENT_WARNING: {
+    readonly primary: "WARN: Claude Code #43869 — subagent model: declarations are ignored. Agents currently run on parent model.";
+    readonly url: "https://github.com/anthropics/claude-code/issues/43869";
+    readonly inertFieldNote: "Note: agents.model is currently inert (see #43869).";
+};
+/**
+ * Emit the upstream subagent-routing bug notice and (when applicable) the
+ * `agents.model` inert-field note. Honors `--quiet`.
+ *
+ * AC-2: primary line + link, suppressible via `quiet`.
+ * AC-4: when the user's `agents.model` differs from the shipped default,
+ * append a second-line note flagging the field as inert.
+ */
+export declare function emitUpstreamWarning(opts: {
+    quiet?: boolean;
+    agentsModel: string;
+    defaultAgentsModel: string;
+}): void;
 interface ClosedIssue {
     number: number;
     title: string;

package/dist/src/commands/doctor.js

@@ -8,11 +8,40 @@ import { GitHubProvider } from "../lib/workflow/platforms/github.js";
 import { fileExists, isExecutable } from "../lib/fs.js";
 import { getManifest } from "../lib/manifest.js";
 import { commandExists, isGhAuthenticated, isNativeWindows, isWSL, checkOptionalMcpServers, getMcpServersConfig, OPTIONAL_MCP_SERVERS, } from "../lib/system.js";
-import { getSettings } from "../lib/settings.js";
+import { getSettings, DEFAULT_AGENT_SETTINGS } from "../lib/settings.js";
 import { checkVersionThorough, getVersionWarning, } from "../lib/version-check.js";
 import { areSkillsOutdated } from "./sync.js";
 import { readAgentsMd, checkAgentsMdConsistency, AGENTS_MD_PATH, } from "../lib/agents-md.js";
 import { readFile } from "../lib/fs.js";
+// TODO: remove when anthropics/claude-code#43869 closes
+/**
+ * Upstream subagent routing bug notice (anthropics/claude-code#43869).
+ * Subagent `model:` declarations are silently ignored; agents run on the
+ * parent session's model. Exported as a constant so tests can match it.
+ */
+export const UPSTREAM_SUBAGENT_WARNING = {
+    primary: "WARN: Claude Code #43869 — subagent model: declarations are ignored. Agents currently run on parent model.",
+    url: "https://github.com/anthropics/claude-code/issues/43869",
+    inertFieldNote: "Note: agents.model is currently inert (see #43869).",
+};
+/**
+ * Emit the upstream subagent-routing bug notice and (when applicable) the
+ * `agents.model` inert-field note. Honors `--quiet`.
+ *
+ * AC-2: primary line + link, suppressible via `quiet`.
+ * AC-4: when the user's `agents.model` differs from the shipped default,
+ * append a second-line note flagging the field as inert.
+ */
+export function emitUpstreamWarning(opts) {
+    if (opts.quiet)
+        return;
+    console.log("");
+    console.log(chalk.yellow(`  !  ${UPSTREAM_SUBAGENT_WARNING.primary}`));
+    console.log(chalk.yellow(`     ${UPSTREAM_SUBAGENT_WARNING.url}`));
+    if (opts.agentsModel !== opts.defaultAgentsModel) {
+        console.log(chalk.yellow(`     ${UPSTREAM_SUBAGENT_WARNING.inertFieldNote}`));
+    }
+}
 /**
  * Labels that indicate an issue should be skipped from closed-issue verification
  * (case-insensitive matching)
@@ -492,6 +521,12 @@ export async function doctorCommand(options = {}) {
         else
             failCount++;
     }
+    // Upstream subagent routing notice (AC-2/AC-4)
+    emitUpstreamWarning({
+        quiet: options.quiet,
+        agentsModel: settings.agents.model,
+        defaultAgentsModel: DEFAULT_AGENT_SETTINGS.model,
+    });
     // Summary with boxed output
     const totalChecks = passCount + warnCount + failCount;
     let summaryTitle;

package/dist/src/commands/locks.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `sequant locks` — inspect and clear per-issue concurrency locks (#625).
+ */
+export interface LocksListOptions {
+    json?: boolean;
+}
+export interface LocksClearOptions {
+    force?: boolean;
+    json?: boolean;
+}
+export interface LocksAcquireOptions {
+    command?: string;
+    skipPidCheck?: boolean;
+    force?: boolean;
+    signalOther?: boolean;
+    json?: boolean;
+}
+export interface LocksReleaseOptions {
+    json?: boolean;
+}
+export interface LocksCheckOptions {
+    json?: boolean;
+}
+export interface LocksCheckBatchOptions {
+    json?: boolean;
+}
+/** `sequant locks list` — print every active lock with staleness metadata. */
+export declare function locksListCommand(options?: LocksListOptions): Promise<void>;
+/**
+ * `sequant locks clear <issue>` — remove a lock manually.
+ * By default refuses to clear a fresh same-host lock whose PID is alive;
+ * pass `--force` to override.
+ */
+export declare function locksClearCommand(issueArg: string, options?: LocksClearOptions): Promise<void>;
+/**
+ * `sequant locks acquire <issue>` — claim the lock from a shell context
+ * (e.g. a skill SKILL.md). Use `--skip-pid-check` for skill shells whose
+ * Node PID dies between acquire and release; stale recovery then falls back
+ * to age-only (2h).
+ *
+ * Exit codes:
+ *   0 — acquired
+ *   1 — locked by another holder (printed to stderr unless --json)
+ *   2 — invalid arguments
+ */
+export declare function locksAcquireCommand(issueArg: string, options?: LocksAcquireOptions): Promise<void>;
+/**
+ * `sequant locks release <issue>` — release a lock previously acquired by
+ * a skill shell on this host. Refuses to release locks held by a foreign
+ * host or by a different process (use `locks clear --force` for that).
+ */
+export declare function locksReleaseCommand(issueArg: string, options?: LocksReleaseOptions): Promise<void>;
+/**
+ * `sequant locks check <issue>` — read-only lock probe for `/assess`-style
+ * skills. Prints holder info if any, exit code 0 when free, 1 when held.
+ */
+export declare function locksCheckCommand(issueArg: string, options?: LocksCheckOptions): Promise<void>;
+/**
+ * `sequant locks check-batch <issue1> <issue2> ...` — read-only batch probe
+ * used by `/assess`. Text mode emits one canonical warning line per held
+ * issue (nothing for unheld), so the skill can paste the output directly
+ * above its dashboard. JSON mode emits a structured `{ warnings: [...] }`.
+ *
+ * Exit code is always 0 — `/assess` is read-only and should never abort
+ * on locked issues; the warning is informational.
+ */
+export declare function locksCheckBatchCommand(issueArgs: string[], options?: LocksCheckBatchOptions): Promise<void>;