@heretyc/subagent-mcp 2.9.2 → 2.10.1

package/dist/index.js

@@ -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, NONBLOCKING_CULL_DEPS, ZOMBIE_FORCE_GRACE_MS, ZOMBIE_LIVE_IDLE_MS, ZOMBIE_TERMINAL_IDLE_MS, buildProcessTreeKillCommands, drainZombieIntents, drainZombieReports, defaultConfigPath, globalCapMessage, readSlotMetadata, readGlobalCap, releaseSlot, reserveSlot, slotDir, writeSlotMetadata, } from "./concurrency.js";
 import * as orchestrationMarker from "./orchestration/marker.js";
 import * as modelMode from "./orchestration/model-mode.js";
 import { startLivenessHeartbeat } from "./orchestration/liveness.js";
@@ -53,6 +54,189 @@ const TASK_CATEGORY_GLOSS = "REQUIRED. Task shape -> routing category (server pi
 function errorResult(text) {
     return { content: [{ type: "text", text }], isError: true };
 }
+function envDuration(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === "")
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isInteger(parsed) && parsed >= 0 ? parsed : fallback;
+}
+function zombieLiveIdleMs() {
+    return envDuration("SUBAGENT_ZOMBIE_LIVE_IDLE_MS", ZOMBIE_LIVE_IDLE_MS);
+}
+function zombieTerminalIdleMs() {
+    return envDuration("SUBAGENT_ZOMBIE_TERMINAL_IDLE_MS", ZOMBIE_TERMINAL_IDLE_MS);
+}
+function zombieForceGraceMs() {
+    return envDuration("SUBAGENT_ZOMBIE_FORCE_GRACE_MS", ZOMBIE_FORCE_GRACE_MS);
+}
+function zombieReport(records) {
+    const ids = Array.from(new Set(records.map((r) => r.agent_id))).filter(Boolean);
+    return ids.length > 0 ? `zombies: ${ids.join(",")}` : undefined;
+}
+function withZombieReport(result, records) {
+    const report = zombieReport(records);
+    if (!report || !result.content?.[0] || result.content[0].type !== "text")
+        return result;
+    const text = result.content[0].text;
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            parsed.zombie_report = report;
+            result.content[0].text = JSON.stringify(parsed, null, text.includes("\n") ? 2 : undefined);
+            return result;
+        }
+    }
+    catch { }
+    result.content[0].text = `${text}\n${report}`;
+    return result;
+}
+function updateSlotMetadata(agent) {
+    if (!agent.slotPath)
+        return;
+    writeSlotMetadata(agent.slotPath, {
+        agent_id: agent.id,
+        server_pid: process.pid,
+        child_pid: agent.process.pid ?? null,
+        cwd: agent.cwd,
+        started_at: new Date(agent.startedAt).toISOString(),
+        started_at_ms: agent.startedAt,
+        last_activity_ms: agent.lastActivity,
+        status: agent.status,
+    });
+}
+function spawnProcessTreeKill(pid, force) {
+    const commands = buildProcessTreeKillCommands(pid);
+    const command = force ? commands.force : commands.graceful;
+    try {
+        const child = spawn(command.command, command.args, {
+            stdio: "ignore",
+            windowsHide: true,
+            detached: false,
+        });
+        child.unref();
+    }
+    catch { }
+}
+function scheduleZombieForceKill(agent) {
+    const pid = agent.process.pid;
+    if (!pid || agent.driver.closed)
+        return;
+    const timer = setTimeout(() => {
+        if (!agent.driver.closed && agent.status === "zombie_killed") {
+            try {
+                agent.driver.kill();
+            }
+            catch { }
+            spawnProcessTreeKill(pid, true);
+        }
+    }, zombieForceGraceMs());
+    timer.unref();
+}
+function markZombieKilled(agent, reason, now) {
+    agent.status = "zombie_killed";
+    agent.exitCode = agent.exitCode ?? -1;
+    agent.exitedAt = agent.exitedAt ?? now;
+    agent.waitReported = false;
+    releaseSlot(agent.slotPath ?? null);
+    const slotPath = agent.slotPath ?? "";
+    agent.slotPath = null;
+    const pid = agent.process.pid ?? null;
+    const record = {
+        kind: "zombie_killed",
+        agent_id: agent.id,
+        child_pid: pid,
+        server_pid: process.pid,
+        slot_path: slotPath,
+        reason,
+        detected_at_ms: now,
+        last_activity_ms: agent.lastActivity,
+        message: `zombies: culled ${agent.id}`,
+    };
+    if (pid && !agent.driver.closed) {
+        if (reason === "terminal_but_alive") {
+            try {
+                agent.driver.kill();
+            }
+            catch { }
+            spawnProcessTreeKill(pid, true);
+        }
+        else {
+            spawnProcessTreeKill(pid, false);
+            scheduleZombieForceKill(agent);
+        }
+    }
+    return record;
+}
+function applyZombieRecord(record, now) {
+    const agent = agents.get(record.agent_id);
+    if (!agent || agent.status === "zombie_killed")
+        return null;
+    agent.status = "zombie_killed";
+    agent.exitCode = agent.exitCode ?? -1;
+    agent.exitedAt = agent.exitedAt ?? now;
+    agent.waitReported = false;
+    releaseSlot(agent.slotPath ?? null);
+    agent.slotPath = null;
+    try {
+        if (!agent.driver.closed)
+            agent.driver.kill();
+    }
+    catch { }
+    return { ...record, detected_at_ms: record.detected_at_ms || now };
+}
+function runToolMaintenance() {
+    const now = Date.now();
+    const records = [];
+    const applied = new Set();
+    for (const record of [...drainZombieIntents(slotDir()), ...drainZombieReports(slotDir())]) {
+        if (applied.has(record.agent_id))
+            continue;
+        const appliedRecord = applyZombieRecord(record, now);
+        if (appliedRecord) {
+            records.push(appliedRecord);
+            applied.add(record.agent_id);
+        }
+    }
+    for (const agent of agents.values()) {
+        if (agent.status === "zombie_killed")
+            continue;
+        reconcileAgent(agent, now);
+        const slotMeta = agent.slotPath ? readSlotMetadata(agent.slotPath) : null;
+        if (slotMeta?.last_activity_ms !== null && slotMeta?.last_activity_ms !== undefined) {
+            agent.lastActivity = Math.min(agent.lastActivity, slotMeta.last_activity_ms);
+        }
+        const live = agent.status === "processing" || agent.status === "stalled";
+        if (live && now - agent.lastActivity > zombieLiveIdleMs()) {
+            const record = markZombieKilled(agent, "stale_live", now);
+            records.push(record);
+            applied.add(agent.id);
+            continue;
+        }
+        const terminalButAlive = (agent.status === "finished" || agent.status === "errored" || agent.status === "stopped") &&
+            !agent.driver.closed &&
+            agent.exitedAt !== null &&
+            now - agent.exitedAt > zombieTerminalIdleMs();
+        if (terminalButAlive) {
+            const record = markZombieKilled(agent, "terminal_but_alive", now);
+            records.push(record);
+            applied.add(agent.id);
+            continue;
+        }
+        updateSlotMetadata(agent);
+    }
+    return records;
+}
+function withMaintenance(handler) {
+    return async (params) => {
+        const zombieRecords = runToolMaintenance();
+        const result = await handler(params, zombieRecords);
+        if (result && typeof result === "object" && "content" in result) {
+            return withZombieReport(result, zombieRecords);
+        }
+        return result;
+    };
+}
 export function classifyFailureReason(reason, stderr) {
     const text = `${reason}\n${stderr}`;
     return /\b429\b|\b5\d{2}\b|quota|usage.?cap|rate.?limit|timeout|connection.?reset|ECONNRESET|ETIMEDOUT|ECONNREFUSED|too many requests|service unavailable|server error|overloaded/i.test(text)
@@ -143,7 +327,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.1",
     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"
@@ -313,6 +497,7 @@ async function tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rule
                 // Heartbeat refreshes only on parsed visible provider stream items,
                 // not on raw stdout bytes.
                 agentState.lastActivity = at;
+                updateSlotMetadata(agentState);
                 agentState.visibleStream = retainLastN(agentState.visibleStream, items.map((it) => ({ ...it, at })), 3);
             }
             // Provider completion events mark the current turn finished while the
@@ -359,9 +544,16 @@ 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();
+        if (agentState.status === "zombie_killed") {
+            if (agentState.exitCode === null)
+                agentState.exitCode = code !== null ? code : -1;
+            return;
+        }
         if (agentState.status === "stopped") {
             // Record real exit code but preserve "stopped" status
             if (agentState.exitCode === null)
@@ -500,7 +692,7 @@ server.tool("launch_agent", "Spawn a sub-agent session. AUTO MODE (mandatory fir
     effort: z.enum(["medium", "high", "xhigh", "max", "ultracode"]).optional(),
     cwd: z.string().optional(),
     deadlock: z.boolean().optional().describe("MANDATE: ALWAYS set deadlock=true when, and ONLY when, 2 launch attempts for the SAME atomic task have already failed or been unsatisfactory — the 3rd attempt onward. Re-wording the prompt does NOT make it a different task; splitting a failed task does NOT reset attempts for its unchanged parts; re-launching for the same deliverable means the prior attempt COUNTS as failed/unsatisfactory ('partial progress' is not an exemption). NEVER set it on a 1st or 2nd attempt, NEVER for a different task, NEVER speculatively. Auto mode only: cannot be combined with provider/model/effort — from the 3rd attempt deadlock outranks any capability override, so drop those params. Passing false is identical to omitting it."),
-}, async (params) => {
+}, withMaintenance(async (params) => {
     const { task_category, provider, model, effort, deadlock } = params;
     // D19/D20/S8: server silently upserts the parent-process marker as the TRUE
     // first line of every sub-agent prompt (idempotent; never duplicates; never
@@ -599,69 +791,95 @@ 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, slotDir(), NONBLOCKING_CULL_DEPS);
+    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;
+                    updateSlotMetadata(registeredAgent);
+                    // 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
@@ -678,12 +896,12 @@ server.tool("launch_agent", "Spawn a sub-agent session. AUTO MODE (mandatory fir
         .map((s, i) => `  ${i + 1}. ${s.model}@${s.effort} (${s.provider}) [${s.failure_type}]: ${s.reason}`)
         .join("\n");
     return errorResult(`Error: all ${skipped.length} candidate launches failed for task_category ${task_category}:\n${lines}\n${SPLIT_HINT}\n${AUTO_HINT}`);
-});
+}));
 // Tool 2: poll_agent
 server.tool("poll_agent", "Get an agent's current status and output. Status `processing` = ALIVE with visible provider activity in the last 10 minutes; `stalled` = ALIVE but no parsed visible provider stream item for 10 minutes (thinking, or awaiting a temp-file handoff) — NOT dead, so prefer `wait`/re-poll over killing. Always returns `alive` and `idle_seconds`, plus `recent_stream` (the last 3 visible provider stream items, each timestamped) and a `hint` while stalled. Pass `verbose: true` to also return `final_output`, the agent's final assistant turn extracted from its captured stdout.", {
     agent_id: z.string(),
     verbose: z.boolean().optional().default(false),
-}, async (params) => {
+}, withMaintenance(async (params) => {
     const agent = agents.get(params.agent_id);
     if (!agent) {
         return {
@@ -748,11 +966,11 @@ server.tool("poll_agent", "Get an agent's current status and output. Status `pro
             },
         ],
     };
-});
+}));
 // Tool 3: kill_agent
 server.tool("kill_agent", "Terminate a live agent/session (status `processing`, `stalled`, or turn-finished but still interactive) by immediately force-killing its managed driver. No-op for already-terminal closed agents.", {
     agent_id: z.string(),
-}, async (params) => {
+}, withMaintenance(async (params) => {
     const agent = agents.get(params.agent_id);
     if (!agent) {
         return {
@@ -790,6 +1008,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,
@@ -826,12 +1046,12 @@ server.tool("kill_agent", "Terminate a live agent/session (status `processing`,
             isError: true,
         };
     }
-});
+}));
 // Tool 4: send_message
 server.tool("send_message", "Enqueue a user message for an open interactive agent session. Observe output with poll_agent or wait.", {
     agent_id: z.string(),
     message: z.string().min(1),
-}, async (params) => {
+}, withMaintenance(async (params) => {
     const agent = agents.get(params.agent_id);
     if (!agent) {
         return {
@@ -866,6 +1086,7 @@ server.tool("send_message", "Enqueue a user message for an open interactive agen
         agent.waitReported = false;
         agent.turnCompleted = false;
         agent.lastActivity = now;
+        updateSlotMetadata(agent);
         return {
             content: [
                 {
@@ -891,9 +1112,9 @@ server.tool("send_message", "Enqueue a user message for an open interactive agen
             isError: true,
         };
     }
-});
+}));
 // Tool 5: list_agents
-server.tool("list_agents", "List all agents with token-efficient core metrics (status, `alive`, `idle_seconds`). `stalled` is ALIVE-but-quiet, NOT dead (full status semantics on poll_agent). Use `poll_agent` for per-agent stream items, hints, and final output.", {}, async () => {
+server.tool("list_agents", "List all agents with token-efficient core metrics (status, `alive`, `idle_seconds`). `stalled` is ALIVE-but-quiet, NOT dead (full status semantics on poll_agent). Use `poll_agent` for per-agent stream items, hints, and final output.", {}, withMaintenance(async () => {
     const now = Date.now();
     const agentList = Array.from(agents.values()).map((agent) => {
         // Reconcile exit synchronously so already-exited processes are reported
@@ -920,11 +1141,11 @@ server.tool("list_agents", "List all agents with token-efficient core metrics (s
             },
         ],
     };
-});
+}));
 // Tool 6: wait
-server.tool("wait", "Blocks until one or more sub-agents reach a reportable state (turn-finished, errored, or stopped), returning exit code when known + local-time timestamp; or returns the live-job list after a 15-minute timeout. A `finished` agent can still be alive and accept `send_message` when exit_code is null. A `stalled` agent is still ALIVE and does NOT end the wait. Pass `verbose: true` to add each finished agent's `final_output`.", {
+server.tool("wait", "Blocks until one or more sub-agents reach a reportable state (turn-finished, errored, stopped, or zombie_killed), returning exit code when known + local-time timestamp; or returns the live-job list after a 15-minute timeout. A `finished` agent can still be alive and accept `send_message` when exit_code is null. A `stalled` agent is still ALIVE and does NOT end the wait. Pass `verbose: true` to add each finished agent's `final_output`.", {
     verbose: z.boolean().optional().default(false),
-}, async (params) => {
+}, withMaintenance(async (params) => {
     const { verbose } = params;
     const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
     const TIMEOUT_MS = 15 * 60 * 1000;
@@ -964,7 +1185,7 @@ server.tool("wait", "Blocks until one or more sub-agents reach a reportable stat
     }
     // Step 2: nothing alive and nothing unreported (includes stopped-but-not-yet-closed).
     // `stalled` is a LIVE state — it keeps the wait pending, it never ends it.
-    const TERMINAL_SET = new Set(["finished", "errored", "stopped"]);
+    const TERMINAL_SET = new Set(["finished", "errored", "stopped", "zombie_killed"]);
     const hasPending = Array.from(agents.values()).some((a) => a.status === "processing" ||
         a.status === "stalled" ||
         (TERMINAL_SET.has(a.status) && a.exitedAt === null));
@@ -1002,11 +1223,11 @@ server.tool("wait", "Blocks until one or more sub-agents reach a reportable stat
     return {
         content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
     };
-});
+}));
 // Tool 7: orchestration-mode
 server.tool("orchestration-mode", "Toggle or query per-project ORCHESTRATION MODE. `enabled`: true = ON, false = OFF for THIS session only, omit = query current state. SOLE CHANNEL: the subagent MCP is the ONLY sanctioned channel for launching sub-agents whether this mode is ON or OFF — toggling OFF does not lift that obligation. When OFF, run the per-turn upgrade check: a long-horizon task = any whose TOTAL context footprint (input read + output produced) exceeds 200 lines, measured CUMULATIVELY since your last upgrade ask; after EVERY user turn, if it qualifies, STOP and ask the user whether to remain enabled (ask every qualifying turn; a decline does not latch; reset the count only when you actually ask). The FULL operating model + governance is carried in this server's MCP `instructions` (read once at initialize) — this is the operational summary only; do not act on the mode without that detail. WHAT: a default-ON orchestration mode for LONG-HORIZON work that would fill the context window if run to completion inline; when ON, act as a delegate-ONLY orchestrator: delegate every step; inline-by-right does not exist; a non-delegable atomic step requires a one-time user-approved exception via the structured-question tool (state which + why). PERSISTENCE: orchestration is DEFAULT ON; a permitted disable applies to THIS session only, resumes ON next new session (or after the 2h backstop), and cannot be re-enabled mid-session. CARRYOVER: if ON was inherited from a PRIOR session (provenance = carried-over, not user-enabled this session), the bundled hook prepends a ONE-TIME notice (once per marker, never per turn) — you MUST then notify the user it auto-activated and confirm whether to keep it ON. DISABLE: never on your own initiative; you MAY PROPOSE turning it OFF on task-fit mismatch, but only EXPLICIT user permission (AskUserQuestion on Claude, request-user-input on Codex) may set enabled:false. Per-turn injection fires only in CLI hosts that load the bundled hook; desktop hosts toggle the marker but inject nothing (documented degradation).", {
     enabled: z.boolean().optional(),
-}, async (params) => {
+}, withMaintenance(async (params) => {
     const cwd = process.cwd();
     const key = orchestrationMarker.readCurrentSession(cwd);
     if (params.enabled === true) {
@@ -1054,11 +1275,11 @@ server.tool("orchestration-mode", "Toggle or query per-project ORCHESTRATION MOD
             },
         ],
     };
-});
+}));
 // Tool 8: model-selection-mode
 server.tool("model-selection-mode", "Set or query per-project MODEL SELECTION MODE, which gates launch_agent's `provider`/`model`/`effort` selectors. `mode`: \"smart\" or \"user-approved-overrides\"; omit to query current state. \"smart\" is the DEFAULT and is used whenever the mode is unset — in smart, launch_agent REJECTS any call that supplies provider/model/effort and the server auto-picks the best model for the task_category. \"user-approved-overrides\" opens a 30-MINUTE window during which selectors are HONORED; the window is enforced LAZILY — the mode reverts to smart on the next launch_agent call after the 30 minutes elapse — and re-enabling does NOT extend an already-active window. HONOR-BASED, parallel to orchestration-mode: you MUST NOT set this to \"user-approved-overrides\" without explicit interactive USER authorization obtained via the structured-question tool (AskUserQuestion on Claude / request-user-input on Codex; a plain yes/no exchange if neither exists). This tool CANNOT verify that authorization — never enable it on your own initiative. PERSISTENCE: per-project state keyed by cwd; both the mode and the override-window enable-timestamp persist across MCP server restarts (the remaining window is restored, not reset).", {
     mode: z.enum(["smart", "user-approved-overrides"]).optional(),
-}, async (params) => {
+}, withMaintenance(async (params) => {
     const cwd = process.cwd();
     if (params.mode)
         modelMode.setMode(cwd, params.mode);
@@ -1076,7 +1297,7 @@ server.tool("model-selection-mode", "Set or query per-project MODEL SELECTION MO
             },
         ],
     };
-});
+}));
 // Connect the stdio transport only when run as the entry point (the bin), NOT
 // when this module is imported (e.g. test/handler-validation.test.mjs importing
 // the exported validatePresence). Connecting on import would block the test on
@@ -1116,7 +1337,17 @@ if (isMain) {
     }
     if (arg === "update" || arg === "--update") {
         const pkg = readPkg();
-        const npmArgs = ["install", "-g", `${pkg.name}@latest`];
+        const scope = pkg.name.startsWith("@") ? pkg.name.split("/")[0] : null;
+        const npmjsRegistryArgs = [
+            "--registry=https://registry.npmjs.org",
+            ...(scope ? [`--${scope}:registry=https://registry.npmjs.org`] : []),
+        ];
+        const npmArgs = [
+            "install",
+            "-g",
+            ...npmjsRegistryArgs,
+            `${pkg.name}@latest`,
+        ];
         console.log(`subagent-mcp ${pkg.version} -> npm ${npmArgs.join(" ")}`);
         // npm on Windows is npm.cmd; spawning a .cmd without a shell fails
         // (EINVAL on modern Node). Resolve the underlying npm-cli.js and run it
@@ -1154,7 +1385,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 +1400,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 +1434,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/orchestration/hook-core.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import * as marker from "./marker.js";
 import * as reminder from "./reminder.js";
+import { cullStaleSlots, slotDir, ZOMBIE_FORCE_GRACE_MS, } from "../concurrency.js";
 /**
  * Provider-agnostic core of the UserPromptSubmit / SessionStart hook.
  *
@@ -210,6 +211,35 @@ export function claimAndEmit(cwd, current, turn, m, kind, env, adapter) {
         ? readDirective(env, adapter.carryoverDirectiveFile) + full
         : full;
 }
+function hookCullDeps(env = process.env) {
+    return {
+        forceGraceMs: () => {
+            const raw = env.SUBAGENT_ZOMBIE_FORCE_GRACE_MS;
+            if (raw === undefined || raw === "")
+                return ZOMBIE_FORCE_GRACE_MS;
+            const parsed = Number.parseInt(raw, 10);
+            return Number.isInteger(parsed) && parsed >= 0 ? parsed : ZOMBIE_FORCE_GRACE_MS;
+        },
+    };
+}
+export function cullHookZombies(deps = hookCullDeps()) {
+    try {
+        return cullStaleSlots(slotDir(), deps);
+    }
+    catch {
+        return [];
+    }
+}
+export function hookZombieReportText(records) {
+    const ids = Array.from(new Set(records.map((r) => r.agent_id))).filter(Boolean);
+    return ids.length > 0 ? `zombies: ${ids.join(",")}` : "";
+}
+export function appendHookZombieReport(out, records) {
+    const report = hookZombieReportText(records);
+    if (!report)
+        return out;
+    return out ? `${out}\n${report}` : report;
+}
 /**
  * Core hook logic. Returns the string to inject, or '' to inject nothing.
  *
@@ -229,8 +259,9 @@ export function claimAndEmit(cwd, current, turn, m, kind, env, adapter) {
  */
 export function runHook(payload, env, adapter) {
     try {
+        const zombieRecords = cullHookZombies();
         if (adapter.isSubagent(payload, env)) {
-            return "";
+            return appendHookZombieReport("", zombieRecords);
         }
         const cwd = payload.cwd || process.cwd();
         const current = sessionKey(payload);
@@ -239,17 +270,17 @@ export function runHook(payload, env, adapter) {
         if (!marker.isActive(cwd, current)) {
             // OFF: no claim machinery — just the per-prompt reminder cadence.
             const r = reminder.advance(cwd, current);
-            return cadenceEmit(env, adapter, adapter.reminderOffFile, adapter.shortOffFile, r.count, r.persisted);
+            return appendHookZombieReport(cadenceEmit(env, adapter, adapter.reminderOffFile, adapter.shortOffFile, r.count, r.persisted), zombieRecords);
         }
         const m = marker.readMarker(cwd);
         const kind = classifyClaim(m.owner_session, m.baseline_turn, current);
         if (kind === "fresh" || kind === "carryover") {
             const turn = adapter.currentTurn(payload.transcript_path);
-            return claimAndEmit(cwd, current, turn, m, kind, env, adapter);
+            return appendHookZombieReport(claimAndEmit(cwd, current, turn, m, kind, env, adapter), zombieRecords);
         }
         // SAME-SESSION: per-prompt reminder cadence, ON variant.
         const r = reminder.advance(cwd, current);
-        return cadenceEmit(env, adapter, adapter.reminderOnFile, adapter.shortOnFile, r.count, r.persisted);
+        return appendHookZombieReport(cadenceEmit(env, adapter, adapter.reminderOnFile, adapter.shortOnFile, r.count, r.persisted), zombieRecords);
     }
     catch {
         // Any failure -> inject nothing. Never crash or stall the host turn.