sequant 2.2.0 → 2.4.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.4.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.4.0",
   "author": {
     "name": "sequant-io",
     "email": "hello@sequant.io"

package/README.md

@@ -9,13 +9,16 @@ Solve GitHub issues with structured phases and quality gates — from issue to m
 [![npm version](https://img.shields.io/npm/v/sequant.svg)](https://www.npmjs.com/package/sequant)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-### What's new in 2.0
+### What's new in 2.x
 
 - **MCP server** — `sequant serve` exposes workflow orchestration as MCP tools (`sequant_run`, `sequant_status`, `sequant_logs`). Any MCP client can drive Sequant headlessly.
 - **`/assess` unification** — `/solve` is merged into `/assess` with a 6-action vocabulary (PROCEED, CLOSE, MERGE, REWRITE, CLARIFY, PARK). `/solve` still works as an alias.
-- **Parallel execution** — multi-issue runs are concurrent by default with `--concurrency`.
-- **Multi-agent** — `--agent aider` as an alternative backend, with a driver interface for future agents.
-- **GitHub Actions** — label-triggered and comment-triggered CI workflows out of the box.
+- **Parallel execution with per-issue locks** — multi-issue runs are concurrent by default (`--concurrency`); `.sequant/locks/` prevents two sessions from clobbering the same issue.
+- **Stacked PRs** — `sequant run --stacked` chains issue PRs onto their predecessor branch so reviewers see the incremental diff per issue instead of the cumulative chain diff.
+- **Live run dashboard + cohort analytics** — unified renderer with a two-zone TTY grid (active issues + append-only events log); `sequant stats --label <name> --since YYYY-MM-DD` filters runs for measuring feature- or class-specific success rates.
+- **Interactive relay** — `sequant prompt <issue> "<message>"` sends queries or directives into a running headless `sequant run`, and `sequant watch <issue>` tails the replies. Bidirectional communication with detached and CI-driven sessions.
+- **Worktree isolation for parallel agents** — `sequant run --isolate-parallel` gives each parallel `/exec` agent group its own sub-worktree with merge-back via `git merge --no-ff`, eliminating file conflicts between concurrent agents structurally rather than by convention.
+- **GitHub Actions & multi-agent backends** — label-triggered and comment-triggered CI workflows out of the box; `--agent aider` for non-Claude-Code execution.
 
 Upgrading from v1.x? See the [migration guide](CHANGELOG.md#migration-from-v1x).
 
@@ -71,7 +74,7 @@ Or step-by-step:
 - Git (for worktree-based isolation)
 
 **For npm installation:**
-- Node.js 20+
+- Node.js 22.12+
 
 **Optional MCP servers (enhanced features):**
 - `chrome-devtools` — enables `/test` for browser-based UI testing
@@ -207,14 +210,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

@@ -4,13 +4,13 @@
  *
  * Sequential AI phases with quality gates for any codebase.
  */
-import { Command } from "commander";
+import { Command, InvalidArgumentError } from "commander";
 import chalk from "chalk";
 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,7 +47,32 @@ 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 { abortCommand } from "../src/commands/abort.js";
 import { getManifest } from "../src/lib/manifest.js";
+import { phaseRegistry } from "../src/lib/workflow/phase-registry.js";
+/**
+ * Validate `--phases` argument against the phase registry.
+ *
+ * Splits a comma-separated phase list, checks each name against
+ * `phaseRegistry`, and exits with a clear error message if any phase
+ * is unknown. Returns the original string unchanged so downstream
+ * `RunOptions.phases` parsing in `config-resolver.ts` is undisturbed.
+ */
+function validatePhasesFlag(value) {
+    const names = value
+        .split(",")
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0);
+    const unknown = names.filter((n) => !phaseRegistry.has(n));
+    if (unknown.length > 0) {
+        const available = phaseRegistry.names().join(", ");
+        throw new InvalidArgumentError(`Unknown phase '${unknown[0]}'. Available: ${available}`);
+    }
+    return value;
+}
 const program = new Command();
 // Handle --no-color before parsing
 if (process.argv.includes("--no-color")) {
@@ -62,13 +87,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 +138,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")
@@ -128,7 +163,7 @@ program
     .command("run")
     .description("Execute workflow for GitHub issues using Claude Agent SDK")
     .argument("[issues...]", "Issue numbers to process")
-    .option("--phases <list>", "Phases to run (default: spec,exec,qa)")
+    .option("--phases <list>", "Phases to run (default: spec,exec,qa)", validatePhasesFlag)
     .option("--sequential", "Stop on first issue failure (default: continue)")
     .option("-d, --dry-run", "Preview without execution")
     .option("-v, --verbose", "Verbose output with streaming")
@@ -136,14 +171,16 @@ program
     .option("--log-json", "Enable structured JSON logging (default: true)")
     .option("--no-log", "Disable JSON logging for this run")
     .option("--log-path <path>", "Custom log directory path")
-    .option("-q, --quality-loop", "Enable quality loop with auto-retry")
+    .option("-Q, --quality-loop", "Enable quality loop with auto-retry")
     .option("--max-iterations <n>", "Max iterations for quality loop (default: 3)", parseInt)
     .option("--batch <issues>", 'Group of issues to run together (e.g., --batch "1 2" --batch "3")', (value, prev) => prev.concat([value]), [])
     .option("--smart-tests", "Enable smart test detection (default)")
     .option("--no-smart-tests", "Disable smart test detection")
     .option("--testgen", "Run testgen phase after spec")
-    .option("--quiet", "Suppress version warnings and non-essential output")
+    .option("--security-review", "Run security-review phase after spec")
+    .option("-q, --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 +188,61 @@ 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("--wait <seconds>", "Block until a reply arrives or the timeout elapses (#645, Gap 4)", parseInt)
+    .option("--json", "Output as JSON")
+    .action((args, options) => {
+    return promptCommand({
+        args,
+        options: {
+            type: options.type,
+            waitSeconds: typeof options.wait === "number" ? options.wait : undefined,
+            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("abort")
+    .description("Out-of-band abort: signal a running sequant session directly (#645)")
+    .argument("[issue]", "Issue number (auto-resolved when a single run is active)")
+    .option("--force", "Skip the SIGINT grace period; SIGTERM immediately")
+    .option("--grace <seconds>", "Seconds to wait after SIGINT before escalating (default: 10)", parseInt)
+    .option("--json", "Output as JSON")
+    .action((issueArg, options) => {
+    const args = issueArg === undefined ? [] : [issueArg];
+    return abortCommand({
+        args,
+        options: {
+            force: Boolean(options.force),
+            graceSeconds: typeof options.grace === "number" ? options.grace : undefined,
+            json: Boolean(options.json),
+        },
+    });
+});
 program
     .command("merge")
     .description("Batch-level integration QA — verify feature branches before merging")
@@ -195,6 +281,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 +332,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/abort.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `sequant abort <issue>` — out-of-band escape hatch for a running headless
+ * session (#645, Gap 7).
+ *
+ * `sequant prompt --type abort` queues an abort message into the inbox, which
+ * the agent must read via the PostToolUse hook chain. When that chain is
+ * broken (the bug originally reported in #645), no in-band abort can land.
+ *
+ * This command bypasses the inbox entirely: it locates the orchestrator PID
+ * via `state.json.relay.pid` (with the per-issue pidfile as fallback) and
+ * sends signals directly. The receiving end is the existing ShutdownManager
+ * in `sequant run`, which already performs a clean teardown on SIGINT/SIGTERM.
+ */
+export interface AbortCommandOptions {
+    /** Skip the SIGINT grace period; SIGTERM immediately. */
+    force?: boolean;
+    /** Seconds to wait after SIGINT before escalating. Default 10. */
+    graceSeconds?: number;
+    json?: boolean;
+    /** Test seam: override the system kill function. */
+    killFn?: (pid: number, signal: NodeJS.Signals) => void;
+    /** Test seam: override the liveness check. */
+    isAlive?: (pid: number) => boolean;
+    /** Test seam: override the poll interval (ms). Default 250. */
+    pollIntervalMs?: number;
+    /** Test seam: override SIGTERM grace before SIGKILL (ms). Default 3000. */
+    sigtermTimeoutMs?: number;
+    /** Test seam: override SIGKILL final wait (ms). Default 2000. */
+    sigkillTimeoutMs?: number;
+    /** Test seam: override cwd for pidfile resolution. */
+    cwd?: string;
+}
+export declare function abortCommand(argsAndOptions: {
+    args: string[];
+    options: AbortCommandOptions;
+}): Promise<void>;

package/dist/src/commands/abort.js

@@ -0,0 +1,138 @@
+/**
+ * `sequant abort <issue>` — out-of-band escape hatch for a running headless
+ * session (#645, Gap 7).
+ *
+ * `sequant prompt --type abort` queues an abort message into the inbox, which
+ * the agent must read via the PostToolUse hook chain. When that chain is
+ * broken (the bug originally reported in #645), no in-band abort can land.
+ *
+ * This command bypasses the inbox entirely: it locates the orchestrator PID
+ * via `state.json.relay.pid` (with the per-issue pidfile as fallback) and
+ * sends signals directly. The receiving end is the existing ShutdownManager
+ * in `sequant run`, which already performs a clean teardown on SIGINT/SIGTERM.
+ */
+import chalk from "chalk";
+import { isPidAlive, readPidFile } from "../lib/relay/pid.js";
+import { StateManager } from "../lib/workflow/state-manager.js";
+import { findActiveIssues, resolveTargetIssue } from "./prompt.js";
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Send `signal` and wait up to `timeoutMs` for the PID to exit. Returns true
+ * if the process died, false if still alive at the deadline.
+ */
+async function signalAndWait(pid, signal, timeoutMs, isAlive, killFn, pollIntervalMs) {
+    try {
+        killFn(pid, signal);
+    }
+    catch {
+        // ESRCH (process already dead) → success.
+        if (!isAlive(pid))
+            return true;
+        throw new Error(`Failed to send ${signal} to PID ${pid} (signal not delivered)`);
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!isAlive(pid))
+            return true;
+        await delay(pollIntervalMs);
+    }
+    return !isAlive(pid);
+}
+export async function abortCommand(argsAndOptions) {
+    const { args, options } = argsAndOptions;
+    const json = Boolean(options.json);
+    const killFn = options.killFn ??
+        ((pid, signal) => {
+            process.kill(pid, signal);
+        });
+    const isAlive = options.isAlive ?? isPidAlive;
+    const pollIntervalMs = options.pollIntervalMs ?? 250;
+    const cwd = options.cwd ?? process.cwd();
+    // Resolve target issue: explicit arg or single-active auto-resolve.
+    const stateManager = new StateManager();
+    let issueNumber;
+    const issueArg = args[0];
+    if (issueArg !== undefined) {
+        const n = Number.parseInt(issueArg, 10);
+        if (!Number.isInteger(n) || n <= 0) {
+            throw new Error(`Invalid issue number: '${issueArg}'`);
+        }
+        issueNumber = n;
+    }
+    else {
+        const all = stateManager.stateExists()
+            ? Object.values(await stateManager.getAllIssueStates())
+            : [];
+        const active = findActiveIssues(all, isAlive, cwd);
+        const target = resolveTargetIssue({ explicit: null, activeIssues: active });
+        issueNumber = target.issue;
+    }
+    const issueState = await stateManager.getIssueState(issueNumber);
+    const pid = issueState?.relay?.pid ?? readPidFile(issueNumber, cwd) ?? null;
+    if (pid === null) {
+        const msg = `No relay PID found for #${issueNumber}. Is the run active?`;
+        if (json) {
+            console.log(JSON.stringify({ ok: false, issue: issueNumber, error: msg }));
+        }
+        else {
+            console.error(chalk.yellow(msg));
+        }
+        process.exitCode = 1;
+        return;
+    }
+    if (!isAlive(pid)) {
+        const msg = `PID ${pid} for #${issueNumber} is already dead.`;
+        if (json) {
+            console.log(JSON.stringify({ ok: true, issue: issueNumber, pid, signal: null }));
+        }
+        else {
+            console.log(chalk.gray(msg));
+        }
+        return;
+    }
+    const graceMs = Math.max(0, (options.graceSeconds ?? 10) * 1000);
+    const force = Boolean(options.force);
+    let delivered = "SIGINT";
+    let died = false;
+    if (!force) {
+        if (!json) {
+            console.log(chalk.gray(`Sending SIGINT to PID ${pid} (#${issueNumber}); waiting up to ${graceMs / 1000}s for graceful exit…`));
+        }
+        died = await signalAndWait(pid, "SIGINT", graceMs, isAlive, killFn, pollIntervalMs);
+    }
+    if (!died) {
+        delivered = "SIGTERM";
+        if (!json) {
+            console.log(chalk.yellow(force
+                ? `Sending SIGTERM to PID ${pid} (#${issueNumber}) (--force)…`
+                : `Grace expired; escalating to SIGTERM…`));
+        }
+        died = await signalAndWait(pid, "SIGTERM", options.sigtermTimeoutMs ?? 3000, isAlive, killFn, pollIntervalMs);
+    }
+    if (!died) {
+        delivered = "SIGKILL";
+        if (!json) {
+            console.log(chalk.red(`SIGTERM ignored; escalating to SIGKILL on PID ${pid}…`));
+        }
+        died = await signalAndWait(pid, "SIGKILL", options.sigkillTimeoutMs ?? 2000, isAlive, killFn, pollIntervalMs);
+    }
+    if (!died) {
+        process.exitCode = 1;
+    }
+    if (json) {
+        console.log(JSON.stringify({
+            ok: died,
+            issue: issueNumber,
+            pid,
+            signal: delivered,
+        }));
+    }
+    else if (died) {
+        console.log(chalk.green(`Aborted #${issueNumber} (PID ${pid}, ${delivered}).`));
+    }
+    else {
+        console.error(chalk.red(`Failed to abort #${issueNumber}: PID ${pid} still alive after ${delivered}.`));
+    }
+}

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;