@namzu/sdk 27.1.0 → 29.0.0

package/src/plugin/lifecycle.ts

@@ -1,16 +1,21 @@
 import { pathToFileURL } from 'node:url'
+import type { ConfigRegistry } from '../config/registry.js'
 import { mcpToolToToolDefinition } from '../connector/mcp/adapter.js'
 import { MCPClient } from '../connector/mcp/client.js'
 import { MCPToolDiscovery } from '../connector/mcp/discovery.js'
 import type { MCPToolDiscoveryOptions } from '../connector/mcp/discovery.js'
 import type { MCPToolPolicy } from '../connector/mcp/policy.js'
 import { mcpPromptToToolDefinition } from '../connector/mcp/prompt-adapter.js'
+import { MCPReconnectOptionsSchema, MCPReconnectSupervisor } from '../connector/mcp/reconnect.js'
 import {
 	DEFAULT_HOOK_PRIORITY,
 	HOOK_TIMEOUT_MS,
 	PLUGIN_NAMESPACE_SEPARATOR,
 } from '../constants/plugin/index.js'
+import { GENAI } from '../constants/telemetry/index.js'
 import type { PluginRegistry } from '../registry/plugin/index.js'
+import { loadSkill } from '../skills/loader.js'
+import type { SkillRegistry } from '../skills/registry.js'
 import { resolveWithinReal } from '../tools/paths.js'
 import type { PluginId } from '../types/ids/index.js'
 import type {
@@ -28,19 +33,52 @@ import type { RunEvent } from '../types/run/index.js'
 import type { ToolDefinition, ToolRegistryContract } from '../types/tool/index.js'
 import { toErrorMessage } from '../utils/error.js'
 import { generatePluginId } from '../utils/id.js'
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
 import type { Logger } from '../utils/logger.js'
 import { assertEnableable, loadPluginManifest } from './loader.js'
 
 interface PluginContributionRecord {
 	toolNames: string[]
 	mcpClients: MCPClient[]
+	/** Namespaced skill names, so rollback and disable can take them back. */
+	skillNames: string[]
+	/**
+	 * One per client, held so teardown can stop them.
+	 *
+	 * A supervisor still attached when `disconnect()` runs reads the teardown
+	 * as a fault and reconnects what was just closed — the lifecycle event
+	 * cannot tell a deliberate disconnect from a dropped transport. Keeping
+	 * them here is what makes the required stop-then-disconnect ordering
+	 * possible at all.
+	 */
+	mcpSupervisors: MCPReconnectSupervisor[]
 }
 
 export interface PluginLifecycleManagerConfig {
 	pluginRegistry: PluginRegistry
 	toolRegistry: ToolRegistryContract
+	/**
+	 * Where a plugin's declared skills land.
+	 *
+	 * Optional, and its absence is enforced rather than tolerated: a
+	 * manifest that declares skills is REFUSED when this is missing, the
+	 * same way it was refused before the manifest path existed. Accepting it
+	 * and dropping the skills would produce a plugin reporting `enabled`
+	 * that contributes nothing its author declared.
+	 */
+	skillRegistry?: SkillRegistry
 	log: Logger
 	hookTimeoutMs?: number
+	/**
+	 * Where each MCP server's reconnect policy is registered, so an operator
+	 * can retune it while a run is live.
+	 *
+	 * Optional, and its absence is not a degraded mode: without one the
+	 * supervisor uses its own defaults, which is what it did before this
+	 * existed. What a registry buys is the ability to change them without
+	 * restarting the process — see `config/registry.ts`.
+	 */
+	configRegistry?: ConfigRegistry
 
 	/**
 	 * What each MCP server a plugin brings is allowed to contribute, keyed by
@@ -84,6 +122,7 @@ export class PluginLifecycleManager {
 	> = new Map()
 	private pluginContributions: Map<PluginId, PluginContributionRecord> = new Map()
 	private hookTimeoutMs: number
+	private readonly configRegistry: ConfigRegistry | undefined
 	private log: Logger
 	/**
 	 * The admission boundary for everything a plugin's MCP servers advertise.
@@ -101,11 +140,15 @@ export class PluginLifecycleManager {
 	 */
 	private mcpDiscovery: MCPToolDiscovery
 
+	private readonly skillRegistry: SkillRegistry | undefined
+
 	constructor(config: PluginLifecycleManagerConfig) {
 		this.pluginRegistry = config.pluginRegistry
 		this.toolRegistry = config.toolRegistry
+		this.skillRegistry = config.skillRegistry
 		this.hookTimeoutMs = config.hookTimeoutMs ?? HOOK_TIMEOUT_MS
-		this.log = config.log.child({ component: 'PluginLifecycleManager' })
+		this.configRegistry = config.configRegistry
+		this.log = config.log.child({ [SCOPE_ATTRIBUTE]: 'plugin/lifecycle' })
 		this.mcpDiscovery = new MCPToolDiscovery([], {
 			...(config.mcpToolPolicies ? { policies: config.mcpToolPolicies } : {}),
 			...(config.onMCPToolDrift ? { onDrift: config.onMCPToolDrift } : {}),
@@ -178,10 +221,11 @@ export class PluginLifecycleManager {
 			scope,
 		})
 
-		this.log.info(`Plugin installed: ${manifest.name}`, {
-			pluginId,
-			scope,
-			version: manifest.version,
+		this.log.info('Plugin installed', {
+			'namzu.plugin.name': manifest.name,
+			'namzu.plugin.id': pluginId,
+			'namzu.plugin.scope': scope,
+			'namzu.plugin.version': manifest.version,
 		})
 
 		return definition
@@ -206,13 +250,18 @@ export class PluginLifecycleManager {
 		// `installed`: a status that says the plugin is fine while it can
 		// never enable is how the next reader gets misled.
 		try {
-			assertEnableable(manifest)
+			assertEnableable(manifest, { skillsSupported: Boolean(this.skillRegistry) })
 		} catch (err) {
 			this.pluginRegistry.register({ ...plugin, status: 'error' })
 			throw err
 		}
 
-		const contributions: PluginContributionRecord = { toolNames: [], mcpClients: [] }
+		const contributions: PluginContributionRecord = {
+			toolNames: [],
+			mcpClients: [],
+			skillNames: [],
+			mcpSupervisors: [],
+		}
 
 		try {
 			// Load tools
@@ -237,6 +286,33 @@ export class PluginLifecycleManager {
 				}
 			}
 
+			// Load skills. Namespaced like tools, and for the same reason: two
+			// plugins shipping `reconcile` would otherwise overwrite each
+			// other in a Map keyed by the frontmatter name, and the loser
+			// would vanish with nothing reporting it.
+			if (manifest.skills && manifest.skills.length > 0) {
+				const skillRegistry = this.skillRegistry
+				if (!skillRegistry) {
+					// Unreachable via `enable` — `assertEnableable` above refuses
+					// first — and kept because this method is also the one a
+					// future caller reaches directly. A silent skip here would
+					// be the exact failure that check exists to prevent.
+					throw new Error(
+						`Plugin "${manifest.name}" declares skills but no SkillRegistry is configured.`,
+					)
+				}
+				for (const skillPath of manifest.skills) {
+					const absolutePath = await resolveWithinReal(plugin.rootDir, skillPath)
+					const { skill } = await loadSkill(absolutePath, 'metadata', this.log)
+					const namespacedName = manifest.name + PLUGIN_NAMESPACE_SEPARATOR + skill.metadata.name
+					skillRegistry.add(namespacedName, {
+						...skill,
+						metadata: { ...skill.metadata, name: namespacedName },
+					})
+					contributions.skillNames.push(namespacedName)
+				}
+			}
+
 			// Load hooks
 			if (manifest.hooks && manifest.hooks.length > 0) {
 				for (const hookPath of manifest.hooks) {
@@ -282,10 +358,16 @@ export class PluginLifecycleManager {
 			name: manifest.name,
 		})
 
-		this.log.info(`Plugin enabled: ${manifest.name}`, {
-			pluginId,
-			toolCount: contributions.toolNames.length,
-			mcpServerCount: contributions.mcpClients.length,
+		this.log.info('Plugin enabled', {
+			// Every key namespaced, not just the newest one. Adding a bare
+			// `skillCount` beside bare neighbours would have moved the
+			// log-standard ratchet the wrong way for the sake of matching
+			// prose that is itself the debt.
+			'namzu.plugin.id': pluginId,
+			'namzu.plugin.name': manifest.name,
+			'namzu.plugin.tool_count': contributions.toolNames.length,
+			'namzu.plugin.skill_count': contributions.skillNames.length,
+			'namzu.plugin.mcp_server_count': contributions.mcpClients.length,
 		})
 	}
 
@@ -302,11 +384,36 @@ export class PluginLifecycleManager {
 				args: config.args ? [...config.args] : undefined,
 				env: config.env ? { ...config.env } : undefined,
 			},
+			logger: this.log,
 		})
 
 		await client.connect()
 		contributions.mcpClients.push(client)
 
+		// Watched from here on. `connect()` above is the only attempt anything
+		// made: `transport.onClose` marked the client disconnected and rejected
+		// its pending calls, and nothing scheduled another try — so one blip
+		// took this plugin's tools out for the life of the process while the
+		// plugin went on reporting as enabled.
+		// The policy is read from the registry on EVERY attempt, not captured
+		// here. That is what makes the seam live: raising `maxAttempts` during
+		// an outage takes effect on the retry that is already running, which is
+		// the moment an operator actually reaches for it.
+		//
+		// Namespaced per server rather than globally, because two plugins'
+		// servers fail differently — one behind a flaky proxy wants patience,
+		// one behind a crash loop wants to give up and say so.
+		const policyScope = this.configRegistry?.register(
+			`mcp.${config.name}`,
+			MCPReconnectOptionsSchema,
+		)
+		const supervisor = new MCPReconnectSupervisor(
+			client,
+			policyScope ? () => policyScope.get() : {},
+		)
+		supervisor.start()
+		contributions.mcpSupervisors.push(supervisor)
+
 		// Through the boundary, not around it. This used to call
 		// `client.listTools()` and register everything the server answered
 		// with, so the remote side decided what entered the agent's registry
@@ -346,18 +453,28 @@ export class PluginLifecycleManager {
 				this.toolRegistry.unregister(name)
 			} catch (unregErr) {
 				this.log.warn('Rollback: tool unregister failed', {
-					tool: name,
-					error: toErrorMessage(unregErr),
+					[GENAI.TOOL_NAME]: name,
+					'exception.message': toErrorMessage(unregErr),
 				})
 			}
 		}
+		for (const name of contributions.skillNames) {
+			// No try/catch: `unregister` is a Map delete and cannot throw.
+			// Wrapping it would suggest a failure mode that does not exist.
+			this.skillRegistry?.unregister(name)
+		}
+		// Stop supervising BEFORE disconnecting. The lifecycle event a
+		// deliberate disconnect emits is the same one a dropped transport
+		// emits, so a still-attached supervisor would reconnect what this
+		// rollback just closed.
+		for (const supervisor of contributions.mcpSupervisors) supervisor.stop()
 		for (const client of contributions.mcpClients) {
 			try {
 				await client.disconnect()
 			} catch (discErr) {
 				this.log.warn('Rollback: MCP disconnect failed', {
-					clientId: client.id,
-					error: toErrorMessage(discErr),
+					'namzu.mcp.client_id': client.id,
+					'exception.message': toErrorMessage(discErr),
 				})
 			}
 		}
@@ -383,16 +500,21 @@ export class PluginLifecycleManager {
 		const contributions = this.pluginContributions.get(pluginId) ?? {
 			toolNames: [],
 			mcpClients: [],
+			skillNames: [],
+			mcpSupervisors: [],
 		}
 
+		// Stop supervising first, for the same reason as the rollback path: the
+		// disconnect below emits the event the supervisor treats as a fault.
+		for (const supervisor of contributions.mcpSupervisors) supervisor.stop()
 		// Disconnect MCP clients first so no new tool calls can reach them mid-teardown.
 		for (const client of contributions.mcpClients) {
 			try {
 				await client.disconnect()
 			} catch (err) {
 				this.log.warn('MCP client disconnect failed during disable', {
-					clientId: client.id,
-					error: toErrorMessage(err),
+					'namzu.mcp.client_id': client.id,
+					'exception.message': toErrorMessage(err),
 				})
 			}
 		}
@@ -402,6 +524,14 @@ export class PluginLifecycleManager {
 			this.toolRegistry.unregister(name)
 		}
 
+		// And its skills. A disabled plugin whose skills stayed registered
+		// would keep offering the model instructions from something the
+		// runtime has switched off, which is worse than a stale tool: a tool
+		// call would at least fail, and a skill is followed silently.
+		for (const name of contributions.skillNames) {
+			this.skillRegistry?.unregister(name)
+		}
+
 		// Remove hook handlers for this plugin
 		for (const [event, handlers] of this.hookHandlers) {
 			const filtered = handlers.filter((h) => h.pluginId !== pluginId)
@@ -428,7 +558,10 @@ export class PluginLifecycleManager {
 			name: plugin.manifest.name,
 		})
 
-		this.log.info(`Plugin disabled: ${plugin.manifest.name}`, { pluginId })
+		this.log.info('Plugin disabled', {
+			'namzu.plugin.name': plugin.manifest.name,
+			'namzu.plugin.id': pluginId,
+		})
 	}
 
 	async uninstall(pluginId: PluginId): Promise<void> {
@@ -446,7 +579,10 @@ export class PluginLifecycleManager {
 			name: plugin.manifest.name,
 		})
 
-		this.log.info(`Plugin uninstalled: ${plugin.manifest.name}`, { pluginId })
+		this.log.info('Plugin uninstalled', {
+			'namzu.plugin.name': plugin.manifest.name,
+			'namzu.plugin.id': pluginId,
+		})
 	}
 
 	async executeHooks(
@@ -576,7 +712,7 @@ export class PluginLifecycleManager {
 				listener(event)
 			} catch (err) {
 				this.log.error('Plugin event listener error', {
-					error: toErrorMessage(err),
+					'exception.message': toErrorMessage(err),
 				})
 			}
 		}

package/src/plugin/loader.ts

@@ -7,15 +7,27 @@ import {
 	USER_PLUGIN_DIR,
 } from '../constants/plugin/index.js'
 import { type PluginManifest, PluginManifestSchema } from '../types/plugin/index.js'
-import { getRootLogger } from '../utils/logger.js'
-
-const logger = getRootLogger().child({ component: 'PluginLoader' })
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
+import { type Logger, resolveLogger } from '../utils/logger.js'
 
 /**
  * Scans a directory for subdirectories containing a plugin manifest.
  * Returns an array of absolute paths to plugin directories.
  */
-export async function discoverPlugins(parentDir: string): Promise<string[]> {
+export async function discoverPlugins(parentDir: string, log?: Logger): Promise<string[]> {
+	// Resolved here, not at module scope. A module-scope
+	// `getRootLogger().child(...)` ran once, at import time — before any
+	// host's `configureLogger()` call had a chance to run — and `child()`
+	// bakes `minLevel` into the closure `log()` reads from forever after
+	// (`utils/logger.ts`), so whatever level was live at that one moment
+	// was permanent. `configureLogger` replaces the `_rootLogger` binding
+	// rather than mutating the object it points at, so caching the CHILD
+	// (as this loader did) survives no later call at all — including the
+	// CLI's own `configureLogger({ level: 'silent' })`.
+	//
+	// `log`, when a caller has one, wins over the process default — LOG-10:
+	// this was the module's own remaining getRootLogger() call site.
+	const logger = resolveLogger(log).child({ [SCOPE_ATTRIBUTE]: 'plugin/loader' })
 	const dirs: string[] = []
 
 	try {
@@ -31,7 +43,7 @@ export async function discoverPlugins(parentDir: string): Promise<string[]> {
 			// directory listed is not the directory loaded.
 			const s = await lstat(fullPath)
 			if (s.isSymbolicLink()) {
-				logger.warn('Refusing a symlinked plugin directory', { path: fullPath })
+				logger.warn('Refusing a symlinked plugin directory', { 'namzu.plugin.path': fullPath })
 				continue
 			}
 			if (!s.isDirectory()) continue
@@ -45,7 +57,7 @@ export async function discoverPlugins(parentDir: string): Promise<string[]> {
 			}
 		}
 	} catch {
-		logger.debug('Plugins directory not found', { parentDir })
+		logger.debug('Plugins directory not found', { 'namzu.plugin.parent_dir': parentDir })
 	}
 
 	return dirs
@@ -72,7 +84,18 @@ export async function loadPluginManifest(pluginDir: string): Promise<PluginManif
  * shipping four tools and one skill validated clean, installed clean, and
  * contributed zero tools. The refusal was right; its position was not.
  */
-const UNSUPPORTED_CONTRIBUTIONS = ['skills', 'connectors', 'personas'] as const
+/**
+ * Contribution types the runtime can enable only when the host supplies the
+ * registry they land in.
+ *
+ * `skills` moved here from the flat unsupported list once the manifest path
+ * into `SkillRegistry` existed. It is still refused when there is no
+ * registry — and refused rather than dropped, because a plugin whose skills
+ * silently vanished would report `enabled` and contribute nothing the
+ * author declared, which is the same lie the wholesale refusal was written
+ * to prevent.
+ */
+const REGISTRY_BACKED_CONTRIBUTIONS = ['skills'] as const
 
 /**
  * Refuse a manifest whose contributions can never be enabled.
@@ -88,9 +111,32 @@ const UNSUPPORTED_CONTRIBUTIONS = ['skills', 'connectors', 'personas'] as const
  * through host configuration; what does not exist is the manifest path
  * into them. Naming the types is what makes that actionable.
  */
-export function assertEnableable(manifest: PluginManifest): void {
+export interface EnableableOptions {
+	/**
+	 * Whether the host wired a `SkillRegistry`.
+	 *
+	 * Defaults to `false`, which keeps the previous behaviour for every
+	 * caller that has not been updated: a manifest declaring skills is
+	 * refused. The check cannot default the other way — a host that never
+	 * supplied a registry would then install a plugin whose skills go
+	 * nowhere.
+	 */
+	readonly skillsSupported?: boolean
+}
+
+export function assertEnableable(manifest: PluginManifest, opts: EnableableOptions = {}): void {
 	const record = manifest as unknown as Record<string, unknown[] | undefined>
-	const unsupported = UNSUPPORTED_CONTRIBUTIONS.filter((key) => record[key]?.length)
+	// One ordered pass over all three rather than two group filters
+	// concatenated, so the message keeps naming them in the order the
+	// manifest declares them. Two groups would list `connectors, personas,
+	// skills`, which reads as though the grouping were the point rather than
+	// an implementation detail of which registry each one needs.
+	const enableable = (key: string): boolean =>
+		opts.skillsSupported === true &&
+		(REGISTRY_BACKED_CONTRIBUTIONS as readonly string[]).includes(key)
+	const unsupported = ['skills', 'connectors', 'personas'].filter(
+		(key) => Boolean(record[key]?.length) && !enableable(key),
+	)
 	if (unsupported.length === 0) return
 
 	throw new Error(
@@ -114,6 +160,8 @@ export interface PluginDiscoveryOptions {
 	readonly autoDiscovery?: boolean
 	/** Which locations may be scanned. Absent means both. */
 	readonly allowedScopes?: readonly PluginScope[]
+	/** Threaded into both `discoverPlugins` calls below. */
+	readonly log?: Logger
 }
 
 /**
@@ -144,10 +192,13 @@ export async function discoverAllPluginDirs(
 	workingDirectory?: string,
 	options?: PluginDiscoveryOptions,
 ): Promise<{ project: string[]; user: string[] }> {
+	// Resolved here too — see discoverPlugins above for why module scope
+	// froze this logger's level, and its very reference, at import time.
+	const logger = resolveLogger(options?.log).child({ [SCOPE_ATTRIBUTE]: 'plugin/loader' })
 	if (options?.enabled === false || options?.autoDiscovery === false) {
 		logger.debug('Plugin discovery skipped', {
-			enabled: options.enabled,
-			autoDiscovery: options.autoDiscovery,
+			'namzu.plugin.enabled': options.enabled,
+			'namzu.plugin.auto_discovery': options.autoDiscovery,
 		})
 		return { project: [], user: [] }
 	}
@@ -161,14 +212,14 @@ export async function discoverAllPluginDirs(
 	const userDir = join(homedir(), USER_PLUGIN_DIR)
 
 	const [project, user] = await Promise.all([
-		mayScan('project') ? discoverPlugins(projectDir) : Promise.resolve([]),
-		mayScan('user') ? discoverPlugins(userDir) : Promise.resolve([]),
+		mayScan('project') ? discoverPlugins(projectDir, options?.log) : Promise.resolve([]),
+		mayScan('user') ? discoverPlugins(userDir, options?.log) : Promise.resolve([]),
 	])
 
 	logger.debug('Plugin discovery complete', {
-		projectCount: project.length,
-		userCount: user.length,
-		...(scopes ? { allowedScopes: scopes } : {}),
+		'namzu.plugin.project_count': project.length,
+		'namzu.plugin.user_count': user.length,
+		...(scopes ? { 'namzu.plugin.allowed_scopes': scopes } : {}),
 	})
 
 	return { project, user }

package/src/probe/index.ts

@@ -2,3 +2,4 @@ export { ProbeNameCollisionError, ProbeVetoError } from './errors.js'
 export { buildProbeContext } from './context.js'
 export type { ProbeContextInput } from './context.js'
 export { ProbeRegistry, createProbeRegistry, probe } from './registry.js'
+export type { ProbeEnforcement, ProbeObservation } from './registry.js'

package/src/probe/registry.ts

@@ -11,6 +11,7 @@ import type {
 	VetoOutcome,
 	VetoableEventKind,
 } from '../types/probe/index.js'
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
 import type { Logger } from '../utils/logger.js'
 
 import { ProbeNameCollisionError } from './errors.js'
@@ -79,7 +80,42 @@ function removeEntry(list: ProbeEntry[], entry: ProbeEntry): void {
 	if (idx >= 0) list.splice(idx, 1)
 }
 
-export class ProbeRegistry {
+/**
+ * The observation half: watch, and record what you saw.
+ *
+ * Split from the enforcement half because `ProbeRegistry` was described,
+ * in the SDK's own barrel, as "typed observation" — which is true of these
+ * four methods and false of the two below. A registered veto handler can
+ * DENY a tool call, and `runtime/query/executor.ts` turns that denial into
+ * a failed `tool_result`. That is the third of the three gates on a tool
+ * call, not telemetry.
+ *
+ * A consumer that wants telemetry had no way to say so: `ProbeRegistry`
+ * was the only export, so accepting one meant accepting the power to
+ * refuse. These two interfaces are what let a signature say which half it
+ * needs, and the class implements both unchanged.
+ */
+export interface ProbeObservation {
+	setLogger(log: Logger): void
+	on: ProbeRegistry['on']
+	onAny: ProbeRegistry['onAny']
+	dispatch: ProbeRegistry['dispatch']
+}
+
+/**
+ * The enforcement half: refuse, and make the refusal the outcome.
+ *
+ * `veto` registers a handler that can deny; `queryVeto` asks the
+ * registered handlers and returns their verdict. A caller holding only
+ * this cannot observe, and a caller holding only {@link ProbeObservation}
+ * cannot refuse.
+ */
+export interface ProbeEnforcement {
+	veto: ProbeRegistry['veto']
+	queryVeto: ProbeRegistry['queryVeto']
+}
+
+export class ProbeRegistry implements ProbeObservation, ProbeEnforcement {
 	private readonly typedByKind: Map<ProbeEventKind, ProbeEntry[]> = new Map()
 	private readonly vetoByKind: Map<VetoableEventKind, VetoEntry[]> = new Map()
 	private readonly catchAll: ProbeEntry[] = []
@@ -88,7 +124,7 @@ export class ProbeRegistry {
 	private log?: Logger
 
 	setLogger(log: Logger): void {
-		this.log = log.child({ component: 'ProbeRegistry' })
+		this.log = log.child({ [SCOPE_ATTRIBUTE]: 'probe/registry' })
 	}
 
 	on<K extends ProbeEventKind>(
@@ -282,9 +318,9 @@ export class ProbeRegistry {
 	private logThrow(probeName: string, eventType: string, error: unknown): void {
 		if (!this.log) return
 		this.log.error('probe handler threw', {
-			probeName,
-			eventType,
-			error: error instanceof Error ? error.message : String(error),
+			'namzu.probe.probe_name': probeName,
+			'namzu.event.type': eventType,
+			'exception.message': error instanceof Error ? error.message : String(error),
 		})
 	}
 }

package/src/process/kill-tree.ts

@@ -0,0 +1,52 @@
+import { execFileSync } from 'node:child_process'
+import type { spawn } from 'node:child_process'
+
+/**
+ * Signal a spawned child AND everything it forked.
+ *
+ * Extracted from `sandbox/provider/local.ts` unchanged, because a second
+ * caller arrived — the background job registry — and this is not a function
+ * anybody should write twice. Every sentence of the reasoning below was
+ * paid for by a bug where a cancelled command kept running, and a
+ * near-copy would reproduce the bug in the copy.
+ *
+ * Every caller reaches a real command through `/bin/sh -c "cmd"`, and under
+ * the local sandbox's `linux-namespace`/`macos-seatbelt` tiers that shell is
+ * wrapped again (`unshare …`/`sandbox-exec … -- /bin/sh -c "cmd"`). Either
+ * way, `child.pid` names the OUTERMOST wrapper Node spawned, not `cmd` —
+ * signalling only that pid, which is both what `child.kill()` does and what
+ * `spawn`'s own `signal` option does internally on abort, reaps the wrapper
+ * and leaves `cmd`, and anything it forked, running past both a cancel and a
+ * timeout.
+ *
+ * POSIX: the caller must spawn with `detached: true`, which makes the child
+ * the leader of a new process group (pgid === pid) instead of joining this
+ * Node process's own. A negative pid signals that whole group in one call.
+ * Group membership is a host-kernel fact that a fork()'d descendant inherits
+ * from its parent whether or not it — or an ancestor such as `unshare --pid`
+ * — subsequently entered a new PID namespace, so this reaches `cmd` and its
+ * descendants along with the wrapper itself even under the namespaced
+ * isolation tiers.
+ *
+ * Windows has no process-group id to sign a kill with — `process.kill` with
+ * a negative pid there either throws or silently does nothing, depending on
+ * the signal — so there is no equivalent single call. The OS's own
+ * tree-walk, `taskkill /T`, runs instead. Windows also has no soft-vs-forced
+ * distinction the way SIGTERM/SIGKILL do: `child.kill()` there already
+ * terminates unconditionally, so `/F` is passed every time this runs,
+ * including the post-grace call that follows a POSIX SIGTERM — against an
+ * already-dead tree that second call is a deliberate no-op, the same as the
+ * POSIX SIGKILL that follows a SIGTERM which already worked.
+ */
+export function killTree(child: ReturnType<typeof spawn>, signal: NodeJS.Signals): void {
+	if (!child.pid) return
+	try {
+		if (process.platform === 'win32') {
+			execFileSync('taskkill', ['/pid', String(child.pid), '/t', '/f'], { stdio: 'ignore' })
+		} else {
+			process.kill(-child.pid, signal)
+		}
+	} catch {
+		// Group (or tree) already gone
+	}
+}