npm - @heretyc/subagent-mcp - Versions diffs - 2.9.2 → 2.10.0 - Mend

@heretyc/subagent-mcp 2.9.2 → 2.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md +207 -193
package/dist/concurrency.js +96 -0
package/dist/config-scaffold.js +2 -0
package/dist/global-concurrency.jsonc +29 -0
package/dist/index.js +117 -58
package/dist/setup.js +1 -0
package/package.json +2 -2

package/README.md CHANGED Viewed

@@ -1,193 +1,207 @@
-# subagent-mcp
-[![npm version](https://img.shields.io/npm/v/@heretyc/subagent-mcp?label=npm)](https://www.npmjs.com/package/@heretyc/subagent-mcp)
-[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
-[![node](https://img.shields.io/node/v/@heretyc/subagent-mcp)](https://www.npmjs.com/package/@heretyc/subagent-mcp)
-[![CI](https://github.com/Heretyc/subagent-mcp/actions/workflows/claude-routine.yml/badge.svg)](https://github.com/Heretyc/subagent-mcp/actions/workflows/claude-routine.yml)
-MCP server that launches and manages always-interactive Claude Code and Codex sub-agent sessions — on macOS, Linux, and Windows. No direct API calls. No API keys.
----
-## Install
-### Prerequisites (runtime)
-To run the published CLI you need:
-- Node.js >= 18  (`node --version`)
-- `claude` CLI — globally installed and authenticated  (`claude --version`)
-- `codex` CLI — globally installed and authenticated  (`codex --version`; optional if you only use Claude paths)
-Building from source needs additional developer tooling — see [CONTRIBUTING.md § Prerequisites](CONTRIBUTING.md#prerequisites).
-### npmjs (default)
-No authentication, no `.npmrc` configuration, and no PAT required. The package is publicly available on [npmjs.com](https://www.npmjs.com/package/@heretyc/subagent-mcp).
-```bash
-npm install -g @heretyc/subagent-mcp
-```
-**Use this path for all standard installs.**
-### GitHub Packages (org-internal pin / supply-chain auditing)
-Use this path when your organization's `.npmrc` already routes the `@heretyc` scope through GitHub Packages, when you need supply-chain audit tracing against the org-internal artifact, or when you run inside a GitHub Actions workflow whose `GITHUB_TOKEN` carries `read:packages`. Otherwise prefer npmjs above — it is simpler and needs no credentials.
-```bash
-# One-time machine setup
-echo "@heretyc:registry=https://npm.pkg.github.com" >> ~/.npmrc
-echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT" >> ~/.npmrc
-# PAT must be a classic PAT with the read:packages scope
-npm install -g @heretyc/subagent-mcp
-```
-> **Note:** GitHub Packages requires authentication even for public packages. If you see `401 Unauthorized`, verify your PAT has the `read:packages` scope and has not expired. GitHub Packages does not render a README page — the live documentation appears on [npmjs.com](https://www.npmjs.com/package/@heretyc/subagent-mcp).
----
-## Quick Start
-**1. Install** (see [Install](#install) above):
-```bash
-npm install -g @heretyc/subagent-mcp
-```
-**2. Register the MCP server + orchestration hooks:**
-```bash
-subagent-mcp setup
-```
-Installing the package only ships the binary — it does **not** auto-wire anything. `subagent-mcp setup` auto-detects Claude Code / Codex and registers the MCP server plus the per-turn orchestration-mode hooks. Preview with `subagent-mcp setup --dry-run`.
-**3. Restart your host.**
-Restart your Claude Code or Codex session so it picks up the new binary. On Codex, run `/hooks` and trust the new hook.
-**4. Initialize the orchestration invariant (recommended):**
-```bash
-subagent-mcp init --global
-```
-`init --global` writes the managed invariant block into the providers' official global user-config files — `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md` — set up once, works across every project. For a single project instead, use `subagent-mcp init --root /path/to/project` to write into that project's instruction files. `--global` and `--root` are mutually exclusive.
-For manual wiring, Gemini CLI, Claude Desktop, and developer install from source, see [docs/registration.md](docs/registration.md).
----
-## Features
-- Start Claude or Codex interactive sessions as managed sub-agents from any MCP host
-- Poll status, stream stdout/stderr tails, and enqueue follow-up messages to live sessions
-- Concurrency caps: 5 concurrent Claude + 5 concurrent Codex agents (only `processing` agents count toward the cap; `stalled` agents do not hold a slot)
-- Liveness tracking via the visible provider stream (Claude SDK events, Codex app-server JSONL): agents with no parsed visible provider stream item for 10 minutes enter `stalled` state (still alive, just quiet — thinking or awaiting a temp-file handoff), and recover to `processing` if the visible stream resumes
-- Ultracode mode for Opus 4.8 via `--settings {"ultracode":true}` — see [docs/usage.md](docs/usage.md)
-- Cross-platform exe resolution (Windows: npm-prefix .exe paths; macOS/Linux: PATH + Homebrew/usr-local fallbacks); immediate `taskkill /t /f` (Windows) / `SIGKILL` (POSIX) force-kill; no graceful shutdown period
-- stdio MCP transport; built with `@modelcontextprotocol/sdk` + `zod`
-- `orchestration-mode` tool — toggles orchestrator directives injected by bundled Claude Code / Codex hooks; Claude also gets a deterministic `PreToolUse` gate
----
-## Orchestration Mode
-**ON:** the agent operates as an orchestrator — hook injection governs each session turn, preventing inline reads or writes, and all work is delegated through sub-agent tools.
-**OFF:** the agent operates normally, with no orchestration constraints.
-Toggle with the `orchestration-mode` tool. Desktop hosts toggle the mode but receive no hook injection. See [docs/spec/dev-loop/orchestration-directive-architecture.md](docs/spec/dev-loop/orchestration-directive-architecture.md) for full semantics.
----
-## Auto Mode
-Pass `task_category` to `launch_agent` and the server picks the best provider, model, and effort for that category, with automatic fallback.
-`launch_agent` supports **auto mode**: pass `prompt` + `task_category` and the server picks the best provider/model/effort for that category from its routing table, silently falling back to the next-best candidate on any launch-time failure.
-`provider`, `model`, and `effort` are optional overrides — omit them to get the auto-selected best combination. Rules: passing `model` requires `provider`; passing `effort` requires both `provider` and `model`.
-**task_category** (required) — pick one:
-| Category | What it is |
-|---|---|
-| `math_proof` | deliverable is a proof/derivation/formally-checkable result |
-| `security_review` | security verdict, threat assessment, or demonstrated exploit |
-| `debugging` | verified fix/root-cause; requires an observed failure as precondition |
-| `quality_review` | evaluative verdict on existing artifact (review, A-vs-B, validate-vs-spec) |
-| `architecture` | cross-module design/plan, no code, no execution loop |
-| `agentic_execution` | end-state via act/observe/adapt loop (run/deploy/provision/browse) |
-| `data_analysis` | empirical finding about structured dataset (query, stat, model) |
-| `coding` | bounded runnable code artifact, one-pass (implement, test, refactor) |
-| `knowledge_synthesis` | novel integrated prose over sources (synthesize, summarize, draft) |
-| `mechanical` | deterministic single-pass transform, exact-match checkable (grep, rename, reformat) |
-| `prompt_engineering` | designed/optimized prompt or prompt-system steering an LLM/agent (composite-inferred) |
-| `vulnerability_research` | discovery + PoC of a novel vulnerability (composite-inferred) |
-| `molecular_biology` | reasoned molecular/computational-biology result over sequences, structures, or -omics data (composite-inferred) |
-| `ml_accelerator_design` | hardware/software design for ML acceleration — dataflow, kernel, roofline (composite-inferred) |
-| `fallback_default` | no category matches with confidence; prefer splitting work instead |
-The last four are **composite-inferred**: they carry no dedicated benchmark and their routing competency is composed from parent categories rather than measured directly.
-**Atomic-split guidance:** if you are unsure which category fits, do NOT submit one large amorphous task. Break the work into smaller atomic steps each mapping to a single category and launch one agent per step.
----
-## Tools
-Eight tools are exposed over the stdio MCP transport.
-| Tool | Description |
-|---|---|
-| `launch_agent` | Start a new sub-agent session with a prompt and optional task category / overrides |
-| `poll_agent` | Check status and stream tail output for a running agent |
-| `kill_agent` | Terminate a running or stalled agent |
-| `send_message` | Enqueue a message into a running agent's stdin |
-| `list_agents` | List all tracked agents and their current status |
-| `wait` | Block until a specific agent reaches a terminal state |
-| `orchestration-mode` | Toggle orchestration-mode ON/OFF; controls whether hook directives are injected into agent sessions |
-| `model-selection-mode` | Control model selection: `smart` (auto-pick) or `user-approved-overrides` (30-min override window) |
-Full parameters, return shapes, and the `alive` / `idle_seconds` / `hint` / `recent_stream` fields are in [docs/tools.md](docs/tools.md).
----
-## Agent Lifecycle
-Each agent transitions through these states:
-| Status | Meaning |
-|---|---|
-| `processing` | Driver alive with a visible provider-stream heartbeat in the last 10 minutes — actively working. Launch time counts as the initial heartbeat |
-| `stalled` | Driver STILL ALIVE but no parsed visible provider stream item for >= 10 minutes — working, thinking, or awaiting a temp-file handoff (not a failure). Recovers to `processing` if the visible stream resumes |
-| `finished` | Current turn completed, or driver exited with code 0 |
-| `errored` | Process exited with non-zero code |
-| `stopped` | Terminated by `kill_agent` |
-`processing` and `stalled` are live. `stalled` means the driver is alive but quiet (>= 10 min no visible stream); it recovers automatically and is never auto-killed — do not `kill_agent` a stalled agent. `wait` does not return on `stalled`. Full semantics: [docs/reference/status-lifecycle.md](docs/reference/status-lifecycle.md).
----
-## Documentation
-| Document | Contents |
-|---|---|
-| [docs/registration.md](docs/registration.md) | Per-platform setup: Claude Code, Codex, Gemini CLI, Claude Desktop; manual wiring; developer install from source |
-| [docs/tools.md](docs/tools.md) | Full tool reference — all eight tools, parameters, return shapes |
-| [docs/usage.md](docs/usage.md) | Model & effort matrix, ultracode mode, CLI invocations, usage examples |
-| [docs/SPEC.md](docs/SPEC.md) | Full technical specification — architecture, schemas, status lifecycle, error catalogue |
-| [docs/spec/interactive-drivers.md](docs/spec/interactive-drivers.md) | Always-interactive Claude/Codex driver model |
-| [docs/release-notes.md](docs/release-notes.md) | Operator-facing release notes |
-| [CONTRIBUTING.md](CONTRIBUTING.md) | Contributor guide — dev environment, build, test, publish |
----
-## License
-Apache-2.0 — Copyright 2026 Lexi Blackburn
-See [LICENSE](LICENSE).
+# subagent-mcp
+[![npm version](https://img.shields.io/npm/v/@heretyc/subagent-mcp?label=npm)](https://www.npmjs.com/package/@heretyc/subagent-mcp)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+[![node](https://img.shields.io/node/v/@heretyc/subagent-mcp)](https://www.npmjs.com/package/@heretyc/subagent-mcp)
+[![CI](https://github.com/Heretyc/subagent-mcp/actions/workflows/claude-routine.yml/badge.svg)](https://github.com/Heretyc/subagent-mcp/actions/workflows/claude-routine.yml)
+MCP server that launches and manages always-interactive Claude Code and Codex sub-agent sessions — on macOS, Linux, and Windows. No direct API calls. No API keys.
+---
+## Install
+### Prerequisites (runtime)
+To run the published CLI you need:
+- Node.js >= 18  (`node --version`)
+- `claude` CLI — globally installed and authenticated  (`claude --version`)
+- `codex` CLI — globally installed and authenticated  (`codex --version`; optional if you only use Claude paths)
+Building from source needs additional developer tooling — see [CONTRIBUTING.md § Prerequisites](CONTRIBUTING.md#prerequisites).
+### npmjs (default)
+No authentication, no `.npmrc` configuration, and no PAT required. The package is publicly available on [npmjs.com](https://www.npmjs.com/package/@heretyc/subagent-mcp).
+```bash
+npm install -g @heretyc/subagent-mcp
+```
+**Use this path for all standard installs.**
+### GitHub Packages (org-internal pin / supply-chain auditing)
+Use this path when your organization's `.npmrc` already routes the `@heretyc` scope through GitHub Packages, when you need supply-chain audit tracing against the org-internal artifact, or when you run inside a GitHub Actions workflow whose `GITHUB_TOKEN` carries `read:packages`. Otherwise prefer npmjs above — it is simpler and needs no credentials.
+```bash
+# One-time machine setup
+echo "@heretyc:registry=https://npm.pkg.github.com" >> ~/.npmrc
+echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT" >> ~/.npmrc
+# PAT must be a classic PAT with the read:packages scope
+npm install -g @heretyc/subagent-mcp
+```
+> **Note:** GitHub Packages requires authentication even for public packages. If you see `401 Unauthorized`, verify your PAT has the `read:packages` scope and has not expired. GitHub Packages does not render a README page — the live documentation appears on [npmjs.com](https://www.npmjs.com/package/@heretyc/subagent-mcp).
+---
+## Quick Start
+**1. Install** (see [Install](#install) above):
+```bash
+npm install -g @heretyc/subagent-mcp
+```
+**2. Register the MCP server + orchestration hooks:**
+```bash
+subagent-mcp setup
+```
+Installing the package only ships the binary — it does **not** auto-wire anything. `subagent-mcp setup` auto-detects Claude Code / Codex and registers the MCP server plus the per-turn orchestration-mode hooks. Preview with `subagent-mcp setup --dry-run`.
+**3. Restart your host.**
+Restart your Claude Code or Codex session so it picks up the new binary. On Codex, run `/hooks` and trust the new hook.
+**4. Initialize the orchestration invariant (recommended):**
+```bash
+subagent-mcp init --global
+```
+`init --global` writes the managed invariant block into the providers' official global user-config files — `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md` — set up once, works across every project. For a single project instead, use `subagent-mcp init --root /path/to/project` to write into that project's instruction files. `--global` and `--root` are mutually exclusive.
+For manual wiring, Gemini CLI, Claude Desktop, and developer install from source, see [docs/registration.md](docs/registration.md).
+---
+## Features
+- Start Claude or Codex interactive sessions as managed sub-agents from any MCP host
+- Poll status, stream stdout/stderr tails, and enqueue follow-up messages to live sessions
+- Concurrency caps: 5 concurrent Claude + 5 concurrent Codex agents (only `processing` agents count toward the cap; `stalled` agents do not hold a slot)
+- Liveness tracking via the visible provider stream (Claude SDK events, Codex app-server JSONL): agents with no parsed visible provider stream item for 10 minutes enter `stalled` state (still alive, just quiet — thinking or awaiting a temp-file handoff), and recover to `processing` if the visible stream resumes
+- Ultracode mode for Opus 4.8 via `--settings {"ultracode":true}` — see [docs/usage.md](docs/usage.md)
+- Cross-platform exe resolution (Windows: npm-prefix .exe paths; macOS/Linux: PATH + Homebrew/usr-local fallbacks); immediate `taskkill /t /f` (Windows) / `SIGKILL` (POSIX) force-kill; no graceful shutdown period
+- stdio MCP transport; built with `@modelcontextprotocol/sdk` + `zod`
+- `orchestration-mode` tool — toggles orchestrator directives injected by bundled Claude Code / Codex hooks; Claude also gets a deterministic `PreToolUse` gate
+---
+## Orchestration Mode
+**ON:** the agent operates as an orchestrator — hook injection governs each session turn, preventing inline reads or writes, and all work is delegated through sub-agent tools.
+**OFF:** the agent operates normally, with no orchestration constraints.
+Toggle with the `orchestration-mode` tool. Desktop hosts toggle the mode but receive no hook injection. See [docs/spec/dev-loop/orchestration-directive-architecture.md](docs/spec/dev-loop/orchestration-directive-architecture.md) for full semantics.
+---
+## Auto Mode
+Pass `task_category` to `launch_agent` and the server picks the best provider, model, and effort for that category, with automatic fallback.
+`launch_agent` supports **auto mode**: pass `prompt` + `task_category` and the server picks the best provider/model/effort for that category from its routing table, silently falling back to the next-best candidate on any launch-time failure.
+`provider`, `model`, and `effort` are optional overrides — omit them to get the auto-selected best combination. Rules: passing `model` requires `provider`; passing `effort` requires both `provider` and `model`.
+**task_category** (required) — pick one:
+| Category | What it is |
+|---|---|
+| `math_proof` | deliverable is a proof/derivation/formally-checkable result |
+| `security_review` | security verdict, threat assessment, or demonstrated exploit |
+| `debugging` | verified fix/root-cause; requires an observed failure as precondition |
+| `quality_review` | evaluative verdict on existing artifact (review, A-vs-B, validate-vs-spec) |
+| `architecture` | cross-module design/plan, no code, no execution loop |
+| `agentic_execution` | end-state via act/observe/adapt loop (run/deploy/provision/browse) |
+| `data_analysis` | empirical finding about structured dataset (query, stat, model) |
+| `coding` | bounded runnable code artifact, one-pass (implement, test, refactor) |
+| `knowledge_synthesis` | novel integrated prose over sources (synthesize, summarize, draft) |
+| `mechanical` | deterministic single-pass transform, exact-match checkable (grep, rename, reformat) |
+| `prompt_engineering` | designed/optimized prompt or prompt-system steering an LLM/agent (composite-inferred) |
+| `vulnerability_research` | discovery + PoC of a novel vulnerability (composite-inferred) |
+| `molecular_biology` | reasoned molecular/computational-biology result over sequences, structures, or -omics data (composite-inferred) |
+| `ml_accelerator_design` | hardware/software design for ML acceleration — dataflow, kernel, roofline (composite-inferred) |
+| `fallback_default` | no category matches with confidence; prefer splitting work instead |
+The last four are **composite-inferred**: they carry no dedicated benchmark and their routing competency is composed from parent categories rather than measured directly.
+**Atomic-split guidance:** if you are unsure which category fits, do NOT submit one large amorphous task. Break the work into smaller atomic steps each mapping to a single category and launch one agent per step.
+---
+## Configuration
+### Global concurrent-subagent cap
+subagent-mcp enforces a machine-global cap on the number of **live concurrent subagents** across all agentic sessions and MCP server processes on the machine. The count includes agents started by other active sessions and the whole recursive descendant tree; slots free as agents finish or are killed.
+The cap is configured in `global-concurrency.jsonc`, a dedicated dist-sibling file in the install directory. It is separate from the advanced routing directives file, ships as a commented template, and is retained across installs and updates by the same preserve-user-edits mechanism as the advanced routing directives.
+Set `globalConcurrentSubagents` in that file. The default is `20`; the minimum valid value is `10`. Validation is forced: `0`, unset, missing, or invalid values reset to `20`, and values `1` through `9` are pinned up to `10`. There is no environment-variable override; the file is the sole source of truth. The file is re-read on every `launch_agent` call, so edits take effect on the next launch with no server restart.
+When the cap is reached, `launch_agent` is rejected immediately; it never queues. Because the count includes other active sessions and the entire descendant tree, free slots manually with `list_agents` and `kill_agent` before retrying. There is no automatic cleanup or zombie reaping.
+---
+## Tools
+Eight tools are exposed over the stdio MCP transport.
+| Tool | Description |
+|---|---|
+| `launch_agent` | Start a new sub-agent session with a prompt and optional task category / overrides |
+| `poll_agent` | Check status and stream tail output for a running agent |
+| `kill_agent` | Terminate a running or stalled agent |
+| `send_message` | Enqueue a message into a running agent's stdin |
+| `list_agents` | List all tracked agents and their current status |
+| `wait` | Block until a specific agent reaches a terminal state |
+| `orchestration-mode` | Toggle orchestration-mode ON/OFF; controls whether hook directives are injected into agent sessions |
+| `model-selection-mode` | Control model selection: `smart` (auto-pick) or `user-approved-overrides` (30-min override window) |
+Full parameters, return shapes, and the `alive` / `idle_seconds` / `hint` / `recent_stream` fields are in [docs/tools.md](docs/tools.md).
+---
+## Agent Lifecycle
+Each agent transitions through these states:
+| Status | Meaning |
+|---|---|
+| `processing` | Driver alive with a visible provider-stream heartbeat in the last 10 minutes — actively working. Launch time counts as the initial heartbeat |
+| `stalled` | Driver STILL ALIVE but no parsed visible provider stream item for >= 10 minutes — working, thinking, or awaiting a temp-file handoff (not a failure). Recovers to `processing` if the visible stream resumes |
+| `finished` | Current turn completed, or driver exited with code 0 |
+| `errored` | Process exited with non-zero code |
+| `stopped` | Terminated by `kill_agent` |
+`processing` and `stalled` are live. `stalled` means the driver is alive but quiet (>= 10 min no visible stream); it recovers automatically and is never auto-killed — do not `kill_agent` a stalled agent. `wait` does not return on `stalled`. Full semantics: [docs/reference/status-lifecycle.md](docs/reference/status-lifecycle.md).
+---
+## Documentation
+| Document | Contents |
+|---|---|
+| [docs/registration.md](docs/registration.md) | Per-platform setup: Claude Code, Codex, Gemini CLI, Claude Desktop; manual wiring; developer install from source |
+| [docs/tools.md](docs/tools.md) | Full tool reference — all eight tools, parameters, return shapes |
+| [docs/usage.md](docs/usage.md) | Model & effort matrix, ultracode mode, CLI invocations, usage examples |
+| [docs/SPEC.md](docs/SPEC.md) | Full technical specification — architecture, schemas, status lifecycle, error catalogue |
+| [docs/spec/interactive-drivers.md](docs/spec/interactive-drivers.md) | Always-interactive Claude/Codex driver model |
+| [docs/release-notes.md](docs/release-notes.md) | Operator-facing release notes |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Contributor guide — dev environment, build, test, publish |
+---
+## License
+Apache-2.0 — Copyright 2026 Lexi Blackburn
+See [LICENSE](LICENSE).

package/dist/concurrency.js ADDED Viewed

@@ -0,0 +1,96 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { platform } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONCURRENCY_SCAFFOLD } from "./config-scaffold.js";
+export const DEFAULT_CAP = 20;
+export const MIN_CAP = 10;
+export const CONFIG_FILENAME = "global-concurrency.jsonc";
+export function clampCap(raw) {
+    if (!Number.isInteger(raw))
+        return DEFAULT_CAP;
+    const v = raw;
+    if (v <= 0)
+        return DEFAULT_CAP;
+    if (v < MIN_CAP)
+        return MIN_CAP;
+    return v;
+}
+export function stripJsoncComments(text) {
+    return text.replace(/^\s*\/\/.*$/gm, "");
+}
+export function parseConcurrencyConfig(text) {
+    let raw;
+    try {
+        raw = JSON.parse(stripJsoncComments(text))?.globalConcurrentSubagents;
+    }
+    catch {
+        raw = undefined;
+    }
+    return clampCap(raw);
+}
+export function defaultConfigPath() {
+    return fileURLToPath(new URL("./" + CONFIG_FILENAME, import.meta.url));
+}
+export function ensureConcurrencyConfig(path = defaultConfigPath()) {
+    try {
+        if (existsSync(path))
+            return;
+        writeFileSync(path, CONCURRENCY_SCAFFOLD);
+    }
+    catch { }
+}
+export function readGlobalCap(path = defaultConfigPath()) {
+    try {
+        ensureConcurrencyConfig(path);
+        return parseConcurrencyConfig(readFileSync(path, "utf8"));
+    }
+    catch {
+        return DEFAULT_CAP;
+    }
+}
+export function slotDir() {
+    if (platform() === "win32") {
+        return join(process.env.ProgramData || process.env.ALLUSERSPROFILE || "C:\\ProgramData", "subagent-mcp", "slots");
+    }
+    return "/tmp/subagent-mcp/slots";
+}
+export function countSlots(dir = slotDir()) {
+    try {
+        return readdirSync(dir).filter((f) => f.startsWith("slot-")).length;
+    }
+    catch {
+        return 0;
+    }
+}
+export function reserveSlot(agentId, max, dir = slotDir()) {
+    try {
+        mkdirSync(dir, { recursive: true, mode: 0o1777 });
+        const slotPath = join(dir, `slot-${agentId}.json`);
+        writeFileSync(slotPath, JSON.stringify({ pid: process.pid, cwd: process.cwd(), startedAt: new Date().toISOString() }), { mode: 0o600 });
+        const n = countSlots(dir);
+        if (n > max) {
+            try {
+                unlinkSync(slotPath);
+            }
+            catch { }
+            return { ok: false, current: n - 1, max };
+        }
+        return { ok: true, slotPath, current: n, max };
+    }
+    catch (e) {
+        console.error(`[concurrency] reserve failed, failing open: ${e instanceof Error ? e.message : String(e)}`);
+        return { ok: true, current: 0, max, slotPath: null };
+    }
+}
+export function releaseSlot(slotPath) {
+    if (!slotPath)
+        return;
+    try {
+        unlinkSync(slotPath);
+    }
+    catch { }
+}
+export function globalCapMessage(current, max, configPath = defaultConfigPath()) {
+    return `Global concurrent-subagent limit reached: ${current} of ${max} live subagents are already running across all sessions on this machine. This global count includes agents started by OTHER active agentic sessions and the ENTIRE recursive descendant tree, not just this session's direct children. launch_agent was REJECTED — this cap never queues or blocks; no slot frees itself by waiting. Free a slot manually first: call list_agents to see live agents, then kill_agent to terminate ones you no longer need, and retry. The limit is "globalConcurrentSubagents" in ${configPath} (default 20, minimum 10).`;
+}

package/dist/config-scaffold.js ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ // GENERATED by scripts/gen-ruleset-scaffold.mjs from src/global-concurrency.jsonc — DO NOT EDIT.
2	+ export const CONCURRENCY_SCAFFOLD = "// subagent-mcp — Global Concurrent Subagent Cap\r\n// ------------------------------------------------------------------\r\n// SOLE source of truth for the machine-wide limit on how many subagents\r\n// may be ALIVE AT ONCE across EVERY session, process, and user on this\r\n// machine. There is NO environment-variable override.\r\n//\r\n// The whole recursive descendant tree counts toward this ONE number: a\r\n// subagent that itself launches subagents adds to the same machine-wide\r\n// total, and OTHER active agentic sessions count too.\r\n//\r\n// RE-READ on every launch_agent call — edits take effect immediately, no\r\n// server restart required.\r\n//\r\n// Value rules (forcibly applied to the number below):\r\n// - missing / unset / non-integer / 0 / negative -> reset to default 20\r\n// - 1 through 9 -> forced UP to minimum 10\r\n// - 10 or greater -> used as-is\r\n//\r\n// When the cap is reached, launch_agent is REJECTED (never queued). Free a\r\n// slot with list_agents + kill_agent, then retry.\r\n//\r\n// Slots free automatically as agents finish or are killed. There is NO\r\n// zombie reaping. If a server process CRASHES, its slots stay counted until\r\n// you delete the stale slot files by hand:\r\n// Windows: %ProgramData%\\subagent-mcp\\slots\r\n// macOS/Linux: /tmp/subagent-mcp/slots\r\n{\r\n \"globalConcurrentSubagents\": 20\r\n}\r\n";

package/dist/global-concurrency.jsonc ADDED Viewed

@@ -0,0 +1,29 @@
+// subagent-mcp — Global Concurrent Subagent Cap
+// ------------------------------------------------------------------
+// SOLE source of truth for the machine-wide limit on how many subagents
+// may be ALIVE AT ONCE across EVERY session, process, and user on this
+// machine. There is NO environment-variable override.
+//
+// The whole recursive descendant tree counts toward this ONE number: a
+// subagent that itself launches subagents adds to the same machine-wide
+// total, and OTHER active agentic sessions count too.
+//
+// RE-READ on every launch_agent call — edits take effect immediately, no
+// server restart required.
+//
+// Value rules (forcibly applied to the number below):
+//   - missing / unset / non-integer / 0 / negative  -> reset to default 20
+//   - 1 through 9                                    -> forced UP to minimum 10
+//   - 10 or greater                                 -> used as-is
+//
+// When the cap is reached, launch_agent is REJECTED (never queued). Free a
+// slot with list_agents + kill_agent, then retry.
+//
+// Slots free automatically as agents finish or are killed. There is NO
+// zombie reaping. If a server process CRASHES, its slots stay counted until
+// you delete the stale slot files by hand:
+//   Windows:      %ProgramData%\subagent-mcp\slots
+//   macOS/Linux:  /tmp/subagent-mcp/slots
+{
+  "globalConcurrentSubagents": 20
+}

package/dist/index.js CHANGED Viewed

@@ -18,6 +18,7 @@ import { consumeStreamChunk, flushStream, isTurnCompletedLine, retainLastN, } fr
 import { loadRoutingTable, buildCandidates, validatePresence, TASK_CATEGORIES, AUTO_HINT, SPLIT_HINT, } from "./routing.js";
 import { createDeadlockWindow } from "./deadlock.js";
 import { createRulesetGate, RULESET_HARD_FAIL_MSG, } from "./ruleset.js";
+import { CONFIG_FILENAME, defaultConfigPath, globalCapMessage, readGlobalCap, releaseSlot, reserveSlot, } from "./concurrency.js";
 import * as orchestrationMarker from "./orchestration/marker.js";
 import * as modelMode from "./orchestration/model-mode.js";
 import { startLivenessHeartbeat } from "./orchestration/liveness.js";
@@ -143,7 +144,7 @@ const ORCHESTRATION_INSTRUCTIONS = "subagent-mcp - CANONICAL OPERATING MODEL (fu
 const SUBAGENT_INSTRUCTIONS = "SUB-AGENT SESSION: you are a child process launched by subagent-mcp. Follow the parent prompt. Do not treat yourself as the orchestrator, do not re-trigger orchestration carryover, and do not launch further sub-agents unless the parent prompt explicitly assigns that.\n\nMODEL SELECTION MODE (parallel to orchestration-mode, set via the model-selection-mode tool). DEFAULT is \"smart\" and is used whenever unset: in smart, launch_agent REJECTS any call supplying provider/model/effort selectors and the server auto-picks the best model. \"user-approved-overrides\" opens a 30-MINUTE window where selectors are HONORED, enforced LAZILY (the mode reverts to smart on the next launch_agent call after 30 minutes) and re-enabling does NOT extend an active window. HONOR-BASED: you MUST NOT set \"user-approved-overrides\" without explicit interactive USER authorization via the structured-question tool (AskUserQuestion on Claude / request-user-input on Codex); never enable it on your own initiative.";
 const server = new McpServer({
     name: "subagent-mcp",
-    version: "2.9.2",
+    version: "2.10.0",
     description: "Launches always-interactive local Claude and Codex sub-agent sessions. Claude uses the Claude Agent SDK over the local Claude Code executable; Codex uses `codex app-server` over stdio. The server does not call Anthropic or OpenAI HTTP APIs directly.",
 }, {
     instructions: process.env.SUBAGENT_MCP_SUBAGENT === "1"
@@ -359,6 +360,8 @@ async function tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rule
         }
         // Always clean up ultracode settings file on close
         cleanupUcSettings(agentState);
+        releaseSlot(agentState.slotPath ?? null);
+        agentState.slotPath = null;
         // Always record actual close time (unless already finalized)
         if (agentState.exitedAt === null)
             agentState.exitedAt = Date.now();
@@ -599,69 +602,94 @@ server.tool("launch_agent", "Spawn a sub-agent session. AUTO MODE (mandatory fir
     }
     // 6. Attempt loop: best→worst. Register on first successful driver start; silently
     //    advance on launch-time failure. Sub-agent task outcome is NEVER a trigger.
+    const cap = readGlobalCap();
+    const reservationId = randomUUID();
+    const reservation = reserveSlot(reservationId, cap);
+    if (!reservation.ok) {
+        return errorResult(globalCapMessage(reservation.current, cap, defaultConfigPath()));
+    }
     const skipped = [];
-    for (const candidate of candidates) {
-        const outcome = await tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rulesetApplied && rulesetOriginalSelection !== undefined
-            ? { applied: true, originalSelection: rulesetOriginalSelection }
-            : undefined);
-        if ("agentId" in outcome) {
-            if (branch === "performance") {
-                deadlockWindow.consume();
-            }
-            if (skipped.length > 0) {
+    let launched = false;
+    try {
+        for (const candidate of candidates) {
+            const outcome = await tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rulesetApplied && rulesetOriginalSelection !== undefined
+                ? { applied: true, originalSelection: rulesetOriginalSelection }
+                : undefined);
+            if ("agentId" in outcome) {
+                if (branch === "performance") {
+                    deadlockWindow.consume();
+                }
                 const registeredAgent = agents.get(outcome.agentId);
                 if (registeredAgent) {
-                    registeredAgent.failoverFrom = skipped.map((s) => ({
-                        provider: s.provider,
-                        model: s.model,
-                        effort: s.effort,
-                        failure_type: s.failure_type,
-                    }));
+                    registeredAgent.slotPath = reservation.slotPath;
+                    // The child can reach a terminal state DURING tryLaunchCandidate's
+                    // awaits — before slotPath was set — so its close handler ran
+                    // releaseSlot(undefined) (a no-op) and left the slot leaked. Detect
+                    // that here and release now. slotPath is unique per reservation, so
+                    // this never frees another agent's slot.
+                    if (registeredAgent.exitCode !== null) {
+                        releaseSlot(registeredAgent.slotPath);
+                        registeredAgent.slotPath = null;
+                    }
+                    if (skipped.length > 0) {
+                        registeredAgent.failoverFrom = skipped.map((s) => ({
+                            provider: s.provider,
+                            model: s.model,
+                            effort: s.effort,
+                            failure_type: s.failure_type,
+                        }));
+                    }
                 }
+                launched = true;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                agent_id: outcome.agentId,
+                                status: "processing",
+                                provider: candidate.provider,
+                                model: candidate.model,
+                                effort: candidate.effort,
+                                task_category,
+                                ...(rulesetApplied
+                                    ? {
+                                        ruleset_applied: true,
+                                        ruleset_original_selection: rulesetOriginalSelection,
+                                    }
+                                    : {}),
+                                ...(skipped.length > 0
+                                    ? {
+                                        failover_occurred: true,
+                                        failover_from: skipped.map((s) => ({
+                                            provider: s.provider,
+                                            model: s.model,
+                                            effort: s.effort,
+                                            failure_type: s.failure_type,
+                                        })),
+                                        failover_note: buildFailoverNote(skipped, candidate),
+                                    }
+                                    : {}),
+                            }),
+                        },
+                    ],
+                };
+            }
+            skipped.push({
+                model: candidate.model,
+                effort: candidate.effort,
+                provider: candidate.provider,
+                reason: outcome.reason,
+                failure_type: outcome.failure_type,
+            });
+            if (!pureAuto) {
+                break;
             }
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            agent_id: outcome.agentId,
-                            status: "processing",
-                            provider: candidate.provider,
-                            model: candidate.model,
-                            effort: candidate.effort,
-                            task_category,
-                            ...(rulesetApplied
-                                ? {
-                                    ruleset_applied: true,
-                                    ruleset_original_selection: rulesetOriginalSelection,
-                                }
-                                : {}),
-                            ...(skipped.length > 0
-                                ? {
-                                    failover_occurred: true,
-                                    failover_from: skipped.map((s) => ({
-                                        provider: s.provider,
-                                        model: s.model,
-                                        effort: s.effort,
-                                        failure_type: s.failure_type,
-                                    })),
-                                    failover_note: buildFailoverNote(skipped, candidate),
-                                }
-                                : {}),
-                        }),
-                    },
-                ],
-            };
         }
-        skipped.push({
-            model: candidate.model,
-            effort: candidate.effort,
-            provider: candidate.provider,
-            reason: outcome.reason,
-            failure_type: outcome.failure_type,
-        });
-        if (!pureAuto) {
-            break;
+    }
+    finally {
+        if (!launched) {
+            releaseSlot(reservation.slotPath);
         }
     }
     // 7. All candidates failed. Override selector modes are single-attempt hard
@@ -790,6 +818,8 @@ server.tool("kill_agent", "Terminate a live agent/session (status `processing`,
         // POSIX, SIGKILL the process (close handler records the real exit code).
         agent.status = "stopped";
         agent.driver.kill();
+        releaseSlot(agent.slotPath ?? null);
+        agent.slotPath = null;
         if (isWindows && agent.process.pid) {
             spawn("taskkill", ["/pid", String(agent.process.pid), "/t", "/f"], {
                 windowsHide: true,
@@ -1154,7 +1184,9 @@ if (isMain) {
         }
         const installRoot = join(npmRoot.stdout.toString().trim(), ...pkg.name.split("/"));
         const rulesetPath = join(installRoot, "dist", "advanced-ruleset.py");
+        const cfgPath = join(installRoot, "dist", CONFIG_FILENAME);
         let previousRuleset = null;
+        let previousCfg = null;
         if (existsSync(rulesetPath)) {
             previousRuleset = readFileSync(rulesetPath);
             const backupPath = join(tmpdir(), `advanced-ruleset.py.bak-update-${Date.now()}`);
@@ -1167,6 +1199,18 @@ if (isMain) {
                 process.exit(1);
             }
         }
+        if (existsSync(cfgPath)) {
+            previousCfg = readFileSync(cfgPath);
+            const backupPath = join(tmpdir(), `${CONFIG_FILENAME}.bak-update-${Date.now()}`);
+            try {
+                writeFileSync(backupPath, previousCfg);
+                console.log(`backed up user ${CONFIG_FILENAME} to ${backupPath}`);
+            }
+            catch (e) {
+                console.error(`update refused before install: failed to back up ${CONFIG_FILENAME}: ${e instanceof Error ? e.message : String(e)}`);
+                process.exit(1);
+            }
+        }
         const r = spawnNpm(npmArgs, "inherit");
         if (r.error) {
             console.error(`update failed to start npm: ${r.error.message}`);
@@ -1189,6 +1233,21 @@ if (isMain) {
                     process.exit(1);
                 }
             }
+            if (previousCfg !== null) {
+                try {
+                    const freshCfg = existsSync(cfgPath)
+                        ? readFileSync(cfgPath)
+                        : null;
+                    if (freshCfg === null || !previousCfg.equals(freshCfg)) {
+                        writeFileSync(cfgPath, previousCfg);
+                        console.log(`restored user ${CONFIG_FILENAME} (package update never overwrites user edits)`);
+                    }
+                }
+                catch (e) {
+                    console.error(`update failed to restore ${CONFIG_FILENAME}: ${e instanceof Error ? e.message : String(e)}`);
+                    process.exit(1);
+                }
+            }
             console.log("Update complete. Restart your CLI sessions so the MCP server picks up the new build.");
         }
         process.exit(code);

package/dist/setup.js CHANGED Viewed

@@ -227,6 +227,7 @@ export function verifyInstall(root = INSTALL_ROOT) {
     const required = [
         "dist/index.js",
         "dist/advanced-ruleset.py",
+        "dist/global-concurrency.jsonc",
         "dist/hooks/orchestration-claude.js",
         "dist/hooks/orchestration-claude-pretool.js",
         "dist/hooks/orchestration-codex.js",

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@heretyc/subagent-mcp",
-  "version": "2.9.2",
+  "version": "2.10.0",
   "description": "MCP server that launches and manages always-interactive Claude Code and Codex sub-agent sessions (no direct Anthropic/OpenAI API).",
   "keywords": [
     "mcp",
@@ -37,7 +37,7 @@
     "postinstall": "node scripts/postinstall.mjs",
     "prepare": "npm run build",
     "prepublishOnly": "npm test",
-    "test": "npm run check:versions && node test/effort.test.mjs && node test/drivers.test.mjs && node test/platform.test.mjs && node test/wait.test.mjs && node test/status.test.mjs && node test/output.test.mjs && node test/stream.test.mjs && node test/routing.test.mjs && node test/deadlock.test.mjs && node test/handler-validation.test.mjs && node test/index-handler.test.mjs && node test/ruleset.test.mjs && node test/ruleset-exec.test.mjs && node test/ruleset-handler.test.mjs && node test/failover.test.mjs && node test/orchestration-marker.test.mjs && node test/orchestration-hook-core.test.mjs && node test/orchestration-adapters.test.mjs && node test/orchestration-pretool.test.mjs && node test/orchestration-directives.test.mjs && node test/no-five-call.test.mjs && node test/check-worktree-subagent.test.mjs && node test/launch-agent-upsert.test.mjs && node test/claude-session-limit.test.mjs && node test/init-migration.test.mjs && node test/init-global.test.mjs && node test/mirror-fragments.test.mjs && node test/performance-tier-effort.test.mjs && node test/setup-repair.test.mjs && node test/setup-quoting.test.mjs && node test/setup-wire.test.mjs && node test/setup-cli-integration.test.mjs && node test/init.test.mjs && node test/model-selection-mode.test.mjs && node test/cli-args.test.mjs && node scripts/validate_provider.mjs && node scripts/validate_seed_sites.mjs && node scripts/validate_routing_audit.mjs && node test/seed-sites.test.mjs && node test/mcp-compliance.test.mjs"
+    "test": "npm run check:versions && node test/effort.test.mjs && node test/drivers.test.mjs && node test/platform.test.mjs && node test/wait.test.mjs && node test/status.test.mjs && node test/output.test.mjs && node test/stream.test.mjs && node test/routing.test.mjs && node test/deadlock.test.mjs && node test/handler-validation.test.mjs && node test/index-handler.test.mjs && node test/ruleset.test.mjs && node test/ruleset-exec.test.mjs && node test/ruleset-handler.test.mjs && node test/failover.test.mjs && node test/global-concurrency-cap.test.mjs && node test/orchestration-marker.test.mjs && node test/orchestration-hook-core.test.mjs && node test/orchestration-adapters.test.mjs && node test/orchestration-pretool.test.mjs && node test/orchestration-directives.test.mjs && node test/no-five-call.test.mjs && node test/check-worktree-subagent.test.mjs && node test/launch-agent-upsert.test.mjs && node test/claude-session-limit.test.mjs && node test/init-migration.test.mjs && node test/init-global.test.mjs && node test/mirror-fragments.test.mjs && node test/performance-tier-effort.test.mjs && node test/setup-repair.test.mjs && node test/setup-quoting.test.mjs && node test/setup-wire.test.mjs && node test/setup-cli-integration.test.mjs && node test/init.test.mjs && node test/model-selection-mode.test.mjs && node test/cli-args.test.mjs && node scripts/validate_provider.mjs && node scripts/validate_seed_sites.mjs && node scripts/validate_routing_audit.mjs && node test/seed-sites.test.mjs && node test/mcp-compliance.test.mjs"
   },
   "author": "Lexi Blackburn",
   "license": "Apache-2.0",