@agentuity/cli 2.0.10 → 2.0.12

package/src/cmd/cloud/sandbox/util.ts

@@ -1,17 +1,69 @@
-import { readFileSync } from 'node:fs';
+import { fstatSync, readFileSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
 import type { FileToWrite, Logger } from '@agentuity/core';
-import { APIClient, getServiceUrls, sandboxGet } from '@agentuity/server';
+import { APIClient, getServiceUrls, sandboxGet, sandboxResolve } from '@agentuity/server';
 import { deleteResourceRegion, getResourceInfo, setResourceInfo } from '../../../cache';
 import { getGlobalCatalystAPIClient } from '../../../config';
 import { ErrorCode } from '../../../errors';
 import * as tui from '../../../tui';
 import type { AuthData, Config } from '../../../types';
 
+/**
+ * Detect if a file descriptor is redirected to /dev/null (or NUL on Windows).
+ * Used to optimize stream creation - when output goes to /dev/null, we can
+ * skip creating the stream entirely on the server.
+ *
+ * @param fd - File descriptor (1 for stdout, 2 for stderr)
+ * @returns true if the fd points to /dev/null
+ */
+export function detectNullStream(fd: number): boolean {
+	try {
+		const fdStat = fstatSync(fd);
+		const nullPath = process.platform === 'win32' ? 'NUL' : '/dev/null';
+		const nullStat = statSync(nullPath);
+		return fdStat.dev === nullStat.dev && fdStat.ino === nullStat.ino;
+	} catch {
+		return false;
+	}
+}
+
 export function createSandboxClient(logger: Logger, auth: AuthData, region: string): APIClient {
 	return new APIClient(getServiceUrls(region).catalyst, logger, auth.apiKey);
 }
 
+export interface ResolvedSandboxTarget {
+	region: string;
+	orgId: string;
+}
+
+/**
+ * Resolve sandbox routing context using cache-first lookup.
+ * Falls back to the CLI resolve endpoint on cache miss or partial cache.
+ */
+export async function resolveSandboxTarget(
+	logger: Logger,
+	auth: AuthData,
+	apiClient: APIClient | null = null,
+	sandboxId: string,
+	profileName = 'production',
+	config?: Config | null
+): Promise<ResolvedSandboxTarget> {
+	const cachedInfo = await getResourceInfo('sandbox', profileName, sandboxId);
+	if (cachedInfo?.region && cachedInfo?.orgId) {
+		logger.trace(
+			`[sandbox] Found cached target for ${sandboxId}: ${cachedInfo.region}/${cachedInfo.orgId}`
+		);
+		return { region: cachedInfo.region, orgId: cachedInfo.orgId };
+	}
+
+	logger.trace(`[sandbox] Cache miss for target ${sandboxId}, resolving via CLI API`);
+	const globalClient =
+		apiClient ?? (await getGlobalCatalystAPIClient(logger, auth, profileName, undefined, config));
+	const sandbox = await sandboxResolve(globalClient, sandboxId);
+	await setResourceInfo('sandbox', profileName, sandboxId, sandbox.region, sandbox.orgId);
+	return { region: sandbox.region, orgId: sandbox.orgId };
+}
+
 /**
  * Look up the region for a sandbox, using cache-first strategy.
  * Falls back to API lookup if not in cache.
@@ -64,6 +116,15 @@ export async function cacheSandboxRegion(
 	await setResourceInfo('sandbox', profileName, sandboxId, region);
 }
 
+export async function cacheSandboxTarget(
+	profileName = 'production',
+	sandboxId: string,
+	region: string,
+	orgId?: string
+): Promise<void> {
+	await setResourceInfo('sandbox', profileName, sandboxId, region, orgId);
+}
+
 /**
  * Clear cached region for a sandbox after delete
  */

package/src/cmd/coder/create.ts

@@ -44,6 +44,12 @@ export const createCoderSubcommand = createSubcommand({
 			),
 			description: 'Create with label and tags, return JSON',
 		},
+		{
+			command: getCommand(
+				'coder create "Review this change" --default-agent code-review --enabled-agents code-review'
+			),
+			description: 'Create with a selected agent roster and a custom default route target',
+		},
 	],
 	schema: {
 		args: z.object({
@@ -61,6 +67,10 @@ export const createCoderSubcommand = createSubcommand({
 			// Session config
 			label: z.string().optional().describe('Human-readable session label'),
 			agent: z.string().optional().describe('Default agent role (e.g. lead, scout)'),
+			defaultAgent: z
+				.string()
+				.optional()
+				.describe('Preferred default agent slug or built-in route target'),
 			visibility: z
 				.string()
 				.optional()
@@ -86,6 +96,10 @@ export const createCoderSubcommand = createSubcommand({
 			// Resources
 			workspaceId: z.string().optional().describe('Workspace ID to use'),
 			tags: z.string().optional().describe('Comma-separated tags'),
+			enabledAgents: z
+				.string()
+				.optional()
+				.describe('Comma-separated built-in/custom agents to include'),
 			env: z
 				.string()
 				.optional()
@@ -105,10 +119,14 @@ export const createCoderSubcommand = createSubcommand({
 		});
 
 		// Build the create session request body from flags
-		const body: CoderCreateSessionRequest = {
+		const body: CoderCreateSessionRequest & {
+			defaultAgent?: string;
+			enabledAgents?: string[];
+		} = {
 			task: args.task,
 			...(opts?.label && { label: opts.label }),
 			...(opts?.agent && { agent: opts.agent }),
+			...(opts?.defaultAgent && { defaultAgent: opts.defaultAgent }),
 			...(opts?.visibility && { visibility: normalizeVisibility(opts.visibility) }),
 			...(opts?.workflowMode && { workflowMode: opts.workflowMode as 'standard' | 'loop' }),
 		};
@@ -149,6 +167,11 @@ export const createCoderSubcommand = createSubcommand({
 				.split(',')
 				.map((t) => t.trim())
 				.filter(Boolean);
+		if (opts?.enabledAgents)
+			body.enabledAgents = opts.enabledAgents
+				.split(',')
+				.map((name) => name.trim())
+				.filter(Boolean);
 		if (opts?.savedSkillIds)
 			body.savedSkillIds = opts.savedSkillIds
 				.split(',')

package/src/cmd/coder/index.ts

@@ -24,6 +24,10 @@ export const command = createCommand({
 			command: getCommand('coder start'),
 			description: 'Start a coding session connected to Coder',
 		},
+		{
+			command: getCommand('coder start --dir ~/path/to/my/project'),
+			description: 'Start a coding session from a specific local project directory',
+		},
 		{
 			command: getCommand('coder create "Build a REST API"'),
 			description: 'Create a new Coder session with a task',

package/src/cmd/coder/start.ts

@@ -1,4 +1,6 @@
 import { dirname, resolve } from 'node:path';
+import { stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
 import { z } from 'zod';
 import { CoderClient, type CoderSessionListItem } from '@agentuity/core/coder';
 import { ValidationOutputError } from '@agentuity/core';
@@ -64,6 +66,10 @@ export const startSubcommand = createSubcommand({
 			command: getCommand('coder start'),
 			description: 'Start Pi with auto-detected Hub and extension',
 		},
+		{
+			command: getCommand('coder start --dir ~/path/to/my/project'),
+			description: 'Start from a specific local project directory',
+		},
 		{
 			command: getCommand('coder start --url ws://127.0.0.1:3500/api/ws'),
 			description: 'Start with explicit Coder URL',
@@ -97,6 +103,7 @@ export const startSubcommand = createSubcommand({
 	],
 	schema: {
 		options: z.object({
+			dir: z.string().optional().describe('Local project directory to start from'),
 			url: z.string().optional().describe('Coder API URL override'),
 			extension: z.string().optional().describe('Coder extension path override'),
 			pi: z.string().optional().describe('Path to pi binary'),
@@ -121,6 +128,32 @@ export const startSubcommand = createSubcommand({
 	},
 	async handler(ctx) {
 		const { opts, options } = ctx;
+		// Keep Pi's interactive install telemetry disabled for Agentuity CLI sessions.
+		process.env.PI_TELEMETRY = '0';
+
+		// Resolve working directory from optional --dir option
+		let cwd = process.cwd();
+		if (opts?.dir) {
+			// Warn if --dir is provided with --remote or --sandbox (dir is ignored in those modes)
+			if (opts?.remote !== undefined || opts?.sandbox !== undefined) {
+				tui.warning('--dir is ignored in remote/sandbox mode');
+			} else {
+				const raw = opts.dir.trim();
+				cwd =
+					raw === '~' || raw.startsWith('~/')
+						? resolve(homedir(), raw.slice(2))
+						: resolve(raw);
+
+				const st = await stat(cwd).catch(() => null);
+				if (!st?.isDirectory()) {
+					tui.fatal(
+						`The specified path is not a valid directory: ${cwd}`,
+						ErrorCode.CONFIG_INVALID
+					);
+					return;
+				}
+			}
+		}
 		const client = new CoderClient({
 			apiKey: ctx.auth.apiKey,
 			url: opts?.url,
@@ -216,6 +249,33 @@ export const startSubcommand = createSubcommand({
 		// with the coder extension loaded for Hub UI (footer, /hub, commands).
 		// Agent.emit() drives native rendering — no [remote_message] blocks.
 		if (remoteSessionId) {
+			try {
+				const session = await tui.spinner({
+					message: 'Preparing remote session…',
+					callback: async () => client.prepareSessionForRemoteAttach(remoteSessionId!),
+				});
+
+				if (session.historyOnly === true) {
+					tui.fatal(
+						`Session ${remoteSessionId} is history-only and cannot be attached remotely.`,
+						ErrorCode.CONFIG_INVALID
+					);
+					return;
+				}
+
+				if (session.runtimeAvailable === false) {
+					tui.fatal(
+						`Session ${remoteSessionId} is offline and could not be resumed for remote attach.`,
+						ErrorCode.NETWORK_ERROR
+					);
+					return;
+				}
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				tui.fatal(`Failed to prepare remote session: ${msg}`, ErrorCode.NETWORK_ERROR);
+				return;
+			}
+
 			if (!options.json) {
 				tui.newline();
 				tui.output(`  Hub:       ${tui.bold(hubWsUrl)}`);
@@ -330,6 +390,7 @@ export const startSubcommand = createSubcommand({
 			AGENTUITY_CODER_HUB_URL: hubWsUrl,
 		};
 		env.AGENTUITY_CODER_API_KEY = ctx.auth.apiKey;
+		env.AGENTUITY_ORGID = ctx.orgId;
 
 		if (opts?.agent) {
 			env.AGENTUITY_CODER_AGENT = opts.agent;
@@ -343,6 +404,7 @@ export const startSubcommand = createSubcommand({
 			tui.output(`  Hub:       ${tui.bold(hubWsUrl)}`);
 			tui.output(`  Extension: ${tui.bold(extensionPath)}`);
 			tui.output(`  Pi:        ${tui.bold(piBinary)}`);
+			if (opts?.dir) tui.output(`  Dir:       ${tui.bold(cwd)}`);
 			if (opts?.agent) tui.output(`  Agent:     ${tui.bold(opts.agent)}`);
 			tui.newline();
 		}
@@ -351,7 +413,7 @@ export const startSubcommand = createSubcommand({
 		try {
 			const proc = Bun.spawn([piBinary, ...piArgs], {
 				env,
-				cwd: process.cwd(),
+				cwd,
 				stdin: 'inherit',
 				stdout: 'inherit',
 				stderr: 'inherit',

package/src/cmd/coder/tui-init.ts

@@ -43,7 +43,7 @@ export async function probeHubInitAccess(
 	try {
 		const response = await fetchImpl(`${hubHttpUrl}/api/hub/init`, {
 			headers,
-			signal: AbortSignal.timeout(5_000),
+			signal: AbortSignal.timeout(10_000),
 		});
 
 		let payload: unknown;

package/src/cmd/coder/update.ts

@@ -40,6 +40,10 @@ export const updateSubcommand = createSubcommand({
 			url: z.string().optional().describe('Coder API URL override'),
 			label: z.string().optional().describe('Updated session label'),
 			agent: z.string().optional().describe('Updated default agent role'),
+			defaultAgent: z
+				.string()
+				.optional()
+				.describe('Updated preferred default agent slug or built-in route target'),
 			visibility: z
 				.string()
 				.optional()
@@ -50,6 +54,10 @@ export const updateSubcommand = createSubcommand({
 			loopAutoContinue: z.boolean().optional().describe('Auto-continue loop'),
 			loopAllowDetached: z.boolean().optional().describe('Allow detached loop execution'),
 			tags: z.string().optional().describe('Comma-separated tags (replaces existing)'),
+			enabledAgents: z
+				.string()
+				.optional()
+				.describe('Comma-separated built-in/custom agents (replaces existing)'),
 		}),
 	},
 	async handler(ctx) {
@@ -64,6 +72,7 @@ export const updateSubcommand = createSubcommand({
 
 		if (opts?.label) body.label = opts.label;
 		if (opts?.agent) body.agent = opts.agent;
+		if (opts?.defaultAgent) body.defaultAgent = opts.defaultAgent;
 		if (opts?.visibility) body.visibility = normalizeVisibility(opts.visibility);
 		if (opts?.workflowMode) body.workflowMode = opts.workflowMode;
 		if (opts?.tags) {
@@ -72,6 +81,12 @@ export const updateSubcommand = createSubcommand({
 				.map((t) => t.trim())
 				.filter(Boolean);
 		}
+		if (opts?.enabledAgents) {
+			body.enabledAgents = opts.enabledAgents
+				.split(',')
+				.map((name) => name.trim())
+				.filter(Boolean);
+		}
 
 		if (
 			opts?.loopGoal ||
@@ -90,7 +105,7 @@ export const updateSubcommand = createSubcommand({
 
 		if (Object.keys(body).length === 0) {
 			tui.fatal(
-				'No update fields provided. Use --label, --visibility, --tags, --agent, --workflow-mode, or loop options.',
+				'No update fields provided. Use --label, --visibility, --tags, --agent, --default-agent, --enabled-agents, --workflow-mode, or loop options.',
 				ErrorCode.VALIDATION_FAILED
 			);
 		}
@@ -109,6 +124,8 @@ export const updateSubcommand = createSubcommand({
 			if (opts?.visibility) fields.push(`Visibility: ${body.visibility}`);
 			if (opts?.tags) fields.push(`Tags: ${(body.tags as string[]).join(', ')}`);
 			if (opts?.agent) fields.push(`Agent: ${opts.agent}`);
+			if (opts?.defaultAgent) fields.push(`Default agent: ${opts.defaultAgent}`);
+			if (opts?.enabledAgents) fields.push(`Enabled agents: ${opts.enabledAgents}`);
 			if (opts?.workflowMode || body.loop) fields.push(`Workflow: ${body.workflowMode}`);
 
 			for (const f of fields) {

package/src/cmd/coder/workspace/create.ts

@@ -1,37 +1,66 @@
 import { z } from 'zod';
-import { CoderClient, type CoderCreateWorkspaceRequest } from '@agentuity/core/coder';
-import { ValidationOutputError } from '@agentuity/core';
+import { APIError, ValidationInputError, ValidationOutputError } from '@agentuity/core';
+import {
+	CoderClient,
+	CoderCreateWorkspaceRequestSchema,
+	type CoderCreateWorkspaceRequest,
+} from '@agentuity/core/coder';
 import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { getCommand } from '../../../command-prefix';
 import { ErrorCode } from '../../../errors';
 import { resolveGitHubRepo } from '../resolve-repo';
 
+const EMPTY_WORKSPACE_ERROR =
+	'A workspace needs at least one repo, saved skill, skill bucket, or agent';
+
+function hasWorkspaceSelections(input: CoderCreateWorkspaceRequest): boolean {
+	return (
+		(input.repos?.length ?? 0) > 0 ||
+		(input.savedSkillIds?.length ?? 0) > 0 ||
+		(input.skillBucketIds?.length ?? 0) > 0 ||
+		(input.enabledAgents?.length ?? 0) > 0
+	);
+}
+
+function formatWorkspaceValidationMessage(issues: Array<{ message: string }>): string {
+	const messages = [...new Set(issues.map((issue) => issue.message).filter(Boolean))];
+	if (messages.length === 0) {
+		return 'Invalid workspace configuration';
+	}
+	if (messages.includes(EMPTY_WORKSPACE_ERROR)) {
+		return `${EMPTY_WORKSPACE_ERROR}. Use --repo or --enabled-agents.`;
+	}
+	return messages.join('; ');
+}
+
 export const createWorkspaceSubcommand = createSubcommand({
 	name: 'create',
 	aliases: ['new', 'add'],
-	description: 'Create a new Coder workspace',
+	description: 'Create a new Coder workspace with at least one repo or agent',
 	tags: ['mutating', 'requires-auth'],
 	requires: { auth: true, org: true },
 	examples: [
-		{
-			command: getCommand('coder workspace create "My Workspace"'),
-			description: 'Create a workspace with a name',
-		},
 		{
 			command: getCommand(
-				'coder workspace create "My Workspace" --description "For frontend work" --scope org'
+				'coder workspace create "My Workspace" --repo https://github.com/org/repo --repo-branch main'
 			),
-			description: 'Create an org-scoped workspace with description',
+			description: 'Create a workspace with a repository',
 		},
 		{
 			command: getCommand(
-				'coder workspace create "My Workspace" --repo https://github.com/org/repo --repo-branch main'
+				'coder workspace create "My Workspace" --enabled-agents code-review --description "For frontend work" --scope org'
 			),
-			description: 'Create a workspace with a repository',
+			description: 'Create an org-scoped workspace with description and agents',
 		},
 		{
-			command: getCommand('coder workspace create "My Workspace" --json'),
+			command: getCommand('coder workspace create "My Workspace" --enabled-agents code-review'),
+			description: 'Create a workspace with an agent roster',
+		},
+		{
+			command: getCommand(
+				'coder workspace create "My Workspace" --enabled-agents code-review --json'
+			),
 			description: 'Create a workspace and return JSON output',
 		},
 	],
@@ -45,6 +74,10 @@ export const createWorkspaceSubcommand = createSubcommand({
 			scope: z.string().optional().describe('Workspace scope: user or org'),
 			repo: z.string().optional().describe('Repository URL to add'),
 			repoBranch: z.string().optional().describe('Branch for the repository'),
+			enabledAgents: z
+				.string()
+				.optional()
+				.describe('Comma-separated built-in/custom agents to include'),
 		}),
 	},
 	async handler(ctx) {
@@ -72,9 +105,36 @@ export const createWorkspaceSubcommand = createSubcommand({
 				return;
 			}
 		}
+		if (opts?.enabledAgents) {
+			body.enabledAgents = opts.enabledAgents
+				.split(',')
+				.map((name) => name.trim())
+				.filter(Boolean);
+		}
+		if (!hasWorkspaceSelections(body)) {
+			tui.fatal(
+				`Failed to create workspace: ${EMPTY_WORKSPACE_ERROR}. Use --repo or --enabled-agents.`,
+				ErrorCode.VALIDATION_FAILED
+			);
+		}
+
+		const validationResult = CoderCreateWorkspaceRequestSchema.safeParse(body);
+		if (!validationResult.success) {
+			ctx.logger.trace(
+				'Validation issues: %s',
+				JSON.stringify(validationResult.error.issues, null, 2)
+			);
+			tui.fatal(
+				`Failed to create workspace: ${formatWorkspaceValidationMessage(validationResult.error.issues)}`,
+				ErrorCode.VALIDATION_FAILED
+			);
+		}
 
 		try {
-			const created = await client.createWorkspace(body);
+			const created = await client.createWorkspace(validationResult.data);
+			const createdEnabledAgents = Array.isArray(created.enabledAgents)
+				? created.enabledAgents.filter((name): name is string => typeof name === 'string')
+				: [];
 
 			if (options.json) {
 				return created;
@@ -88,13 +148,22 @@ export const createWorkspaceSubcommand = createSubcommand({
 			}
 			tui.output(`  Scope:       ${created.scope}`);
 			tui.output(`  Repos:       ${created.repoCount}`);
-			tui.output(`  Skills:      ${created.selectionCount}`);
+			tui.output(`  Selections:  ${created.selectionCount}`);
+			if (createdEnabledAgents.length > 0) {
+				tui.output(`  Agents:      ${createdEnabledAgents.join(', ')}`);
+			}
 
 			return created;
 		} catch (err) {
-			if (err instanceof ValidationOutputError) {
+			if (err instanceof ValidationInputError || err instanceof ValidationOutputError) {
 				ctx.logger.trace('Validation response URL: %s', err.url ?? 'unknown');
 				ctx.logger.trace('Validation issues: %s', JSON.stringify(err.issues, null, 2));
+				tui.fatal(
+					`Failed to create workspace: ${formatWorkspaceValidationMessage(err.issues)}`,
+					ErrorCode.VALIDATION_FAILED
+				);
+			}
+			if (err instanceof APIError && err.status >= 400 && err.status < 500) {
 				tui.fatal(`Failed to create workspace: ${err.message}`, ErrorCode.VALIDATION_FAILED);
 			}
 			const msg = err instanceof Error ? err.message : String(err);

package/src/cmd/coder/workspace/index.ts

@@ -17,7 +17,9 @@ export const workspaceCommand = createCommand({
 			description: 'List all workspaces',
 		},
 		{
-			command: getCommand('coder workspace create "My Workspace"'),
+			command: getCommand(
+				'coder workspace create "My Workspace" --repo https://github.com/org/repo'
+			),
 			description: 'Create a new workspace',
 		},
 		{

package/src/cmd/coder/workspace/list.ts

@@ -83,7 +83,7 @@ export const listSubcommand = createSubcommand({
 				Name: w.name,
 				Scope: w.scope,
 				Repos: String(w.repoCount),
-				Skills: String(w.selectionCount),
+				Selections: String(w.selectionCount),
 				Created: formatRelativeTime(w.createdAt),
 			})),
 			[
@@ -91,7 +91,7 @@ export const listSubcommand = createSubcommand({
 				{ name: 'Name', alignment: 'left' },
 				{ name: 'Scope', alignment: 'center' },
 				{ name: 'Repos', alignment: 'right' },
-				{ name: 'Skills', alignment: 'right' },
+				{ name: 'Selections', alignment: 'right' },
 				{ name: 'Created', alignment: 'right' },
 			]
 		);

package/src/cmd/dev/dev-lock.ts

@@ -71,35 +71,69 @@ function pidExists(pid: number): boolean {
 }
 
 /**
- * Kill a process by PID with SIGTERM, then SIGKILL if still alive
+ * Send a signal to a process group (negative PID) with fallback to direct PID.
+ * Returns true if the signal was sent successfully.
  */
-async function killPid(pid: number, logger: LoggerLike): Promise<void> {
-	if (!pidExists(pid)) return;
+function killProcessTree(pid: number, signal: NodeJS.Signals, logger: LoggerLike): boolean {
+	// Safety: never send signals to PID 0 (own process group), PID 1 (init/systemd),
+	// or other dangerously low PIDs. process.kill(-1) would signal every process
+	// the user owns, which would crash the entire desktop session.
+	if (pid <= 1) {
+		logger.debug('Refusing to kill dangerous pid %d, skipping process tree kill', pid);
+		return false;
+	}
 
+	// Try process group kill first (kills all children too)
 	try {
-		process.kill(pid, 'SIGTERM');
-		logger.debug('Sent SIGTERM to pid %d', pid);
+		process.kill(-pid, signal);
+		logger.debug('Sent %s to process group -%d', signal, pid);
+		return true;
 	} catch (err: unknown) {
 		const error = err as NodeJS.ErrnoException;
-		if (error.code === 'ESRCH') return;
-		logger.debug('Error sending SIGTERM to pid %d: %s', pid, error.message);
+		if (error.code !== 'ESRCH') {
+			logger.debug(
+				'Process group kill failed for pid %d (%s), falling back to direct',
+				pid,
+				error.code
+			);
+		}
 	}
 
-	// Give it a moment to exit gracefully
-	await new Promise((r) => setTimeout(r, 500));
-
-	if (!pidExists(pid)) return;
-
-	// Force kill
+	// Fall back to direct PID kill
 	try {
-		process.kill(pid, 'SIGKILL');
-		logger.debug('Sent SIGKILL to pid %d', pid);
+		process.kill(pid, signal);
+		logger.debug('Sent %s to pid %d (direct)', signal, pid);
+		return true;
 	} catch (err: unknown) {
 		const error = err as NodeJS.ErrnoException;
 		if (error.code !== 'ESRCH') {
-			logger.debug('Error sending SIGKILL to pid %d: %s', pid, error.message);
+			logger.debug('Direct kill failed for pid %d: %s', pid, error.code);
 		}
+		return false;
 	}
+}
+
+/**
+ * Kill a process by PID with SIGTERM, then SIGKILL if still alive.
+ * Targets the entire process tree to prevent orphaned child processes.
+ */
+async function killPid(pid: number, logger: LoggerLike): Promise<void> {
+	if (!pidExists(pid)) return;
+
+	// Send SIGTERM to process tree
+	const sent = killProcessTree(pid, 'SIGTERM', logger);
+	if (!sent) return;
+
+	// Give it a moment to exit gracefully
+	await new Promise((r) => setTimeout(r, 500));
+
+	// Always attempt SIGKILL on the process tree even if the leader has exited.
+	// On Unix, process groups persist after the leader exits and signaling via
+	// negative PGID still reaches remaining members. killProcessTree() handles
+	// ESRCH gracefully if the group no longer exists.
+
+	// Force kill the entire process tree
+	killProcessTree(pid, 'SIGKILL', logger);
 
 	// Wait for process to fully terminate
 	await new Promise((r) => setTimeout(r, 100));