@heretyc/subagent-mcp 2.12.13 → 2.12.14

package/README.md

@@ -1,170 +1,170 @@
-# 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)
-
-## Core Premise
-
-subagent-mcp is an MCP stdio server that turns an AI coding assistant (Claude
-Code, Codex, Gemini CLI) into a manager of local Claude and Codex sub-agents on
-macOS, Linux, and Windows. It drives the locally authenticated `claude` and
-`codex` CLIs you already signed into. It does not make direct HTTP API calls and
-does not require API keys.
-
-The orchestrator monitors but does not read or write project files itself. Work
-is delegated to fresh sub-agents, so the orchestrator keeps summaries instead
-of raw file context. The main invariants are:
-
-- one machine-global, provider-agnostic concurrency cap (default 20, minimum 10)
-- fail-safe orchestration ON on hookless hosts
-- state authority only from harness-verified `<subagent-mcp state="...">` tags
-- sub-agents gated by default with permission ceiling `auto`
-- automatic model, provider, and effort routing per task category
-
-## Install
-
-### What You Need First
-
-- Node.js 18 or newer (`node --version`)
-- `claude` CLI, installed and signed in (`claude --version`)
-- `codex` CLI, installed and signed in (`codex --version`; optional if you only
-  use Claude)
-
-Building from source needs extra developer tools. See
-[CONTRIBUTING.md](CONTRIBUTING.md).
-
-### Install The Package
-
-```bash
-npm install -g @heretyc/subagent-mcp
-```
-
-This is the standard install. Organizations pinning the package through GitHub
-Packages should see [docs/registration.md](docs/registration.md).
-
-### Wire It Into Your Assistant
-
-```bash
-subagent-mcp setup
-```
-
-Installing the package only ships the program. It does not connect anything on
-its own. `subagent-mcp setup` finds your Claude Code or Codex install and
-registers both the server and the per-turn orchestration hooks. Preview first
-with `subagent-mcp setup --dry-run`.
-
-### Restart, Then Turn On The Invariant
-
-Restart your Claude Code or Codex session so it picks up the new tools. On
-Codex, run `/hooks` and trust the new hook. Then, recommended:
-
-```bash
-subagent-mcp init --global
-```
-
-This writes a managed "always delegate" rule block into your global assistant
-config once. For one project only, use
-`subagent-mcp init --root /path/to/project`. Full per-platform wiring (Gemini
-CLI, Claude Desktop, manual setup) is in
-[docs/registration.md](docs/registration.md).
-
-## How To Operate It
-
-### Orchestration Mode
-
-- **ON**: your assistant acts as a pure manager. It delegates every step to
-  sub-agents. Best for big, long-running jobs.
-- **OFF**: your assistant works normally, with no delegation rules.
-
-Flip it with the `orchestration-mode` tool. Desktop apps can toggle the mode but
-do not receive per-turn hook reminders.
-
-### Tools
-
-The server exposes `launch_agent`, `poll_agent`, `kill_agent`, `send_message`,
-`list_agents`, `wait`, `respond_permission`, `orchestration-mode`, and
-`model-selection-mode`. See [docs/tools.md](docs/tools.md) for the full
-parameter and return reference.
-
-You do not have to choose a model. Give `launch_agent` a prompt and a task
-category such as `coding`, `debugging`, or `security_review`; the server picks
-the provider, model, and effort.
-
-### Concurrency
-
-There is one machine-wide limit on concurrent sub-agents. The default is 20.
-When the limit is reached, `launch_agent` is rejected immediately and does not
-queue. Change the value in `global-subagent-mcp-config.jsonc` in the install
-folder. The file is re-read on every launch.
-
-The config file was renamed from `global-concurrency.jsonc` in 2.12.5. The old
-name is still read, with a one-time deprecation notice, when the new file is
-absent.
-
-The same settings file includes `checkForUpdates` (default `true`). Disable it
-with `checkForUpdates: false` or `SUBAGENT_UPDATE_CHECK=0`.
-
-## Configuration
-
-Machine-wide defaults live in `global-subagent-mcp-config.jsonc`, installed
-beside the compiled server and re-read on every `launch_agent`. It controls the
-global concurrency cap, update checks, permission ceiling, escalation behavior,
-strict read-parity logging, and Codex sandbox networking.
-
-User and repo permission files can only tighten or add scoped permissions on top
-of the global ceiling. See [README/configuration.md](README/configuration.md)
-for the full key table, precedence rules, and mode summary.
-
-## Permissions
-
-Launched sub-agents run gated by default. Set `permissionsCeiling` in
-`global-subagent-mcp-config.jsonc`:
-
-| Mode | What a sub-agent can do |
-|---|---|
-| `auto` | Default. Safe reads auto-allow, dangerous actions auto-deny, everything else parks for your decision. |
-| `manual` | Same, but every non-denied action parks for a decision. |
-| `yolo` | No gating at all. |
-
-When a sub-agent's action parks, its status becomes `permission_requested` and
-it appears in `poll_agent`, `list_agents`, and `wait`. Answer it with:
-
-```text
-respond_permission(agent_id="...", decision="allow" | "deny", reason="...")
-```
-
-One-time only. Omit `request_id` to answer the oldest pending request.
-Unanswered requests auto-deny after 5 minutes. Full spec:
-[docs/spec/permissions.md](docs/spec/permissions.md).
-
-## Basic Debugging
-
-- **An agent looks stuck.** A quiet agent is usually still alive. After about 10
-  minutes with no output an agent is marked `stalled`. Prefer `wait` or another
-  `poll_agent` over killing it.
-- **Cap reached.** Use `list_agents` to see what is running and `kill_agent` on
-  work you no longer need. Raising `globalConcurrentSubagents` also works.
-- **Logs.** Agent output is available through `poll_agent`. Server diagnostics
-  go to the host MCP server log on stderr.
-
-## Documentation
-
-| Document | Contents |
-|---|---|
-| [docs/spec/arch-rationale.md](docs/spec/arch-rationale.md) | Design rationale |
-| [docs/registration.md](docs/registration.md) | Per-platform setup |
-| [docs/tools.md](docs/tools.md) | Tool reference |
-| [docs/usage.md](docs/usage.md) | Model and effort matrix |
-| [docs/SPEC.md](docs/SPEC.md) | Technical specification |
-| [README/configuration.md](README/configuration.md) | Configuration keys and precedence |
-| [docs/spec/permissions.md](docs/spec/permissions.md) | Permission system |
-| [docs/reference/status-lifecycle.md](docs/reference/status-lifecycle.md) | Agent status meanings |
-| [CONTRIBUTING.md](CONTRIBUTING.md) | Developer guide |
-
-## 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)
+
+## Core Premise
+
+subagent-mcp is an MCP stdio server that turns an AI coding assistant (Claude
+Code, Codex, Gemini CLI) into a manager of local Claude and Codex sub-agents on
+macOS, Linux, and Windows. It drives the locally authenticated `claude` and
+`codex` CLIs you already signed into. It does not make direct HTTP API calls and
+does not require API keys.
+
+The orchestrator monitors but does not read or write project files itself. Work
+is delegated to fresh sub-agents, so the orchestrator keeps summaries instead
+of raw file context. The main invariants are:
+
+- one machine-global, provider-agnostic concurrency cap (default 20, minimum 10)
+- fail-safe orchestration ON on hookless hosts
+- state authority only from harness-verified `<subagent-mcp state="...">` tags
+- sub-agents gated by default with permission ceiling `auto`
+- automatic model, provider, and effort routing per task category
+
+## Install
+
+### What You Need First
+
+- Node.js 18 or newer (`node --version`)
+- `claude` CLI, installed and signed in (`claude --version`)
+- `codex` CLI, installed and signed in (`codex --version`; optional if you only
+  use Claude)
+
+Building from source needs extra developer tools. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+### Install The Package
+
+```bash
+npm install -g @heretyc/subagent-mcp
+```
+
+This is the standard install. Organizations pinning the package through GitHub
+Packages should see [docs/registration.md](docs/registration.md).
+
+### Wire It Into Your Assistant
+
+```bash
+subagent-mcp setup
+```
+
+Installing the package only ships the program. It does not connect anything on
+its own. `subagent-mcp setup` finds your Claude Code or Codex install and
+registers both the server and the per-turn orchestration hooks. Preview first
+with `subagent-mcp setup --dry-run`.
+
+### Restart, Then Turn On The Invariant
+
+Restart your Claude Code or Codex session so it picks up the new tools. On
+Codex, run `/hooks` and trust the new hook. Then, recommended:
+
+```bash
+subagent-mcp init --global
+```
+
+This writes a managed "always delegate" rule block into your global assistant
+config once. For one project only, use
+`subagent-mcp init --root /path/to/project`. Full per-platform wiring (Gemini
+CLI, Claude Desktop, manual setup) is in
+[docs/registration.md](docs/registration.md).
+
+## How To Operate It
+
+### Orchestration Mode
+
+- **ON**: your assistant acts as a pure manager. It delegates every step to
+  sub-agents. Best for big, long-running jobs.
+- **OFF**: your assistant works normally, with no delegation rules.
+
+Flip it with the `orchestration-mode` tool. Desktop apps can toggle the mode but
+do not receive per-turn hook reminders.
+
+### Tools
+
+The server exposes `launch_agent`, `poll_agent`, `kill_agent`, `send_message`,
+`list_agents`, `wait`, `respond_permission`, `orchestration-mode`, and
+`model-selection-mode`. See [docs/tools.md](docs/tools.md) for the full
+parameter and return reference.
+
+You do not have to choose a model. Give `launch_agent` a prompt and a task
+category such as `coding`, `debugging`, or `security_review`; the server picks
+the provider, model, and effort.
+
+### Concurrency
+
+There is one machine-wide limit on concurrent sub-agents. The default is 20.
+When the limit is reached, `launch_agent` is rejected immediately and does not
+queue. Change the value in `global-subagent-mcp-config.jsonc` in the install
+folder. The file is re-read on every launch.
+
+The config file was renamed from `global-concurrency.jsonc` in 2.12.5. The old
+name is still read, with a one-time deprecation notice, when the new file is
+absent.
+
+The same settings file includes `checkForUpdates` (default `true`). Disable it
+with `checkForUpdates: false` or `SUBAGENT_UPDATE_CHECK=0`.
+
+## Configuration
+
+Machine-wide defaults live in `global-subagent-mcp-config.jsonc`, installed
+beside the compiled server and re-read on every `launch_agent`. It controls the
+global concurrency cap, update checks, permission ceiling, escalation behavior,
+strict read-parity logging, and Codex sandbox networking.
+
+User and repo permission files can only tighten or add scoped permissions on top
+of the global ceiling. See [README/configuration.md](README/configuration.md)
+for the full key table, precedence rules, and mode summary.
+
+## Permissions
+
+Launched sub-agents run gated by default. Set `permissionsCeiling` in
+`global-subagent-mcp-config.jsonc`:
+
+| Mode | What a sub-agent can do |
+|---|---|
+| `auto` | Default. Safe reads auto-allow, dangerous actions auto-deny, everything else parks for your decision. |
+| `manual` | Same, but every non-denied action parks for a decision. |
+| `yolo` | No gating at all. |
+
+When a sub-agent's action parks, its status becomes `permission_requested` and
+it appears in `poll_agent`, `list_agents`, and `wait`. Answer it with:
+
+```text
+respond_permission(agent_id="...", decision="allow" | "deny", reason="...")
+```
+
+One-time only. Omit `request_id` to answer the oldest pending request.
+Unanswered requests auto-deny after 5 minutes. Full spec:
+[docs/spec/permissions.md](docs/spec/permissions.md).
+
+## Basic Debugging
+
+- **An agent looks stuck.** A quiet agent is usually still alive. After about 10
+  minutes with no output an agent is marked `stalled`. Prefer `wait` or another
+  `poll_agent` over killing it.
+- **Cap reached.** Use `list_agents` to see what is running and `kill_agent` on
+  work you no longer need. Raising `globalConcurrentSubagents` also works.
+- **Logs.** Agent output is available through `poll_agent`. Server diagnostics
+  go to the host MCP server log on stderr.
+
+## Documentation
+
+| Document | Contents |
+|---|---|
+| [docs/spec/arch-rationale.md](docs/spec/arch-rationale.md) | Design rationale |
+| [docs/registration.md](docs/registration.md) | Per-platform setup |
+| [docs/tools.md](docs/tools.md) | Tool reference |
+| [docs/usage.md](docs/usage.md) | Model and effort matrix |
+| [docs/SPEC.md](docs/SPEC.md) | Technical specification |
+| [README/configuration.md](README/configuration.md) | Configuration keys and precedence |
+| [docs/spec/permissions.md](docs/spec/permissions.md) | Permission system |
+| [docs/reference/status-lifecycle.md](docs/reference/status-lifecycle.md) | Agent status meanings |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Developer guide |
+
+## License
+
+Apache-2.0. Copyright 2026 Lexi Blackburn.
+
+See [LICENSE](LICENSE).

package/dist/advanced-ruleset.py

@@ -1,67 +1,67 @@
-#!/usr/bin/env python3
-"""advanced-ruleset.py — final-authority model-routing override hook for subagent-mcp.
-
-(a) PERFORMANCE WARNING: this script runs synchronously inside EVERY launch_agent
-    call. Slow rules slow every agent launch. Keep rules lean and low-latency —
-    no network calls, no heavy imports at module top. This is YOUR responsibility;
-    you have been warned.
-
-(b) OUTPUT CONTRACT (routing mode): print to stdout ONE JSON array — the modified
-    candidate list (reorder / filter / replace allowed). Template:
-    [
-      {"provider": "claude", "model": "sonnet",  "effort": "high",  "rank": 1},
-      {"provider": "codex",  "model": "gpt-5.5", "effort": "xhigh", "rank": 2}
-    ]
-    Valid providers: claude, codex. Valid models: haiku, sonnet, opus, opus-4-8, fable (claude);
-    gpt-5.5 (codex). Valid efforts: haiku -> "none" only; sonnet -> medium|high|xhigh|max;
-    fable -> medium|high|xhigh|max; opus/opus-4-8 -> those plus ultracode; gpt-5.5 -> medium|high|xhigh.
-    "rank" on output is ignored. An EMPTY array vetoes the launch. Anything else
-    invalid fails the launch hard — the server validates strictly.
-
-(c) INPUT CONTRACT (routing mode, invoked as: <python> advanced-ruleset.py route):
-    stdin receives one JSON object:
-    { "candidates": [ {"provider","model","effort","rank"} ... ],   # rank 1..N best->worst
-      "context": { "task_category": str, "cwd": str,
-                   "selection_mode": "auto"|"provider"|"provider_model"|"explicit",
-                   "provider": str|None, "model": str|None, "effort": str|None } }
-    OS environment variables are visible natively (os.environ).
-
-ENV-CHECK MODE (no arguments): prints {"ready": true|false, "load-rules": true|false}.
-Runs once per MCP server process. load-rules false => ruleset silently disabled
-for the rest of the process. Set LOAD_RULES = True below to activate.
-"""
-import json
-import sys
-
-LOAD_RULES = False
-
-# --- Requirements stub (scaffold itself is stdlib-only) ----------------------
-# List third-party distributions your rules import, e.g.:
-# REQUIREMENTS = ["requests", "pyyaml"]
-# Install with:  <python> -m pip install <name> ...
-REQUIREMENTS = []
-
-def missing_requirements():
-    """pip-check helper: returns the REQUIREMENTS entries not importable here."""
-    import importlib.util
-    return [r for r in REQUIREMENTS
-            if importlib.util.find_spec(r.replace("-", "_")) is None]
-
-def env_check():
-    missing = missing_requirements()
-    json.dump({"ready": not missing, "load-rules": bool(LOAD_RULES)}, sys.stdout)
-
-def apply_rules(candidates, context):
-    """YOUR RULES HERE. Default: passthrough (returns the list unchanged)."""
-    return candidates
-
-def route():
-    payload = json.load(sys.stdin)
-    out = apply_rules(payload.get("candidates", []), payload.get("context", {}))
-    json.dump(out, sys.stdout)
-
-if __name__ == "__main__":
-    if len(sys.argv) > 1 and sys.argv[1] == "route":
-        route()
-    else:
-        env_check()
+#!/usr/bin/env python3
+"""advanced-ruleset.py — final-authority model-routing override hook for subagent-mcp.
+
+(a) PERFORMANCE WARNING: this script runs synchronously inside EVERY launch_agent
+    call. Slow rules slow every agent launch. Keep rules lean and low-latency —
+    no network calls, no heavy imports at module top. This is YOUR responsibility;
+    you have been warned.
+
+(b) OUTPUT CONTRACT (routing mode): print to stdout ONE JSON array — the modified
+    candidate list (reorder / filter / replace allowed). Template:
+    [
+      {"provider": "claude", "model": "sonnet",  "effort": "high",  "rank": 1},
+      {"provider": "codex",  "model": "gpt-5.5", "effort": "xhigh", "rank": 2}
+    ]
+    Valid providers: claude, codex. Valid models: haiku, sonnet, opus, opus-4-8, fable (claude);
+    gpt-5.5 (codex). Valid efforts: haiku -> "none" only; sonnet -> medium|high|xhigh|max;
+    fable -> medium|high|xhigh|max; opus/opus-4-8 -> those plus ultracode; gpt-5.5 -> medium|high|xhigh.
+    "rank" on output is ignored. An EMPTY array vetoes the launch. Anything else
+    invalid fails the launch hard — the server validates strictly.
+
+(c) INPUT CONTRACT (routing mode, invoked as: <python> advanced-ruleset.py route):
+    stdin receives one JSON object:
+    { "candidates": [ {"provider","model","effort","rank"} ... ],   # rank 1..N best->worst
+      "context": { "task_category": str, "cwd": str,
+                   "selection_mode": "auto"|"provider"|"provider_model"|"explicit",
+                   "provider": str|None, "model": str|None, "effort": str|None } }
+    OS environment variables are visible natively (os.environ).
+
+ENV-CHECK MODE (no arguments): prints {"ready": true|false, "load-rules": true|false}.
+Runs once per MCP server process. load-rules false => ruleset silently disabled
+for the rest of the process. Set LOAD_RULES = True below to activate.
+"""
+import json
+import sys
+
+LOAD_RULES = False
+
+# --- Requirements stub (scaffold itself is stdlib-only) ----------------------
+# List third-party distributions your rules import, e.g.:
+# REQUIREMENTS = ["requests", "pyyaml"]
+# Install with:  <python> -m pip install <name> ...
+REQUIREMENTS = []
+
+def missing_requirements():
+    """pip-check helper: returns the REQUIREMENTS entries not importable here."""
+    import importlib.util
+    return [r for r in REQUIREMENTS
+            if importlib.util.find_spec(r.replace("-", "_")) is None]
+
+def env_check():
+    missing = missing_requirements()
+    json.dump({"ready": not missing, "load-rules": bool(LOAD_RULES)}, sys.stdout)
+
+def apply_rules(candidates, context):
+    """YOUR RULES HERE. Default: passthrough (returns the list unchanged)."""
+    return candidates
+
+def route():
+    payload = json.load(sys.stdin)
+    out = apply_rules(payload.get("candidates", []), payload.get("context", {}))
+    json.dump(out, sys.stdout)
+
+if __name__ == "__main__":
+    if len(sys.argv) > 1 and sys.argv[1] == "route":
+        route()
+    else:
+        env_check()

package/dist/concurrency.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir, platform, userInfo } from "node:os";
 import { dirname, join, parse as parsePath, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -26,7 +26,50 @@ export function clampCap(raw) {
     return v;
 }
 export function stripJsoncComments(text) {
-    return text.replace(/^\uFEFF/, "").replace(/^\s*\/\/.*$/gm, "");
+    let out = "";
+    let inString = false;
+    let quote = null;
+    let escaped = false;
+    for (let i = text.startsWith("\uFEFF") ? 1 : 0; i < text.length; i++) {
+        const ch = text[i];
+        const next = text[i + 1];
+        if (inString) {
+            out += ch;
+            if (escaped) {
+                escaped = false;
+            }
+            else if (ch === "\\") {
+                escaped = true;
+            }
+            else if (ch === quote) {
+                inString = false;
+                quote = null;
+            }
+            continue;
+        }
+        if (ch === "\"" || ch === "'") {
+            inString = true;
+            quote = ch;
+            out += ch;
+            continue;
+        }
+        if (ch === "/" && next === "/") {
+            while (i < text.length && text[i] !== "\n" && text[i] !== "\r")
+                i++;
+            i--;
+            continue;
+        }
+        if (ch === "/" && next === "*") {
+            i += 2;
+            while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
+                i++;
+            if (i < text.length)
+                i++;
+            continue;
+        }
+        out += ch;
+    }
+    return out;
 }
 function parseJsonObject(text) {
     const parsed = JSON.parse(stripJsoncComments(text));
@@ -591,6 +634,74 @@ export function countSlots(dir = slotDir()) {
         return 0;
     }
 }
+function slotPathForIndex(dir, index) {
+    return join(dir, `slot-${index}.json`);
+}
+function slotMetadataJson(agentId) {
+    const now = Date.now();
+    return JSON.stringify({
+        schema_version: 1,
+        agent_id: agentId,
+        server_pid: process.pid,
+        child_pid: null,
+        cwd: process.cwd(),
+        started_at: new Date(now).toISOString(),
+        started_at_ms: now,
+        last_activity_ms: now,
+        status: null,
+    });
+}
+function claimSlotPath(dir, agentId, max) {
+    let existing;
+    try {
+        existing = readdirSync(dir).filter((f) => f.startsWith("slot-"));
+    }
+    catch {
+        existing = [];
+    }
+    if (existing.length >= max)
+        return null;
+    const occupied = new Set(existing);
+    const candidateCount = max - existing.length;
+    const candidates = [];
+    for (let i = 0; i < max && candidates.length < candidateCount; i++) {
+        const name = `slot-${i}.json`;
+        if (!occupied.has(name))
+            candidates.push(slotPathForIndex(dir, i));
+    }
+    for (const path of candidates) {
+        let fd = null;
+        try {
+            fd = openSync(path, "wx", 0o600);
+            writeFileSync(fd, slotMetadataJson(agentId));
+            return path;
+        }
+        catch (e) {
+            if (fd !== null) {
+                try {
+                    closeSync(fd);
+                }
+                catch { }
+                fd = null;
+                try {
+                    unlinkSync(path);
+                }
+                catch { }
+            }
+            if (e.code !== "EEXIST")
+                throw e;
+        }
+        finally {
+            if (fd !== null) {
+                try {
+                    closeSync(fd);
+                }
+                catch { }
+            }
+        }
+    }
+    return null;
+}
 export function scheduleForceKill(ms, kill) {
     const timer = setTimeout(kill, ms);
     timer.unref();
@@ -608,21 +719,11 @@ export function reserveSlot(agentId, max, dir = slotDir(), cullDeps) {
             mkdirSync(dir, { recursive: true, mode: 0o700 });
         }
         cullStaleSlots(dir, cullDeps);
-        const slotPath = slotPathForAgent(dir, agentId);
-        const before = countSlots(dir);
-        if (before >= max) {
-            return { ok: false, current: before, max };
-        }
-        // ponytail: count->write->recount narrows the TOCTOU; a cross-process lock would close it fully.
-        writeSlotMetadata(slotPath, { agent_id: agentId });
-        const after = countSlots(dir);
-        if (after > max) {
-            try {
-                unlinkSync(slotPath);
-            }
-            catch { }
+        // ponytail: numbered O_EXCL slot claims make admission atomic without queues or a process-wide lock.
+        const slotPath = claimSlotPath(dir, agentId, max);
+        if (!slotPath)
             return { ok: false, current: countSlots(dir), max };
-        }
+        const after = countSlots(dir);
         return { ok: true, slotPath, current: after, max };
     }
     catch (e) {

package/dist/config-scaffold.js

@@ -1,2 +1,2 @@
 // GENERATED by scripts/gen-ruleset-scaffold.mjs from src/global-subagent-mcp-config.jsonc — DO NOT EDIT.
-export const CONCURRENCY_SCAFFOLD = "// subagent-mcp - Global Subagent MCP Config\r\n// ------------------------------------------------------------------\r\n// SOLE source of truth for machine-wide subagent-mcp defaults that must be\r\n// available beside the compiled server.\r\n//\r\n// globalConcurrentSubagents controls how many subagents may be ALIVE AT ONCE\r\n// across EVERY session, process, and user on this machine. There is NO\r\n// environment-variable override for the cap.\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// Cap value rules:\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// checkForUpdates controls the silent npmjs update check started when the MCP\r\n// server connects. Default true. Set to false to skip the registry fetch and\r\n// suppress hook notices. SUBAGENT_UPDATE_CHECK=0 or false also disables it.\r\n//\r\n// permissionsCeiling controls launch-time permissions posture:\r\n//   - auto   (default): shared engine gates unsafe/residue actions\r\n//   - manual: human approval for residue while still auto-denying DANGER\r\n//   - yolo:  preserve the historical bypass/danger-full-access path, except\r\n//            for non-bypassable config-file self-protection\r\n//\r\n// escalation applies only in auto mode. irreversible-only routes irreversible\r\n// NEUTRAL residue to a human; off leaves residue to orchestrator judgment.\r\n//\r\n// strictReadParity controls logging only. Unparseable Codex approval payloads\r\n// always fail closed to ask; warn logs the construct, off silences that log.\r\n//\r\n// sandboxNetwork controls Codex workspace-write network access. Default false.\r\n// Set true only when sub-agents need network after permission approval.\r\n{\r\n  \"globalConcurrentSubagents\": 20,\r\n  \"checkForUpdates\": true,\r\n  \"permissionsCeiling\": \"auto\",\r\n  \"escalation\": \"irreversible-only\",\r\n  \"strictReadParity\": \"warn\",\r\n  \"sandboxNetwork\": false\r\n}\r\n";
+export const CONCURRENCY_SCAFFOLD = "// subagent-mcp - Global Subagent MCP Config\n// ------------------------------------------------------------------\n// SOLE source of truth for machine-wide subagent-mcp defaults that must be\n// available beside the compiled server.\n//\n// globalConcurrentSubagents controls how many subagents may be ALIVE AT ONCE\n// across EVERY session, process, and user on this machine. There is NO\n// environment-variable override for the cap.\n//\n// RE-READ on every launch_agent call - edits take effect immediately, no\n// server restart required.\n//\n// Cap value rules:\n//   - missing / unset / non-integer / 0 / negative -> reset to default 20\n//   - 1 through 9                                  -> forced UP to minimum 10\n//   - 10 or greater                                -> used as-is\n//\n// checkForUpdates controls the silent npmjs update check started when the MCP\n// server connects. Default true. Set to false to skip the registry fetch and\n// suppress hook notices. SUBAGENT_UPDATE_CHECK=0 or false also disables it.\n//\n// permissionsCeiling controls launch-time permissions posture:\n//   - auto   (default): shared engine gates unsafe/residue actions\n//   - manual: human approval for residue while still auto-denying DANGER\n//   - yolo:  preserve the historical bypass/danger-full-access path, except\n//            for non-bypassable config-file self-protection\n//\n// escalation applies only in auto mode. irreversible-only routes irreversible\n// NEUTRAL residue to a human; off leaves residue to orchestrator judgment.\n//\n// strictReadParity controls logging only. Unparseable Codex approval payloads\n// always fail closed to ask; warn logs the construct, off silences that log.\n//\n// sandboxNetwork controls Codex workspace-write network access. Default false.\n// Set true only when sub-agents need network after permission approval.\n{\n  \"globalConcurrentSubagents\": 20,\n  \"checkForUpdates\": true,\n  \"permissionsCeiling\": \"auto\",\n  \"escalation\": \"irreversible-only\",\n  \"strictReadParity\": \"warn\",\n  \"sandboxNetwork\": false\n}\n";