@heretyc/subagent-mcp 2.10.0 → 2.10.1

package/dist/index.js

@@ -18,7 +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 { 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";
@@ -54,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)
@@ -144,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.10.0",
+    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"
@@ -314,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
@@ -365,6 +549,11 @@ async function tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rule
         // 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)
@@ -503,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
@@ -604,7 +793,7 @@ server.tool("launch_agent", "Spawn a sub-agent session. AUTO MODE (mandatory fir
     //    advance on launch-time failure. Sub-agent task outcome is NEVER a trigger.
     const cap = readGlobalCap();
     const reservationId = randomUUID();
-    const reservation = reserveSlot(reservationId, cap);
+    const reservation = reserveSlot(reservationId, cap, slotDir(), NONBLOCKING_CULL_DEPS);
     if (!reservation.ok) {
         return errorResult(globalCapMessage(reservation.current, cap, defaultConfigPath()));
     }
@@ -622,6 +811,7 @@ server.tool("launch_agent", "Spawn a sub-agent session. AUTO MODE (mandatory fir
                 const registeredAgent = agents.get(outcome.agentId);
                 if (registeredAgent) {
                     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
@@ -706,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 {
@@ -776,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 {
@@ -856,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 {
@@ -896,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: [
                 {
@@ -921,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
@@ -950,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;
@@ -994,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));
@@ -1032,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) {
@@ -1084,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);
@@ -1106,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
@@ -1146,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

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.

package/dist/orchestration/pretool.js

@@ -1,4 +1,5 @@
 import { serverAlive } from "./liveness.js";
+import { cullHookZombies, hookZombieReportText } from "./hook-core.js";
 const NATIVE_SUBAGENT_TOOLS = new Set(["Task", "Agent", "Explore"]);
 function decision(permissionDecision, permissionDecisionReason, additionalContext) {
     return {
@@ -21,17 +22,21 @@ function decision(permissionDecision, permissionDecisionReason, additionalContex
  */
 export function runClaudePreTool(payload, env, now = Date.now()) {
     try {
+        const zombieReport = hookZombieReportText(cullHookZombies());
         if (env.SUBAGENT_MCP_SUBAGENT === "1")
             return null;
+        const zombieAllowedDecision = zombieReport
+            ? decision("allow", "zombies culled; allowing requested tool.", zombieReport)
+            : null;
         if (!serverAlive(now))
-            return null;
+            return zombieAllowedDecision;
         const tool = typeof payload.tool_name === "string" ? payload.tool_name : "";
         if (!tool)
-            return null;
+            return zombieAllowedDecision;
         if (NATIVE_SUBAGENT_TOOLS.has(tool)) {
-            return decision("deny", "subagent-mcp is alive; harness-native Task/Agent/Explore is not the sanctioned sub-agent channel. Use the subagent-mcp launch_agent MCP tool with the parent-process sentinel as prompt line 1.");
+            return decision("deny", "subagent-mcp is alive; harness-native Task/Agent/Explore is not the sanctioned sub-agent channel. Use the subagent-mcp launch_agent MCP tool with the parent-process sentinel as prompt line 1.", zombieReport || undefined);
         }
-        return null;
+        return zombieAllowedDecision;
     }
     catch {
         return null;

package/dist/status-helpers.js

@@ -9,6 +9,7 @@
 //   finished   - current turn completed, or driver exited 0.
 //   errored    - process exited non-zero.
 //   stopped    - process was killed.
+//   zombie_killed - stale process tree was culled outside the owning server.
 //
 // Liveness is driven by a heartbeat: launch time is the initial heartbeat and
 // every subsequent PARSED visible provider stream item refreshes it (raw
@@ -44,8 +45,7 @@ export function computeStatusTransition(input) {
 // opts in (poll_agent does; list_agents omits it to stay token-efficient).
 export function buildLivenessFields(status, exitCode, lastActivity, now, includeHint = true) {
     const idle_seconds = Math.floor((now - lastActivity) / 1000);
-    const alive = exitCode === null &&
-        (status === "processing" || status === "stalled" || status === "finished");
+    const alive = exitCode === null && (status === "processing" || status === "stalled");
     const fields = { alive, idle_seconds };
     if (status === "stalled" && includeHint) {
         fields.hint =

package/dist/wait-helpers.js

@@ -15,7 +15,7 @@ export function formatLocalIso(ms) {
     const zone = Intl.DateTimeFormat().resolvedOptions().timeZone;
     return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}${sign}${offH}:${offM} (${zone})`;
 }
-const TERMINAL_STATUSES = new Set(["finished", "errored", "stopped"]);
+const TERMINAL_STATUSES = new Set(["finished", "errored", "stopped", "zombie_killed"]);
 export function selectUnreported(list) {
     return list.filter((a) => TERMINAL_STATUSES.has(a.status) && a.exitedAt !== null && !a.waitReported);
 }