claude-dev-env 8.51.4 → 8.52.1

package/_shared/process-tree/scripts/config/process_tree_scripts_constants/process_tree_kill_constants.py

@@ -25,3 +25,15 @@ PROCESS_TREE_KILL_TIMEOUT_SECONDS: int = 10
 Gates the kill command alone. Each caller sets its own bound on the drain that
 follows the kill.
 """
+
+PROCESS_TREE_EXIT_WAIT_SECONDS: float = 2.0
+"""Seconds ``terminate_process_tree`` waits for the signalled POSIX group to exit.
+
+A SIGKILL takes effect when the kernel next schedules each target, so a
+descendant can still run for a moment after ``killpg`` returns. The wait ends
+as soon as no group member is still running; the bound applies only when a
+member survived the signal.
+"""
+
+PROCESS_TREE_EXIT_POLL_SECONDS: float = 0.01
+"""Pause between checks for running members of the signalled process group."""

package/_shared/process-tree/scripts/process_tree_kill.py

@@ -25,6 +25,7 @@ import os
 import signal
 import subprocess
 import sys
+import time
 from pathlib import Path
 
 _config_directory = str(Path(__file__).resolve().parent / "config")
@@ -32,6 +33,8 @@ if _config_directory not in sys.path:
     sys.path.insert(0, _config_directory)
 
 from process_tree_scripts_constants.process_tree_kill_constants import (  # noqa: E402
+    PROCESS_TREE_EXIT_POLL_SECONDS,
+    PROCESS_TREE_EXIT_WAIT_SECONDS,
     PROCESS_TREE_KILL_TIMEOUT_SECONDS,
     WINDOWS_TASKKILL_COMMAND,
     WINDOWS_TASKKILL_FORCE_FLAG,
@@ -126,19 +129,103 @@ def terminate_process_tree(process: subprocess.Popen[str]) -> None:
         tree kill takes            ok:  grandchildren die, pipes close
         tree kill misses the child ok:  Popen.kill() ends the direct child
         child exits mid-kill       ok:  the raised lookup error is swallowed
+        grandchild still running   ok:  returns once the POSIX group has exited
 
     Falls back to ``Popen.kill()`` when the direct child survives the tree kill,
-    so the caller never waits on a live process.
+    so the caller never waits on a live process. On POSIX it then waits, bounded
+    by ``PROCESS_TREE_EXIT_WAIT_SECONDS``, until no group member is running, so
+    a descendant cannot touch files after this call returns.
 
     Args:
         process: The process whose tree is ended.
     """
     if process.poll() is not None:
         return
+    process_group_identifier = _posix_process_group(process.pid)
     kill_process_tree_by_identifier(process.pid)
-    if process.poll() is not None:
-        return
+    if process.poll() is None:
+        try:
+            process.kill()
+        except ProcessLookupError:
+            pass
+    if process_group_identifier is not None:
+        _wait_for_process_group_exit(process, process_group_identifier)
+
+
+def _posix_process_group(process_identifier: int) -> int | None:
+    if sys.platform == "win32":
+        return None
     try:
-        process.kill()
-    except ProcessLookupError:
-        return
+        return os.getpgid(process_identifier)
+    except OSError:
+        return None
+
+
+def _wait_for_process_group_exit(
+    process: subprocess.Popen[str], process_group_identifier: int
+) -> None:
+    """Block until no member of the signalled group is still running, bounded.
+
+    ``killpg`` returns once the signal is queued, and each target dies only when
+    the kernel next schedules it. A grandchild preempted inside a system call
+    finishes that call first, so it can still truncate or write a file after
+    the caller has moved on. Waiting here keeps that work inside the call.
+    """
+    deadline = time.monotonic() + PROCESS_TREE_EXIT_WAIT_SECONDS
+    while running_process_group_members(process, process_group_identifier):
+        if time.monotonic() >= deadline:
+            return
+        time.sleep(PROCESS_TREE_EXIT_POLL_SECONDS)
+
+
+def running_process_group_members(
+    process: subprocess.Popen[str], process_group_identifier: int
+) -> list[int]:
+    """List the process ids in a POSIX group that have not exited yet.
+
+    Reads ``/proc`` where it exists, which tells a running member from a zombie
+    waiting on its reaper. Elsewhere it reaps the direct child and asks the
+    kernel whether the group still has any member.
+
+    Args:
+        process: The direct child that leads the group.
+        process_group_identifier: The group the direct child leads.
+
+    Returns:
+        Process ids still running, or an empty list once the group has exited.
+    """
+    if sys.platform == "win32":
+        return []
+    proc_directory = Path("/proc")
+    if proc_directory.is_dir():
+        return _running_members_from_proc(proc_directory, process_group_identifier)
+    try:
+        process.wait(timeout=PROCESS_TREE_EXIT_POLL_SECONDS)
+    except subprocess.TimeoutExpired:
+        return [process.pid]
+    try:
+        os.killpg(process_group_identifier, 0)
+    except OSError:
+        return []
+    return [process_group_identifier]
+
+
+def _running_members_from_proc(
+    proc_directory: Path, process_group_identifier: int
+) -> list[int]:
+    all_running: list[int] = []
+    for each_entry in proc_directory.iterdir():
+        if not each_entry.name.isdigit():
+            continue
+        try:
+            stat_text = (each_entry / "stat").read_text(
+                encoding="ascii", errors="replace"
+            )
+        except OSError:
+            continue
+        state, _parent_identifier, group_identifier, *_later_fields = stat_text.rsplit(
+            ")", 1
+        )[1].split()
+        if int(group_identifier) == process_group_identifier and state != "Z":
+            all_running.append(int(each_entry.name))
+    return all_running

package/_shared/process-tree/scripts/test_process_tree_kill.py

@@ -7,9 +7,12 @@ the taskkill argv it builds, the failures it swallows, and the
 
 from __future__ import annotations
 
+import os
 import subprocess
 import sys
+import time
 from pathlib import Path
+from typing import cast
 
 import pytest
 
@@ -23,6 +26,8 @@ from process_tree_kill import (  # noqa: E402
     terminate_process_tree,
 )
 from process_tree_scripts_constants.process_tree_kill_constants import (  # noqa: E402
+    PROCESS_TREE_EXIT_POLL_SECONDS,
+    PROCESS_TREE_EXIT_WAIT_SECONDS,
     PROCESS_TREE_KILL_TIMEOUT_SECONDS,
     WINDOWS_TASKKILL_COMMAND,
     WINDOWS_TASKKILL_FORCE_FLAG,
@@ -276,3 +281,147 @@ def test_new_session_is_requested_off_windows_only(
 
     _install_windows_platform(monkeypatch)
     assert process_tree_kill.should_start_new_session() is False
+
+
+def _install_posix_group_wait(
+    monkeypatch: pytest.MonkeyPatch, all_member_snapshots: list[list[int]]
+) -> list[float]:
+    """Script what the group wait sees after the kill, and record each pause.
+
+    The last snapshot repeats once the list runs dry, so a never-empty script
+    models a group that outlives the deadline.
+    """
+    all_sleeps: list[float] = []
+    remaining_snapshots = list(all_member_snapshots)
+
+    def scripted_members(process: object, process_group_identifier: int) -> list[int]:
+        del process, process_group_identifier
+        if len(remaining_snapshots) > 1:
+            return remaining_snapshots.pop(0)
+        return remaining_snapshots[0]
+
+    _install_posix_platform(monkeypatch)
+    monkeypatch.setattr(
+        process_tree_kill.os,
+        "getpgid",
+        lambda process_identifier: FAKE_PROCESS_GROUP_IDENTIFIER,
+        raising=False,
+    )
+    monkeypatch.setattr(
+        process_tree_kill.os,
+        "killpg",
+        lambda group_identifier, signal_number: None,
+        raising=False,
+    )
+    monkeypatch.setattr(
+        process_tree_kill, "running_process_group_members", scripted_members
+    )
+    monkeypatch.setattr(process_tree_kill.time, "sleep", all_sleeps.append)
+    return all_sleeps
+
+
+def test_terminate_waits_until_no_group_member_is_running(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The POSIX kill returns only once the signalled group has emptied.
+
+    ::
+
+        members [7], [7], []  ok:   two pauses, then return
+        no wait               flag: a grandchild still inside a system call
+                                    writes after the caller has moved on
+    """
+    all_sleeps = _install_posix_group_wait(monkeypatch, [[7], [7], []])
+
+    terminate_process_tree(_as_popen(_FakeProcess([None, 0])))
+
+    assert all_sleeps == [PROCESS_TREE_EXIT_POLL_SECONDS] * 2
+
+
+def test_terminate_stops_waiting_at_the_exit_deadline(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A group member that survives the signal does not hold the caller forever."""
+    all_sleeps = _install_posix_group_wait(monkeypatch, [[7]])
+    clock = iter(
+        [0.0, 0.0, PROCESS_TREE_EXIT_WAIT_SECONDS / 2, PROCESS_TREE_EXIT_WAIT_SECONDS]
+    )
+    monkeypatch.setattr(process_tree_kill.time, "monotonic", lambda: next(clock))
+
+    terminate_process_tree(_as_popen(_FakeProcess([None, 0])))
+
+    assert all_sleeps == [PROCESS_TREE_EXIT_POLL_SECONDS] * 2
+
+
+def _as_popen(fake_process: _FakeProcess) -> subprocess.Popen[str]:
+    return cast("subprocess.Popen[str]", fake_process)
+
+
+def _group_led_by(process: subprocess.Popen[str]) -> int:
+    """Name the group a session-leading child owns; Windows has none, so its pid."""
+    if process_tree_kill.should_start_new_session():
+        return os.getpgid(process.pid)
+    return process.pid
+
+
+def test_running_members_leave_out_a_zombie() -> None:
+    """A member that died but awaits its reaper is not running.
+
+    ::
+
+        child sleeping               ok:   listed on POSIX, [] on Windows
+        child killed, not yet reaped ok:   dropped, so the wait ends
+    """
+    sleeper = subprocess.Popen(
+        [sys.executable, "-c", "import time; time.sleep(60)"],
+        start_new_session=process_tree_kill.should_start_new_session(),
+    )
+    group_identifier = _group_led_by(sleeper)
+    all_expected_running = (
+        [sleeper.pid] if process_tree_kill.should_start_new_session() else []
+    )
+    try:
+        assert (
+            process_tree_kill.running_process_group_members(sleeper, group_identifier)
+            == all_expected_running
+        )
+        sleeper.kill()
+        deadline = time.monotonic() + PROCESS_TREE_EXIT_WAIT_SECONDS
+        while process_tree_kill.running_process_group_members(
+            sleeper, group_identifier
+        ):
+            assert time.monotonic() < deadline, "the killed sleeper still counts"
+            time.sleep(PROCESS_TREE_EXIT_POLL_SECONDS)
+    finally:
+        sleeper.wait()
+
+
+def test_terminate_returns_with_the_grandchild_already_gone(tmp_path: Path) -> None:
+    """Right after the kill returns, no process in the child's group still runs."""
+    heartbeat_file = tmp_path / "heartbeat.txt"
+    grandchild_source = (
+        "import pathlib, sys\n"
+        "heartbeat = pathlib.Path(sys.argv[1])\n"
+        "while True:\n"
+        "    heartbeat.write_text('beat', encoding='utf-8')\n"
+    )
+    child_source = (
+        "import subprocess, sys, time\n"
+        "subprocess.Popen([sys.executable, '-c', sys.argv[1], sys.argv[2]])\n"
+        "time.sleep(60)\n"
+    )
+    child = subprocess.Popen(
+        [sys.executable, "-c", child_source, grandchild_source, str(heartbeat_file)],
+        start_new_session=process_tree_kill.should_start_new_session(),
+    )
+    group_identifier = _group_led_by(child)
+    while not heartbeat_file.exists():
+        time.sleep(PROCESS_TREE_EXIT_POLL_SECONDS)
+
+    terminate_process_tree(child)
+    still_running = process_tree_kill.running_process_group_members(
+        child, group_identifier
+    )
+    child.wait()
+
+    assert still_running == []

package/bin/install-pstack-plugin.mjs

@@ -15,7 +15,7 @@ export const PSTACK_PLUGIN_SPEC = Object.freeze({
     label: 'Pstack',
     marketplaceRepository: PSTACK_MARKETPLACE_REPOSITORY,
     marketplaceName: PSTACK_MARKETPLACE_NAME,
-    marketplaceAddArguments: Object.freeze([]),
+    sparsePaths: Object.freeze([]),
     pluginIdentifier: PSTACK_PLUGIN_IDENTIFIER,
     hosts: PSTACK_PLUGIN_HOSTS,
     optOutFlag: PSTACK_PLUGIN_OPT_OUT_FLAG,
@@ -27,13 +27,25 @@ export const USAGE_WRAPUP_PLUGIN_SPEC = Object.freeze({
     label: 'Usage-wrapup',
     marketplaceRepository: 'jl-cmd/claude-dev-env',
     marketplaceName: 'claude-dev-env',
-    marketplaceAddArguments: Object.freeze(['--sparse', '.claude-plugin', 'packages/usage-wrapup']),
+    sparsePaths: Object.freeze(['.claude-plugin', 'packages/usage-wrapup']),
     pluginIdentifier: 'usage-wrapup@claude-dev-env',
     hosts: Object.freeze(['claude']),
     optOutFlag: '--no-usage-wrapup',
     optOutVariable: 'CDE_INSTALL_USAGE_WRAPUP',
 });
 
+export const SUBAGENT_MODELS_PLUGIN_SPEC = Object.freeze({
+    name: 'subagent-models',
+    label: 'Subagent-models',
+    marketplaceRepository: 'jl-cmd/claude-dev-env',
+    marketplaceName: 'claude-dev-env',
+    sparsePaths: Object.freeze(['.claude-plugin', 'packages/subagent-models']),
+    pluginIdentifier: 'subagent-models@claude-dev-env',
+    hosts: Object.freeze(['claude']),
+    optOutFlag: '--no-subagent-models',
+    optOutVariable: 'CDE_INSTALL_SUBAGENT_MODELS',
+});
+
 const HOST_DEFINITIONS = Object.freeze({
     claude: Object.freeze({
         executable: 'claude',
@@ -55,42 +67,60 @@ const HOST_DEFINITIONS = Object.freeze({
 });
 
 /**
- * Read the marketplace and plugin commands one host installs a plugin with.
+ * Read the marketplace and plugin commands one host installs a set of plugins with.
  *
- * The removal commands run first and take out the installed plugin, its
- * cached versions, and the marketplace clone, so the install commands that
- * follow fetch the newest published version into an empty slot.
+ * Every plugin in the set comes from one marketplace. Removing a marketplace
+ * uninstalls each plugin it supplied, so the plan removes and adds that
+ * marketplace once for the whole set. The removal commands run first and take
+ * out each installed plugin, its cached versions, and the marketplace clone,
+ * so the install commands that follow fetch the newest published version into
+ * an empty slot.
  *
  * Claude Code and Codex publish a marketplace under different plugin verbs, so
  * the install verb belongs to the host and the marketplace and identifier
  * belong to the plugin spec. A spec whose marketplace is a large repository
- * passes `--sparse .claude-plugin` among its marketplace add arguments, so the
- * clone holds only the catalog and stays clear of Windows path-length limits.
+ * names its sparse paths, and the one marketplace add checks out every path
+ * the set names, so the clone holds only the catalog and those plugin folders
+ * and stays clear of Windows path-length limits.
  *
- * @param {typeof PSTACK_PLUGIN_SPEC} spec The plugin to install.
- * @param {string} host A host the spec names, `claude` or `codex`.
+ * @param {ReadonlyArray<typeof PSTACK_PLUGIN_SPEC>} allSpecs The plugins to install, from one marketplace.
+ * @param {string} host A host every spec names, `claude` or `codex`.
  * @returns {{executable: string, executableVariable: string, homeVariable: string,
  *   removalCommands: ReadonlyArray<ReadonlyArray<string>>,
  *   commands: ReadonlyArray<ReadonlyArray<string>>}} The host's install plan.
  */
-export function marketplacePluginPlan(spec, host) {
+export function marketplacePluginsPlan(allSpecs, host) {
     const hostDefinition = HOST_DEFINITIONS[host];
-    if (!hostDefinition || !spec.hosts.includes(host)) {
+    for (const eachSpec of allSpecs) {
+        if (!hostDefinition || !eachSpec.hosts.includes(host)) {
+            throw new Error(
+                `Unsupported ${eachSpec.name} plugin host ${host}: this installer knows ${eachSpec.hosts.join(', ')}.`,
+            );
+        }
+    }
+    const [firstSpec] = allSpecs;
+    const otherMarketplaceSpec = allSpecs.find(
+        eachSpec => eachSpec.marketplaceRepository !== firstSpec.marketplaceRepository,
+    );
+    if (otherMarketplaceSpec) {
         throw new Error(
-            `Unsupported ${spec.name} plugin host ${host}: this installer knows ${spec.hosts.join(', ')}.`,
+            `${otherMarketplaceSpec.name} comes from ${otherMarketplaceSpec.marketplaceRepository}, `
+            + `and one plan installs from ${firstSpec.marketplaceRepository} only.`,
         );
     }
+    const allSparsePaths = [...new Set(allSpecs.flatMap(eachSpec => eachSpec.sparsePaths))];
+    const sparseArguments = allSparsePaths.length > 0 ? ['--sparse', ...allSparsePaths] : [];
     return {
         executable: hostDefinition.executable,
         executableVariable: hostDefinition.executableVariable,
         homeVariable: hostDefinition.homeVariable,
         removalCommands: [
-            ['plugin', hostDefinition.uninstallVerb, spec.pluginIdentifier],
-            ['plugin', 'marketplace', 'remove', spec.marketplaceName],
+            ...allSpecs.map(eachSpec => ['plugin', hostDefinition.uninstallVerb, eachSpec.pluginIdentifier]),
+            ['plugin', 'marketplace', 'remove', firstSpec.marketplaceName],
         ],
         commands: [
-            ['plugin', 'marketplace', 'add', spec.marketplaceRepository, ...spec.marketplaceAddArguments],
-            ['plugin', hostDefinition.installVerb, spec.pluginIdentifier],
+            ['plugin', 'marketplace', 'add', firstSpec.marketplaceRepository, ...sparseArguments],
+            ...allSpecs.map(eachSpec => ['plugin', hostDefinition.installVerb, eachSpec.pluginIdentifier]),
         ],
     };
 }
@@ -198,30 +228,31 @@ export function removeOrphanedPluginVersions(versionsDirectory) {
     return removedPaths;
 }
 
-function absentHostOutcome(spec, host, executable) {
+function absentHostOutcome(allSpecs, host, executable) {
+    const pluginNames = allSpecs.map(eachSpec => eachSpec.name).join(', ');
     return {
         host,
         executable,
         status: 'skipped',
-        warning: `${executable} is not on PATH, so ${spec.name} was not installed for ${host}.`,
+        warning: `${executable} is not on PATH, so ${pluginNames} was not installed for ${host}.`,
     };
 }
 
-function installForHost(spec, host, homeDirectory, environment, runCommand) {
-    const plan = marketplacePluginPlan(spec, host);
+function installForHost(allSpecs, host, homeDirectory, environment, runCommand) {
+    const plan = marketplacePluginsPlan(allSpecs, host);
     const executable = environment[plan.executableVariable] || plan.executable;
     const commandEnvironment = { [plan.homeVariable]: homeDirectory };
     for (const commandArguments of plan.removalCommands) {
         const outcome = runCommand(executable, [...commandArguments], {
             environment: commandEnvironment,
         });
-        if (namesAnAbsentCommand(outcome)) return absentHostOutcome(spec, host, executable);
+        if (namesAnAbsentCommand(outcome)) return absentHostOutcome(allSpecs, host, executable);
     }
     for (const commandArguments of plan.commands) {
         const outcome = runCommand(executable, [...commandArguments], {
             environment: commandEnvironment,
         });
-        if (namesAnAbsentCommand(outcome)) return absentHostOutcome(spec, host, executable);
+        if (namesAnAbsentCommand(outcome)) return absentHostOutcome(allSpecs, host, executable);
         if (outcome.status !== 0 || outcome.error) {
             const detail = firstLine(outcome.stderr) || outcome.error?.message || `exit ${outcome.status}`;
             return {
@@ -234,17 +265,19 @@ function installForHost(spec, host, homeDirectory, environment, runCommand) {
     }
     const hostDefinition = HOST_DEFINITIONS[host];
     if (hostDefinition.orphanedVersionsDirectory && homeDirectory) {
-        removeOrphanedPluginVersions(hostDefinition.orphanedVersionsDirectory(homeDirectory, spec));
+        for (const eachSpec of allSpecs) {
+            removeOrphanedPluginVersions(hostDefinition.orphanedVersionsDirectory(homeDirectory, eachSpec));
+        }
     }
     return { host, executable, status: 'installed', warning: null };
 }
 
 /**
- * Install one plugin from its marketplace into each host's own home.
+ * Install a set of plugins from one marketplace into each host's own home.
  *
- * Each host first removes the plugin and its marketplace, so an older
- * version never survives beside the new one. A removal that finds nothing
- * to remove exits non-zero on a fresh home, and the install goes on.
+ * Each host first removes every plugin in the set and then the marketplace,
+ * so an older version never survives beside the new one. A removal that finds
+ * nothing to remove exits non-zero on a fresh home, and the install goes on.
  *
  * Each host is one member of the batch. A host without its command-line tool
  * is skipped and a host whose command fails is reported, so the rules, hooks,
@@ -253,22 +286,24 @@ function installForHost(spec, host, homeDirectory, environment, runCommand) {
  * `cmd.exe`'s command-not-found exit code on Windows, and both read as
  * skipped.
  *
- * @param {typeof PSTACK_PLUGIN_SPEC} spec The plugin to install.
+ * @param {ReadonlyArray<typeof PSTACK_PLUGIN_SPEC>} allSpecs The plugins to install, from one marketplace.
  * @param {object} [options] Install targets.
  * @param {string} [options.claudeRoot] The managed Claude root to install into.
  * @param {string} [options.codexHome] The Codex home to install into.
- * @param {string[]} [options.hosts] The hosts to install. Defaults to the spec's hosts.
+ * @param {string[]} [options.hosts] The hosts to install. Defaults to the hosts every spec names.
  * @param {Record<string, string|undefined>} [options.environment] The process environment.
  * @param {object} [dependencies] Seams for the command runner.
  * @returns {{status: string, hosts: object[], warning: string|null}} The outcome per host.
  */
-export function installMarketplacePlugin(spec, options = {}, dependencies = {}) {
+export function installMarketplacePlugins(allSpecs, options = {}, dependencies = {}) {
     const environment = options.environment ?? process.env;
     const runCommand = dependencies.runCommand ?? runHostCommand;
     const homeDirectories = { claude: options.claudeRoot, codex: options.codexHome };
-    const hosts = options.hosts ?? spec.hosts;
+    const hosts = options.hosts ?? allSpecs[0].hosts.filter(
+        eachHost => allSpecs.every(eachSpec => eachSpec.hosts.includes(eachHost)),
+    );
     const hostOutcomes = hosts.map(host => installForHost(
-        spec,
+        allSpecs,
         host,
         homeDirectories[host],
         environment,