one-code-extension 0.1.4 → 0.3.0

package/extensions/lib/plugins.ts

@@ -1,36 +1,69 @@
 /**
  * Claude Code plugin discovery (pure).
  *
- * On-disk reality, read from a real installation:
+ * Two roots are merged:
  *
- *   ~/.claude/plugins/installed_plugins.json
- *     { "version": 2, "plugins": { "<name>@<marketplace>": [{ scope, installPath, version }] } }
+ *   ~/.claude/plugins/            Claude Code's own installs — READ-ONLY.
+ *   <agentDir>/plugins/           One Code's installs (lib/plugin-root.ts) —
+ *                                 the only root One Code ever writes.
+ *
+ * Both hold the same on-disk format:
+ *
+ *   <root>/installed_plugins.json
+ *     { "version": 2, "plugins": { "<name>@<marketplace>": [{ scope, installPath, version, ... }] } }
  *
  *   <installPath>/.claude-plugin/plugin.json   { name, description, author }
  *   <installPath>/agents/*.md                  agent definitions
  *   <installPath>/commands/*.md                slash commands
  *   <installPath>/skills/<name>/SKILL.md       skills
  *   <installPath>/.mcp.json                    MCP servers
+ *   <installPath>/.lsp.json                    LSP servers (extensions/lsp)
+ *
+ * Enabled state differs by origin: Claude Code keeps it in settings.json's
+ * `enabledPlugins` map (its installed_plugins.json entries have NO enabled
+ * field), overridable from One Code via <one-code root>/overrides.json;
+ * One Code's own entries carry `enabled` directly (we own that schema copy).
  *
  * Claude Code namespaces everything a plugin provides as `<plugin>:<name>`, so
  * two plugins can both ship a `commit` command.
  */
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { basename, join } from "node:path";
+import os from "node:os";
+import { basename, join, resolve, sep } from "node:path";
+import { readJsonFile } from "./atomic-write.ts";
+import { readEnabledPlugins } from "./claude-settings.ts";
+import { readOverrides } from "./plugin-overrides.ts";
+import { pluginRoot } from "./plugin-root.ts";
+import { isSkillEnabled, readSkillStates, skillOverrideKey } from "./skill-overrides.ts";
+import { claudeUserDir } from "./paths.ts";
 
 export interface PluginManifest {
 	name?: string;
 	description?: string;
 }
 
+export type PluginOrigin = "claude" | "one-code";
+
 export interface Plugin {
-	/** Plugin name, without the @marketplace suffix. */
+	/** Raw registry key (`<name>@<marketplace>`) — what enabledPlugins/overrides key on. */
+	id: string;
+	/** Plugin name, without the @marketplace suffix (manifest name when present). */
 	name: string;
 	marketplace?: string;
 	path: string;
 	version?: string;
 	description?: string;
+	/** Which root the plugin was discovered under. */
+	originRoot: PluginOrigin;
+	/** Effective enabled state after settings/override merging. */
+	enabled: boolean;
+	/** True when a claude-origin plugin's state comes from our overrides.json. */
+	overridden?: boolean;
+	/** Base dir for the plugin's `${CLAUDE_PLUGIN_DATA}` (per-origin). */
+	dataRoot: string;
+	/** Raw `enabled` from the installed_plugins.json entry (meaningful only for one-code origin). */
+	rawEnabled?: boolean;
 }
 
 export interface PluginResources {
@@ -40,15 +73,35 @@ export interface PluginResources {
 	mcpConfig?: string;
 	/** <plugin>/hooks/hooks.json when present — consumed by extensions/hooks. */
 	hooksConfig?: string;
+	/** <plugin>/.lsp.json when present — consumed by extensions/lsp. */
+	lspConfig?: string;
 }
 
 interface InstalledEntry {
 	scope?: string;
+	/** For scope "project"/"local": the project the plugin was installed for. */
+	projectPath?: string;
 	installPath?: string;
 	version?: string;
 	enabled?: boolean;
 }
 
+/**
+ * Whether an installed-plugin entry applies to the session cwd. A project- or
+ * local-scoped entry belongs to one project (its `projectPath`), so it should
+ * be live only in that project or a descendant — not in every project under One
+ * Code (review L6). A user-scoped entry (or one with no `projectPath`, or when
+ * cwd is unknown) applies everywhere.
+ */
+export function entryAppliesToCwd(entry: InstalledEntry, cwd: string | undefined): boolean {
+	if (!cwd) return true;
+	if (entry.scope !== "project" && entry.scope !== "local") return true;
+	if (!entry.projectPath) return true;
+	const base = resolve(entry.projectPath);
+	const here = resolve(cwd);
+	return here === base || here.startsWith(base + sep);
+}
+
 export function splitPluginKey(key: string): { name: string; marketplace?: string } {
 	const at = key.lastIndexOf("@");
 	if (at <= 0) return { name: key };
@@ -64,56 +117,80 @@ export function tryReadFile(path: string): string | undefined {
 	}
 }
 
-function readJsonFile<T>(path: string): T | undefined {
-	if (!existsSync(path)) return undefined;
-	const raw = tryReadFile(path);
-	if (raw === undefined) return undefined;
-	try {
-		return JSON.parse(raw) as T;
-	} catch {
-		return undefined;
-	}
+/** One root's installed plugins, before enabled-policy is applied. */
+export interface InstalledPlugin {
+	id: string;
+	name: string;
+	marketplace?: string;
+	path: string;
+	version?: string;
+	description?: string;
+	rawEnabled?: boolean;
 }
 
-/** Reads the installed-plugin registry; the newest entry per plugin wins. */
-export function loadInstalledPlugins(claudeDir: string): Plugin[] {
+/**
+ * Reads a root's installed-plugin registry (`<pluginsDir>/installed_plugins.json`).
+ * Format reader only — no enabled policy here: Claude Code's entries carry no
+ * enabled field (that state lives in settings.json), so the first entry with an
+ * existing installPath wins; a raw `enabled` value is passed through for the
+ * One Code root, where the entry schema is ours.
+ */
+export function loadInstalledPlugins(pluginsDir: string, cwd?: string): InstalledPlugin[] {
 	const registry = readJsonFile<{ plugins?: Record<string, InstalledEntry[]> }>(
-		join(claudeDir, "plugins", "installed_plugins.json"),
+		join(pluginsDir, "installed_plugins.json"),
 	);
 	if (!registry?.plugins) return [];
 
-	const plugins: Plugin[] = [];
+	const plugins: InstalledPlugin[] = [];
 	for (const [key, entries] of Object.entries(registry.plugins)) {
 		if (!Array.isArray(entries) || entries.length === 0) continue;
-		const entry = entries.find((e) => e.enabled !== false && e.installPath);
-		if (!entry?.installPath || !existsSync(entry.installPath)) continue;
+		const entry = entries.find((e) => e.installPath && existsSync(e.installPath) && entryAppliesToCwd(e, cwd));
+		if (!entry?.installPath) continue;
 
 		const { name, marketplace } = splitPluginKey(key);
 		const manifest = readJsonFile<PluginManifest>(join(entry.installPath, ".claude-plugin", "plugin.json"));
 		plugins.push({
-			name: manifest?.name || name,
+			id: key,
+			// A third-party manifest is copied in verbatim: a non-string `name`
+			// (or one carrying path separators) would later crash `localeCompare`
+			// or poison the namespace it becomes. Fall back to the registry key's
+			// name for anything not a clean string (review H2).
+			name: validPluginName(manifest?.name) ?? name,
 			marketplace,
 			path: entry.installPath,
 			version: entry.version,
-			description: manifest?.description,
+			description: typeof manifest?.description === "string" ? manifest.description : undefined,
+			rawEnabled: typeof entry.enabled === "boolean" ? entry.enabled : undefined,
 		});
 	}
 	return plugins.sort((a, b) => a.name.localeCompare(b.name));
 }
 
-export function pluginResources(plugin: Plugin): PluginResources {
+/** A manifest `name` usable as a namespace: a non-empty string free of path separators, colons and whitespace. */
+export function validPluginName(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	if (trimmed.length === 0) return undefined;
+	if (/[/\\:\s]/.test(trimmed)) return undefined;
+	return trimmed;
+}
+
+export function pluginResources(plugin: Pick<Plugin, "path">): PluginResources {
 	const dirIfExists = (name: string) => {
 		const path = join(plugin.path, name);
 		return existsSync(path) && statSync(path).isDirectory() ? path : undefined;
 	};
-	const mcpConfig = join(plugin.path, ".mcp.json");
-	const hooksConfig = join(plugin.path, "hooks", "hooks.json");
+	const fileIfExists = (...segments: string[]) => {
+		const path = join(plugin.path, ...segments);
+		return existsSync(path) ? path : undefined;
+	};
 	return {
 		agentsDir: dirIfExists("agents"),
 		commandsDir: dirIfExists("commands"),
 		skillsDir: dirIfExists("skills"),
-		mcpConfig: existsSync(mcpConfig) ? mcpConfig : undefined,
-		hooksConfig: existsSync(hooksConfig) ? hooksConfig : undefined,
+		mcpConfig: fileIfExists(".mcp.json"),
+		hooksConfig: fileIfExists("hooks", "hooks.json"),
+		lspConfig: fileIfExists(".lsp.json"),
 	};
 }
 
@@ -125,7 +202,7 @@ export interface PluginSkill {
 }
 
 /** Each immediate subdirectory holding a SKILL.md is one skill. */
-export function findPluginSkills(plugin: Plugin, skillsDir: string): PluginSkill[] {
+export function findPluginSkills(plugin: Pick<Plugin, "name">, skillsDir: string): PluginSkill[] {
 	const skills: PluginSkill[] = [];
 	let entries: string[];
 	try {
@@ -149,7 +226,7 @@ export interface PluginCommand {
 	path: string;
 }
 
-export function findPluginCommands(plugin: Plugin, commandsDir: string): PluginCommand[] {
+export function findPluginCommands(plugin: Pick<Plugin, "name">, commandsDir: string): PluginCommand[] {
 	let entries: string[];
 	try {
 		entries = readdirSync(commandsDir);
@@ -165,14 +242,51 @@ export function findPluginCommands(plugin: Plugin, commandsDir: string): PluginC
 		}));
 }
 
+/** The two roots + settings locations discovery reads from. */
+export interface DiscoverRoots {
+	/** Claude Code's plugins dir (`~/.claude/plugins`) — read-only. */
+	claudePluginsDir: string;
+	/** One Code's plugin root (`<agentDir>/plugins`) — ours to write. */
+	oneCodeRoot: string;
+	cwd: string;
+	home: string;
+}
+
+/** The standard roots; wiring passes `getAgentDir()` (pure modules can't). */
+export function defaultDiscoverRoots(agentDir: string, cwd: string = process.cwd(), home: string = os.homedir()): DiscoverRoots {
+	return {
+		claudePluginsDir: join(claudeUserDir(home), "plugins"),
+		oneCodeRoot: pluginRoot(agentDir),
+		cwd,
+		home,
+	};
+}
+
+/**
+ * The enabled-state precedence for a Claude Code-installed plugin: a One Code
+ * override wins, then Claude Code's own settings, then default-enabled.
+ */
+export function claudePluginEnabled(
+	id: string,
+	ccEnabled: Record<string, boolean>,
+	overrides: Record<string, boolean>,
+): boolean {
+	return overrides[id] ?? ccEnabled[id] ?? true;
+}
+
+/** One Code-installed plugins carry enabled on their own registry entry. */
+export function oneCodePluginEnabled(rawEnabled: boolean | undefined): boolean {
+	return rawEnabled ?? true;
+}
+
 /**
- * Everything a plugin contributes, resolved in one pass.
+ * Everything the installed plugins contribute, resolved in one pass.
  *
  * IMPORTANT: this is a function each consuming extension calls for itself, not a
  * shared singleton. Under jiti every extension file gets its own module
  * instance, so module-level state written by one extension is invisible to
- * another — a shared registry silently read as empty. Re-deriving is cheap (one
- * small JSON plus a few directory checks) and has no load-order constraints.
+ * another — a shared registry silently read as empty. Re-deriving is cheap (a
+ * few small JSON files plus directory checks) and has no load-order constraints.
  */
 export interface NamespacedDir {
 	dir: string;
@@ -180,48 +294,113 @@ export interface NamespacedDir {
 }
 
 export interface DiscoveredPlugins {
+	/** Every installed plugin, enabled or not (the /plugins panel needs both). */
 	plugins: Plugin[];
+	/** Enabled plugins only — the set whose resources are wired in below. */
+	enabledPlugins: Plugin[];
 	agentDirs: NamespacedDir[];
 	skills: PluginSkill[];
 	commands: PluginCommand[];
 	mcpConfigs: string[];
-	/** Per-plugin summary, for status output. */
-	byPlugin: Map<string, { agents: boolean; skills: number; commands: number; mcp: boolean }>;
+	/** The plugin each `mcpConfigs` path belongs to, so its servers can be namespaced `plugin:<name>:<server>`. */
+	mcpConfigPlugins: Map<string, string>;
+	/** Per-plugin summary keyed by plugin id, for status output. */
+	byPlugin: Map<string, { agents: boolean; skills: number; commands: number; mcp: boolean; lsp: boolean }>;
+}
+
+/**
+ * ONE discovery cache for the whole process. Seven extensions import this
+ * module (branding, hooks, lsp, mcp, plugins, skill, subagents) and jiti gives
+ * each its own module instance, so a module-level variable meant seven full
+ * disk scans at startup and an invalidation that cleared only the caller's
+ * copy. The cache therefore hangs off `globalThis` under a symbol: a pure
+ * memo of filesystem state (not steering state — the module-isolation rule in
+ * CLAUDE.md is about *that*), read-through, cleared everywhere at once.
+ */
+const CACHE_SLOT = Symbol.for("one-code:plugins-discovery-cache");
+type CacheBox = { current?: { key: string; result: DiscoveredPlugins } };
+const box: CacheBox = ((globalThis as Record<symbol, unknown>)[CACHE_SLOT] ??= {}) as CacheBox;
+
+/**
+ * Drops the process-wide discovery cache; the /plugins panel calls this after
+ * installs/toggles so every extension's next discoverPlugins() reflects them.
+ */
+export function invalidatePluginsCache(): void {
+	box.current = undefined;
 }
 
-let cache: { claudeDir: string; result: DiscoveredPlugins } | undefined;
+export function discoverPlugins(roots: DiscoverRoots): DiscoveredPlugins {
+	const key = [roots.claudePluginsDir, roots.oneCodeRoot, roots.cwd, roots.home].join("\n");
+	if (box.current?.key === key) return box.current.result;
+
+	const ccEnabled = readEnabledPlugins(roots.cwd, roots.home);
+	const overrides = readOverrides(roots.oneCodeRoot);
+	const skillOverrides = readSkillStates(roots.oneCodeRoot);
 
-export function discoverPlugins(claudeDir: string): DiscoveredPlugins {
-	if (cache?.claudeDir === claudeDir) return cache.result;
+	const claudePlugins: Plugin[] = loadInstalledPlugins(roots.claudePluginsDir, roots.cwd).map((p) => ({
+		...p,
+		originRoot: "claude" as const,
+		enabled: claudePluginEnabled(p.id, ccEnabled, overrides),
+		overridden: p.id in overrides,
+		dataRoot: join(roots.claudePluginsDir, "data"),
+	}));
+
+	const oneCodePlugins: Plugin[] = loadInstalledPlugins(roots.oneCodeRoot, roots.cwd).map((p) => ({
+		...p,
+		originRoot: "one-code" as const,
+		enabled: oneCodePluginEnabled(p.rawEnabled),
+		dataRoot: join(roots.oneCodeRoot, "data"),
+	}));
+
+	// Same plugin id installed under both roots: the One Code copy wins — it's
+	// the one this harness actively manages.
+	const byId = new Map<string, Plugin>();
+	for (const plugin of [...claudePlugins, ...oneCodePlugins]) byId.set(plugin.id, plugin);
+	const plugins = [...byId.values()].sort((a, b) => a.name.localeCompare(b.name));
+	const enabledPlugins = plugins.filter((p) => p.enabled);
 
-	const plugins = loadInstalledPlugins(claudeDir);
 	const result: DiscoveredPlugins = {
 		plugins,
+		enabledPlugins,
 		agentDirs: [],
 		skills: [],
 		commands: [],
 		mcpConfigs: [],
+		mcpConfigPlugins: new Map(),
 		byPlugin: new Map(),
 	};
 
 	for (const plugin of plugins) {
-		const resources = pluginResources(plugin);
-		const skills = resources.skillsDir ? findPluginSkills(plugin, resources.skillsDir) : [];
-		const commands = resources.commandsDir ? findPluginCommands(plugin, resources.commandsDir) : [];
-
-		if (resources.agentsDir) result.agentDirs.push({ dir: resources.agentsDir, namespace: plugin.name });
-		result.skills.push(...skills);
-		result.commands.push(...commands);
-		if (resources.mcpConfig) result.mcpConfigs.push(resources.mcpConfig);
-
-		result.byPlugin.set(plugin.name, {
-			agents: !!resources.agentsDir,
-			skills: skills.length,
-			commands: commands.length,
-			mcp: !!resources.mcpConfig,
-		});
+		// One plugin's fault (a broken symlink in its resource dirs, a statSync
+		// permission error) must skip only that plugin, not blank out every
+		// other plugin's skills/commands/agents for the session. safeDiscover's
+		// outer catch is the last resort; this keeps the blast radius to one entry.
+		try {
+			const resources = pluginResources(plugin);
+			const skills = resources.skillsDir ? findPluginSkills(plugin, resources.skillsDir) : [];
+			const commands = resources.commandsDir ? findPluginCommands(plugin, resources.commandsDir) : [];
+
+			result.byPlugin.set(plugin.id, {
+				agents: !!resources.agentsDir,
+				skills: skills.length,
+				commands: commands.length,
+				mcp: !!resources.mcpConfig,
+				lsp: !!resources.lspConfig,
+			});
+
+			if (!plugin.enabled) continue;
+			if (resources.agentsDir) result.agentDirs.push({ dir: resources.agentsDir, namespace: plugin.name });
+			result.skills.push(...skills.filter((s) => isSkillEnabled(skillOverrides, skillOverrideKey("plugin", s.name))));
+			result.commands.push(...commands);
+			if (resources.mcpConfig) {
+				result.mcpConfigs.push(resources.mcpConfig);
+				result.mcpConfigPlugins.set(resources.mcpConfig, plugin.name);
+			}
+		} catch (error) {
+			console.error(`One Code: skipping plugin "${plugin.id}" — its resources could not be read: ${(error as Error).message}`);
+		}
 	}
 
-	cache = { claudeDir, result };
+	box.current = { key, result };
 	return result;
 }

package/extensions/lib/prefix-warm-gate.ts

@@ -0,0 +1,157 @@
+/**
+ * First-token gate for parallel agent fan-out.
+ *
+ * A provider cache entry becomes readable only once the request that writes
+ * it has started streaming. N children started at the same instant with a
+ * byte-identical prefix (same agent prompt, same first-message reminder stack,
+ * same model) therefore all pay the cache write; none reads what the others
+ * are writing. The gate lets the FIRST run for a prefix key go, holds the rest
+ * until that run's first assistant `message_start` (the stream has begun, the
+ * entry exists), then releases them — every follower reads the prefix instead
+ * of writing it. Followers of a key that recently streamed pass straight
+ * through; a leader that never streams (spawn failure, provider error) hands
+ * the lead to the next waiter; a leader that is merely slow times out so a
+ * stalled first request can never hold a whole fan-out.
+ *
+ * Pure (no pi imports); wired in subagents/runner.ts and workflow/agent-session.ts.
+ */
+
+type Entry =
+	| { kind: "warming"; done: Promise<void>; resolve: () => void }
+	| { kind: "warm"; at: number };
+
+/**
+ * The gate key for a child run: same prompt identity + cwd + model spec = same
+ * request prefix. Both fan-out sites (subagents/runner.ts, workflow/agent-session.ts)
+ * build their key here so the scheme cannot drift between them.
+ */
+export function prefixWarmKey(promptIdentity: string, cwd: string, modelSpec: string | undefined): string {
+	return `${promptIdentity}|${cwd}|${modelSpec ?? ""}`;
+}
+
+/** Prompt identity of a fresh (non-fork) child: its agent definition, else the base prompt. */
+export function agentPromptIdentity(agentName: string | undefined): string {
+	return agentName ? `agent:${agentName}` : "base";
+}
+
+export interface PrefixWarmGateOptions {
+	/** How long a leader may take to stream before waiters are released anyway. */
+	timeoutMs?: number;
+	/** How long after the last stream start a key counts as warm (the 5-minute TTL minus slack). */
+	warmForMs?: number;
+	/** Clock, for tests. */
+	now?: () => number;
+}
+
+/** What the caller reports when it is done with its admission. */
+export type Release = (streamed: boolean) => void;
+
+export class PrefixWarmGate {
+	private readonly entries = new Map<string, Entry>();
+	private readonly timeoutMs: number;
+	private readonly warmForMs: number;
+	private readonly now: () => number;
+
+	constructor(options: PrefixWarmGateOptions = {}) {
+		this.timeoutMs = options.timeoutMs ?? 20_000;
+		this.warmForMs = options.warmForMs ?? 4 * 60_000;
+		this.now = options.now ?? Date.now;
+	}
+
+	/**
+	 * Wait until `key`'s prefix is (probably) cached, then return the release
+	 * the caller must invoke: `release(true)` when its own response started
+	 * streaming (refreshes the warm stamp; lets waiters go if it was the leader),
+	 * `release(false)` if it gave up without streaming. Idempotent; the first
+	 * call wins.
+	 */
+	async admit(key: string): Promise<Release> {
+		for (;;) {
+			const entry = this.entries.get(key);
+			if (entry?.kind === "warm" && this.now() - entry.at < this.warmForMs) {
+				return this.followerRelease(key);
+			}
+			if (entry?.kind === "warming") {
+				await entry.done;
+				continue;
+			}
+			return this.lead(key);
+		}
+	}
+
+	/** How many keys are currently warming (for tests). */
+	get warmingCount(): number {
+		let count = 0;
+		for (const entry of this.entries.values()) if (entry.kind === "warming") count++;
+		return count;
+	}
+
+	private lead(key: string): Release {
+		let resolve!: () => void;
+		const done = new Promise<void>((r) => {
+			resolve = r;
+		});
+		const entry: Entry = { kind: "warming", done, resolve };
+		this.entries.set(key, entry);
+		// A leader that streams slowly must not hold the fan-out forever: on
+		// timeout everyone proceeds and the key is treated as warm.
+		const timer = setTimeout(() => {
+			if (this.entries.get(key) === entry) {
+				this.entries.set(key, { kind: "warm", at: this.now() });
+				resolve();
+			}
+		}, this.timeoutMs);
+		timer.unref?.();
+
+		let released = false;
+		return (streamed) => {
+			if (released) return;
+			released = true;
+			clearTimeout(timer);
+			if (this.entries.get(key) === entry) {
+				// Streamed: the entry exists, followers read it. Abandoned: back to
+				// cold, so the next waiter becomes the leader (its loop re-enters lead()).
+				if (streamed) this.entries.set(key, { kind: "warm", at: this.now() });
+				else this.entries.delete(key);
+			}
+			resolve();
+		};
+	}
+
+	/**
+	 * `admit(key)` for an agent session: the session's own first assistant
+	 * `message_start` (the stream has begun, the entry exists) releases it as
+	 * streamed; the returned release is for the caller's `finally`, where
+	 * `release(false)` is a no-op if streaming already released it and hands the
+	 * lead on if the run never streamed. Structural session type keeps this
+	 * module pi-free.
+	 */
+	async admitOnFirstToken(
+		key: string,
+		session: { subscribe(listener: (event: unknown) => void): () => void },
+	): Promise<Release> {
+		const release = await this.admit(key);
+		const stop = session.subscribe((event) => {
+			const e = event as { type?: string; message?: { role?: string } };
+			if (e.type === "message_start" && e.message?.role === "assistant") {
+				stop();
+				release(true);
+			}
+		});
+		return (streamed) => {
+			stop();
+			release(streamed);
+		};
+	}
+
+	private followerRelease(key: string): Release {
+		let released = false;
+		return (streamed) => {
+			if (released) return;
+			released = true;
+			if (!streamed) return;
+			const entry = this.entries.get(key);
+			if (entry?.kind === "warm") this.entries.set(key, { kind: "warm", at: this.now() });
+		};
+	}
+}

package/extensions/lib/process-tree.ts

@@ -0,0 +1,56 @@
+/**
+ * Process-tree termination for the shells One Code spawns in the background
+ * (`bash run_in_background`, `monitor`).
+ *
+ * A `$SHELL -c "cmd"` child is only the leader: with zsh (macOS default) a
+ * `cmd; echo` or a pipeline runs the command in further processes, and
+ * `child.kill()` signals the shell alone — the command lives on as an orphan
+ * holding the inherited stdout pipe, so `close` never fires (the task cannot
+ * finish, a `task_output block:true` waits its full timeout) and in a one-shot
+ * run the open pipe keeps node alive until the orphan exits
+ * (LIFECYCLE-REVIEW-2026-09-06 M2, measured: 3 min 21 s on a `tail -f | cat`).
+ *
+ * The producer spawns `detached` (own process group; `detachedSpawnOptions`)
+ * and stops it with `killProcessTree`, which signals the negative pid — the
+ * whole group — falling back to the child alone when the group is already gone.
+ * `stopProcessTree` adds the grace period: SIGTERM now, SIGKILL if the leader
+ * has not exited by then (a command that ignores SIGTERM still closes late,
+ * which is exactly the late callback the shutdown paths guard against).
+ */
+
+import type { ChildProcess } from "node:child_process";
+
+/** SIGTERM → SIGKILL grace for a stopped background tree (bash tasks, monitors). */
+export const KILL_GRACE_MS = 2_000;
+
+/** `detached` everywhere but Windows, where process groups do not exist. */
+export function detachedSpawnOptions(): { detached: boolean } {
+	return { detached: process.platform !== "win32" };
+}
+
+export function killProcessTree(child: ChildProcess, signal: NodeJS.Signals = "SIGTERM"): void {
+	if (child.pid == null) return;
+	try {
+		process.kill(-child.pid, signal);
+	} catch {
+		try {
+			child.kill(signal);
+		} catch {
+			// Already gone.
+		}
+	}
+}
+
+/**
+ * SIGTERM the tree, then SIGKILL it after `graceMs` unless the leader exited.
+ * The timer is unref'd: it must never be what keeps a one-shot process alive.
+ */
+export function stopProcessTree(child: ChildProcess, graceMs: number): void {
+	killProcessTree(child, "SIGTERM");
+	if (child.exitCode !== null || child.signalCode !== null) return;
+	const timer = setTimeout(() => {
+		if (child.exitCode === null && child.signalCode === null) killProcessTree(child, "SIGKILL");
+	}, graceMs);
+	timer.unref?.();
+	child.once("exit", () => clearTimeout(timer));
+}