@saifymatteo/pi-extensions 0.1.4 → 0.1.6

package/packages/pi-bg-bash/src/lib/output.ts

@@ -0,0 +1,31 @@
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+import { stripVTControlCharacters } from "node:util";
+
+/** Logs are untrusted terminal input; keep text, never terminal control sequences. */
+export function cleanOutput(text: string): string {
+	return stripVTControlCharacters(text).replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "").replace(/\t/g, "    ");
+}
+
+export function oneLine(text: string): string {
+	return cleanOutput(text).replace(/\s+/g, " ").trim();
+}
+
+/** Read only a bounded suffix, including for a single enormous log line. */
+export function readTail(path: string, maxLines = 2000, maxBytes = 48 * 1024): string {
+	let fd: number | undefined;
+	try {
+		fd = openSync(path, "r");
+		const size = fstatSync(fd).size;
+		const start = Math.max(0, size - maxBytes);
+		const buffer = Buffer.alloc(Math.min(size, maxBytes));
+		const count = readSync(fd, buffer, 0, buffer.length, start);
+		const text = cleanOutput(buffer.subarray(0, count).toString("utf8"));
+		const lines = text.split("\n");
+		const cut = start > 0 || lines.length > maxLines;
+		return (cut ? "(earlier output omitted)\n" : "") + lines.slice(-maxLines).join("\n").trimEnd();
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "ENOENT" ? "(no output yet)" : "(output unavailable)";
+	} finally {
+		if (fd !== undefined) closeSync(fd);
+	}
+}

package/packages/pi-bg-bash/src/lib/panel.ts

@@ -0,0 +1,155 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { matchesKey, SelectList, Text, truncateToWidth } from "@earendil-works/pi-tui";
+import { oneLine } from "./output";
+import type { StopMode } from "./process-control";
+
+export interface JobView {
+	id: number;
+	command: string;
+	tool: string;
+	state: string;
+	secs: number;
+	running: boolean;
+	stoppable: boolean;
+}
+
+interface Controls {
+	list(): JobView[];
+	output(id: number): string;
+	stop(id: number, mode: StopMode): Promise<string>;
+}
+
+type Pick = { id: number; action: "view" | StopMode } | undefined;
+const label = (job: JobView) => `#${job.id} [${job.tool}] ${job.state} · ${job.secs}s · ${oneLine(job.command).slice(0, 200)}`;
+
+/** Human-only controls: inspecting output never claims or consumes agent results. */
+export async function showJobPanel(ctx: ExtensionCommandContext, controls: Controls, signal: AbortSignal): Promise<void> {
+	if (!controls.list().length) return ctx.ui.notify("No background jobs.", "info");
+	if (!ctx.hasUI) return ctx.ui.notify(controls.list().map(label).join("\n"), "info");
+	let selected: number | undefined;
+	while (!signal.aborted) {
+		let pick: Pick;
+		if (ctx.mode === "tui") {
+			pick = await ctx.ui.custom<Pick>((tui, theme, _keys, done) => {
+				let list: SelectList;
+				let visible: JobView[] = [];
+				let disposed = false;
+				const current = () => visible.find(job => String(job.id) === list?.getSelectedItem()?.value);
+				const rebuild = () => {
+					const keep = current()?.id ?? selected;
+					visible = controls.list();
+					list = new SelectList(visible.map(job => ({ value: String(job.id), label: label(job) })),
+						Math.max(1, Math.min(10, tui.terminal.rows - 6)), {
+							selectedPrefix: text => theme.fg("accent", text), selectedText: text => theme.fg("accent", text),
+							description: text => theme.fg("muted", text), scrollInfo: text => theme.fg("dim", text),
+							noMatch: text => theme.fg("dim", text),
+						});
+					list.setSelectedIndex(Math.max(0, visible.findIndex(job => job.id === keep)));
+					list.onSelect = () => { const job = current(); if (job) finish({ id: job.id, action: "view" }); };
+					list.onCancel = () => finish(undefined);
+				};
+				const dispose = () => {
+					if (disposed) return;
+					disposed = true;
+					clearInterval(timer);
+					signal.removeEventListener("abort", cancel);
+				};
+				const finish = (value: Pick) => { dispose(); done(value); };
+				const cancel = () => finish(undefined);
+				const timer = setInterval(() => { rebuild(); tui.requestRender(); }, 1000);
+				rebuild();
+				signal.addEventListener("abort", cancel, { once: true });
+				if (signal.aborted) queueMicrotask(cancel);
+				return {
+					dispose,
+					invalidate() { list.invalidate(); },
+					render(width: number) {
+						return [theme.fg("accent", "Background jobs"), ...list.render(width),
+							theme.fg("dim", "↑↓ select · Enter output · s stop gracefully · x force kill · Esc close")].map(line => truncateToWidth(line, width));
+					},
+					handleInput(data: string) {
+						if (matchesKey(data, "x") || matchesKey(data, "s")) {
+							const job = current();
+							if (job) finish({ id: job.id, action: matchesKey(data, "x") ? "force" : "graceful" });
+						} else if (matchesKey(data, "q")) finish(undefined);
+						else list.handleInput(data);
+						tui.requestRender();
+					},
+				};
+			});
+		} else {
+			const visible = controls.list();
+			const choices = visible.map(label);
+			const choice = await ctx.ui.select("Background jobs", choices, { signal });
+			const job = visible[choices.indexOf(choice ?? "")];
+			if (!job || signal.aborted) return;
+			const action = await ctx.ui.select(label(job), ["View output", "Stop gracefully", "Force kill", "Back"], { signal });
+			if (action === undefined) return;
+			if (action === "Back") continue;
+			pick = { id: job.id, action: action === "Stop gracefully" ? "graceful" : action === "Force kill" ? "force" : "view" };
+		}
+		if (!pick || signal.aborted) return;
+		selected = pick.id;
+		const job = controls.list().find(job => job.id === pick.id);
+		if (!job) continue;
+		if (pick.action !== "view") {
+			if (!job.stoppable) { ctx.ui.notify(`Job #${job.id} already finished.`, "info"); continue; }
+			const force = pick.action === "force";
+			if (!(await ctx.ui.confirm(`${force ? "Force kill" : "Gracefully stop"} background job #${job.id}?`,
+				`${oneLine(job.command).slice(0, 500)}\n` + (force ?
+					"Immediately terminates its tracked process tree. Cleanup hooks will not run." :
+					"Requests Ctrl+C shutdown. Survivors remain available for Force kill; no automatic escalation."), { signal })) || signal.aborted) continue;
+			ctx.ui.notify(`${force ? "Force killing" : "Gracefully stopping"} background job #${job.id}…`, "info");
+			try {
+				const message = await controls.stop(job.id, pick.action);
+				if (!signal.aborted) ctx.ui.notify(message, "info");
+			} catch (error) {
+				if (!signal.aborted) ctx.ui.notify(`Could not stop job #${job.id}: ${oneLine(String(error))}`, "error");
+			}
+		} else if (ctx.mode !== "tui") ctx.ui.notify(controls.output(job.id), "info");
+		else await ctx.ui.custom<void>((tui, theme, _keys, done) => {
+			let text = controls.output(job.id);
+			let top = Number.POSITIVE_INFINITY;
+			let rows: string[] = [];
+			let height = 1;
+			let disposed = false;
+			const dispose = () => {
+				if (disposed) return;
+				disposed = true;
+				clearInterval(timer);
+				signal.removeEventListener("abort", finish);
+			};
+			const finish = () => { dispose(); done(); };
+			const timer = setInterval(() => {
+				const following = top >= Math.max(0, rows.length - height);
+				text = controls.output(job.id);
+				if (following) top = Number.POSITIVE_INFINITY;
+				tui.requestRender();
+			}, 1000);
+			signal.addEventListener("abort", finish, { once: true });
+			if (signal.aborted) queueMicrotask(finish);
+			return {
+				dispose,
+				invalidate() {},
+				render(width: number) {
+					height = Math.max(1, tui.terminal.rows - 6);
+					rows = new Text(text || "(no output yet)", 0, 0).render(Math.max(1, width));
+					top = Math.max(0, Math.min(top, rows.length - height));
+					return [theme.fg("accent", label(controls.list().find(j => j.id === job.id) ?? job)),
+						...rows.slice(top, top + height),
+						theme.fg("dim", "↑↓ / PgUp / PgDn scroll · Home / End · Esc back")].map(line => truncateToWidth(line, width));
+				},
+				handleInput(data: string) {
+					if (matchesKey(data, "escape") || matchesKey(data, "q") || matchesKey(data, "enter")) finish();
+					else if (matchesKey(data, "up")) top = Math.max(0, top - 1);
+					else if (matchesKey(data, "down")) top = Math.min(Math.max(0, rows.length - height), top + 1);
+					else if (matchesKey(data, "pageUp")) top = Math.max(0, top - height);
+					else if (matchesKey(data, "pageDown")) top = Math.min(Math.max(0, rows.length - height), top + height);
+					else if (matchesKey(data, "home")) top = 0;
+					else if (matchesKey(data, "end")) top = Number.POSITIVE_INFINITY;
+					tui.requestRender();
+				},
+			};
+		});
+	}
+}

package/packages/pi-bg-bash/src/lib/process-control.ts

@@ -0,0 +1,221 @@
+import { execFile } from "node:child_process";
+import process from "node:process";
+import { windowsConsoleInterruptScript } from "./windows-console";
+
+export type StopMode = "graceful" | "force";
+
+export interface ProcessIdentity {
+	pid: number;
+	/** OS birth identifier, not a capture timestamp. Windows callers must supply a native PID. */
+	started: string;
+}
+
+interface ProcessRow extends ProcessIdentity {
+	ppid: number;
+	dead?: boolean;
+}
+
+const WINDOWS = process.platform === "win32";
+const GRACE_MS = 3_000;
+// Retain authenticated descendants after a partial failure so retry cannot forget
+// survivors just because their launcher exited during the previous stop.
+const pendingTrees = new WeakMap<ProcessIdentity, Map<number, ProcessRow>>();
+
+function validatePid(pid: number): void {
+	if (!Number.isSafeInteger(pid) || pid <= 1 || pid === process.pid) {
+		throw new Error(`Unsafe process PID: ${pid}`);
+	}
+}
+
+function validateIdentity(identity: ProcessIdentity): void {
+	validatePid(identity.pid);
+	if (typeof identity.started !== "string" || !identity.started || !Number.isFinite(Date.parse(identity.started))) {
+		throw new Error("Missing or invalid process birth identity");
+	}
+}
+
+function run(file: string, args: string[], signal?: AbortSignal): Promise<string> {
+	return new Promise((resolve, reject) => {
+		execFile(file, args, {
+			encoding: "utf8", windowsHide: true, timeout: 15_000, maxBuffer: 16 * 1024 * 1024, signal,
+			env: { ...process.env, LC_ALL: "C", TZ: "UTC" },
+		}, (error, stdout, stderr) => {
+			if (error) reject(error);
+			else if (stderr.trim()) reject(new Error(`Process command reported: ${stderr.trim()}`));
+			else resolve(stdout);
+		});
+	});
+}
+
+function powershell(script: string, signal?: AbortSignal): Promise<string> {
+	return run("powershell.exe", ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command",
+		`$ErrorActionPreference='Stop'; ${script}`], signal);
+}
+
+async function processTable(signal?: AbortSignal): Promise<Map<number, ProcessRow>> {
+	let rows: ProcessRow[];
+	if (WINDOWS) {
+		const output = await powershell(`$rows = @(Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,CreationDate -ErrorAction Stop | ForEach-Object {
+			@{pid=[int]$_.ProcessId; ppid=[int]$_.ParentProcessId;
+			started=$(if ($null -ne $_.CreationDate) {$_.CreationDate.ToUniversalTime().ToString('o')} else {''})}
+		}); ConvertTo-Json -Compress -InputObject $rows`, signal);
+		const parsed: unknown = JSON.parse(output);
+		if (!Array.isArray(parsed)) throw new Error("Invalid CIM process table");
+		rows = parsed;
+	} else {
+		const output = await run("ps", ["-A", "-o", "pid=", "-o", "ppid=", "-o", "lstart=", "-o", "stat="], signal);
+		rows = output.split(/\r?\n/).filter(line => line.trim()).map(line => {
+			const match = /^\s*(\d+)\s+(\d+)\s+([A-Za-z]{3}\s+[A-Za-z]{3}\s+\d{1,2}\s+\d{2}:\d{2}:\d{2}\s+\d{4})\s+(\S+)\s*$/.exec(line);
+			if (!match) throw new Error("Invalid ps process table row");
+			return { pid: Number(match[1]), ppid: Number(match[2]), started: match[3].replace(/\s+/g, " ") + " UTC",
+				dead: /^[ZX]/.test(match[4]) };
+		});
+	}
+	const table = new Map<number, ProcessRow>();
+	for (const row of rows) {
+		if (!row || !Number.isSafeInteger(row.pid) || row.pid < 0 || !Number.isSafeInteger(row.ppid) || row.ppid < 0 ||
+			typeof row.started !== "string" || (row.started && !Number.isFinite(Date.parse(row.started))) || table.has(row.pid)) {
+			throw new Error("Invalid process table");
+		}
+		table.set(row.pid, row);
+	}
+	// A successful but empty/filtered listing cannot establish absence safely.
+	if (!table.has(process.pid)) throw new Error("Incomplete process table (self missing)");
+	return table;
+}
+
+function matching(table: Map<number, ProcessRow>, identity: ProcessIdentity): ProcessRow | undefined {
+	const row = table.get(identity.pid);
+	return row?.started === identity.started && !row.dead ? row : undefined;
+}
+
+/** Snapshot descendants only through verified, live ancestors. Never follow a reused parent PID. */
+function descendants(table: Map<number, ProcessRow>, roots: ProcessIdentity[]): ProcessRow[] {
+	const found = new Map<number, ProcessRow>();
+	const queue = roots.map(root => matching(table, root)).filter((row): row is ProcessRow => !!row);
+	for (const root of queue) found.set(root.pid, root);
+	for (let i = 0; i < queue.length; i++) {
+		const parent = queue[i];
+		for (const child of table.values()) {
+			if (child.ppid !== parent.pid || child.pid === parent.pid || child.dead) continue;
+			validateIdentity(child);
+			// Windows retains the numeric parent PID after exit; it may now belong to a newer process.
+			if (Date.parse(child.started) < Date.parse(parent.started)) continue;
+			if (!found.has(child.pid)) {
+				found.set(child.pid, child);
+				queue.push(child);
+			}
+		}
+	}
+	return [...found.values()];
+}
+
+/** An exited/reused parent cannot authenticate newly observed children. Do not adopt them. */
+function uncertainChildren(table: Map<number, ProcessRow>, targets: Map<number, ProcessRow>): boolean {
+	return [...table.values()].some(row => {
+		const parent = targets.get(row.ppid);
+		return parent && !row.dead && !matching(table, parent) &&
+			targets.get(row.pid)?.started !== row.started &&
+			(!row.started || Date.parse(row.started) >= Date.parse(parent.started));
+	});
+}
+
+/** Snapshot ownership evidence only; this cheap query does not establish liveness. */
+export function hasTrackedDescendants(identity: ProcessIdentity): boolean {
+	return (pendingTrees.get(identity)?.size ?? 0) > 1;
+}
+
+/** Capture a real OS PID and known descendants. Does not translate MSYS PIDs. */
+export async function captureProcess(pid: number, signal?: AbortSignal): Promise<ProcessIdentity> {
+	validatePid(pid);
+	const table = await processTable(signal);
+	const row = table.get(pid);
+	if (!row || row.dead) throw new Error(`Process ${pid} is gone`);
+	validateIdentity(row);
+	const identity = { pid: row.pid, started: row.started };
+	// Remember already-owned descendants at launch, not only at the first stop.
+	// A launcher exiting later must not make these children undiscoverable.
+	pendingTrees.set(identity, new Map(descendants(table, [identity]).map(child => [child.pid, child])));
+	return identity;
+}
+
+function windowsKillScript(identity: ProcessIdentity): string {
+	// CIM records microseconds; .NET also exposes a seventh, 100ns digit.
+	const birth = identity.started.replace(/(\.\d{6})\dZ$/, "$1Z").replace(/'/g, "''");
+	return `$p = $null;
+		try { $p = [System.Diagnostics.Process]::GetProcessById(${identity.pid}) }
+		catch {
+			if ($_.Exception -isnot [System.ArgumentException] -and
+				$_.Exception.InnerException -isnot [System.ArgumentException]) { throw }
+		}
+		if ($null -ne $p) {
+			try {
+				# Cache the OS handle before checking birth; act on that same process object.
+				$null = $p.Handle;
+				if (($p.StartTime.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ss.ffffff') + 'Z') -ceq '${birth}') {
+					$p.Kill()
+				}
+			} finally { $p.Dispose() }
+		}`;
+}
+
+async function signalAll(targets: ProcessIdentity[], mode: StopMode): Promise<void> {
+	for (const identity of targets) validateIdentity(identity);
+	if (WINDOWS) {
+		// One interpreter, not one per descendant. Every kill validates the birth
+		// identity against an open OS handle; console interruption is separate.
+		if (targets.length) await powershell(targets.map(windowsKillScript).join("\n"));
+		return;
+	}
+	for (const identity of targets) {
+		// ps + kill is not atomic; keep the check immediately adjacent to each signal.
+		if (!matching(await processTable(), identity)) continue;
+		try { process.kill(identity.pid, mode === "force" ? "SIGKILL" : "SIGINT"); }
+		catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error; }
+	}
+}
+
+/**
+ * Stop the snapshotted tree without automatic escalation. Graceful means SIGINT
+ * on Unix or a safely isolated console Ctrl+C on Windows; force skips grace.
+ * 'gone' means the root was already absent/reused before
+ * any action; 'stopped' means all tracked identities are gone; 'stuck' means a
+ * survivor or newly observed descendant remains. Enumeration/permission errors
+ * reject, never masquerade as absence. No names, ports, groups, or PID 0 used.
+ *
+ * This is best-effort process control, not containment: children that fork and
+ * reparent between snapshots cannot be recovered safely. Unix ps birth times
+ * have one-second precision, and portable PID signaling has an unavoidable
+ * check/signal race. Stronger guarantees require OS job objects/pidfds.
+ */
+export async function stopProcessTree(identity: ProcessIdentity, mode: StopMode = "force"): Promise<"stopped" | "gone" | "stuck"> {
+	validateIdentity(identity);
+	if (mode !== "graceful" && mode !== "force") throw new Error("Invalid process stop mode");
+	let table = await processTable();
+	const previous = pendingTrees.get(identity);
+	if (!matching(table, identity) && !previous) return "gone";
+	const targets = previous ?? new Map<number, ProcessRow>();
+	for (const row of descendants(table, [identity, ...targets.values()])) targets.set(row.pid, row);
+	// Validate the entire snapshot before taking any destructive action.
+	for (const target of targets.values()) validateIdentity(target);
+	pendingTrees.set(identity, targets);
+	const live = [...targets.values()].filter(target => matching(table, target));
+	if (!live.length && !uncertainChildren(table, targets)) {
+		pendingTrees.delete(identity);
+		return "gone";
+	}
+	if (WINDOWS && mode === "graceful") {
+		// A console event reaches its console, not a PID. The helper authenticates
+		// every attached process and rejects shared/unknown consoles before sending.
+		if (live.length) await powershell(windowsConsoleInterruptScript(live[0], live, process.pid));
+	} else await signalAll(live.reverse(), mode);
+	// Graceful stopping never kills survivors. Force only waits for OS retirement.
+	await new Promise(resolve => setTimeout(resolve, mode === "graceful" ? GRACE_MS : 100));
+	table = await processTable();
+	const uncertain = uncertainChildren(table, targets);
+	const survivors = descendants(table, [...targets.values()]);
+	for (const child of survivors) targets.set(child.pid, child);
+	if (uncertain || survivors.length) return "stuck";
+	pendingTrees.delete(identity);
+	return "stopped";
+}

package/packages/pi-bg-bash/src/lib/windows-console.ts

@@ -0,0 +1,169 @@
+import type { ProcessIdentity } from "./process-control";
+
+/** Run only inside the new job console, before launching its actual command. */
+export const windowsConsoleInputPrelude = `
+$ErrorActionPreference = 'Stop'
+Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+public static class PiBgConsoleInput {
+    [DllImport("kernel32.dll", SetLastError = true)]
+    [return: MarshalAs(UnmanagedType.Bool)] public static extern bool SetConsoleCtrlHandler(IntPtr handler, bool add);
+    [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+    public static extern IntPtr CreateFile(string name, uint access, uint share, IntPtr attrs, uint disposition, uint flags, IntPtr template);
+    [DllImport("kernel32.dll", SetLastError = true)]
+    [return: MarshalAs(UnmanagedType.Bool)] public static extern bool SetHandleInformation(IntPtr handle, uint mask, uint flags);
+    [DllImport("kernel32.dll", SetLastError = true)]
+    [return: MarshalAs(UnmanagedType.Bool)] public static extern bool SetStdHandle(int id, IntPtr handle);
+    [DllImport("kernel32.dll", SetLastError = true)]
+    [return: MarshalAs(UnmanagedType.Bool)] public static extern bool CloseHandle(IntPtr handle);
+    [DllImport("kernel32.dll", SetLastError = true)]
+    public static extern uint GetConsoleProcessList([Out] uint[] list, uint size);
+}
+'@
+# Detached launches can inherit an ignore-Ctrl+C attribute. Clear it in the job
+# console BEFORE children start; registering a Node SIGINT listener alone cannot.
+if (-not [PiBgConsoleInput]::SetConsoleCtrlHandler([IntPtr]::Zero, $false)) {
+    throw ('Cannot enable console Ctrl+C (Win32 ' + [Runtime.InteropServices.Marshal]::GetLastWin32Error() + ')')
+}
+`;
+
+/** Bash needs inheritable CONIN$, not PowerShell's native-command stdin pipe. */
+export function windowsBashLaunchScript(commandPath: string): string {
+	return windowsConsoleInputPrelude + `
+$clients = New-Object System.UInt32[] 2
+$count = [PiBgConsoleInput]::GetConsoleProcessList($clients, $clients.Length)
+if ($count -ne 1 -or $clients[0] -ne $PID) { throw 'Job console is not isolated; refusing to attach input' }
+$inputHandle = [PiBgConsoleInput]::CreateFile('CONIN$', [uint32]3221225472, 3, [IntPtr]::Zero, 3, 0, [IntPtr]::Zero)
+if ($inputHandle -eq [IntPtr](-1)) { throw 'Cannot open job console input' }
+try {
+    if (-not [PiBgConsoleInput]::SetHandleInformation($inputHandle, 1, 1)) { throw 'Cannot inherit job console input' }
+    if (-not [PiBgConsoleInput]::SetStdHandle(-10, $inputHandle)) { throw 'Cannot set job console input' }
+    $start = New-Object System.Diagnostics.ProcessStartInfo
+    $start.FileName = $env:PI_BG_BASH_EXECUTABLE
+    $start.Arguments = '-- "${commandPath.replace(/'/g, "''")}"'
+    $start.UseShellExecute = $false
+    # Avoid PowerShell's native-command pipeline, which replaces stdin with a
+    # pipe and makes MSYS suppress native children's Ctrl+C handlers again.
+    $child = [System.Diagnostics.Process]::Start($start)
+    try { $child.WaitForExit(); $code = $child.ExitCode }
+    finally { $child.Dispose() }
+    exit $code
+} finally { [void][PiBgConsoleInput]::CloseHandle($inputHandle) }
+`;
+}
+
+/**
+ * Run in a disposable powershell.exe, never in Pi's own console host.
+ * Console enumeration/broadcast is not atomic: this is not hostile-process containment.
+ */
+export function windowsConsoleInterruptScript(root: ProcessIdentity, targets: ProcessIdentity[], ownerPid: number): string {
+	// Callers validate the tree; also keep this serialization boundary non-executable.
+	const validPid = (pid: number) => Number.isSafeInteger(pid) && pid > 1 && pid <= 0xffffffff;
+	if (!validPid(ownerPid)) throw new Error("Unsafe console owner PID");
+	const known = new Map<number, string>();
+	for (const identity of [root, ...targets]) {
+		if (!validPid(identity.pid) || identity.pid === ownerPid ||
+			!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}0Z$/.test(identity.started) ||
+			!Number.isFinite(Date.parse(identity.started))) {
+			throw new Error("Invalid Windows console process identity");
+		}
+		const birth = identity.started.replace(/0Z$/, "Z");
+		if (known.has(identity.pid) && known.get(identity.pid) !== birth) throw new Error("Conflicting console process identities");
+		known.set(identity.pid, birth);
+	}
+	return `$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+public static class PiBgConsole {
+    [DllImport("kernel32.dll", SetLastError = true)]
+    [return: MarshalAs(UnmanagedType.Bool)] public static extern bool FreeConsole();
+    [DllImport("kernel32.dll", SetLastError = true)]
+    [return: MarshalAs(UnmanagedType.Bool)] public static extern bool AttachConsole(uint pid);
+    [DllImport("kernel32.dll", SetLastError = true)]
+    [return: MarshalAs(UnmanagedType.Bool)] public static extern bool SetConsoleCtrlHandler(IntPtr handler, bool add);
+    [DllImport("kernel32.dll", SetLastError = true)]
+    public static extern uint GetConsoleProcessList([Out] uint[] list, uint size);
+    [DllImport("kernel32.dll", SetLastError = true)]
+    [return: MarshalAs(UnmanagedType.Bool)] public static extern bool GenerateConsoleCtrlEvent(uint controlEvent, uint group);
+}
+'@
+$known = @{ ${[...known].map(([pid, birth]) => `${pid} = '${birth}'`).join("; ")} }
+$handles = @{}
+$attached = $false
+function Console-Error([string] $operation) {
+    throw ($operation + ' failed (Win32 ' + [Runtime.InteropServices.Marshal]::GetLastWin32Error() + ')')
+}
+function Get-ConsoleMembers {
+    $capacity = 16
+    for ($attempt = 0; $attempt -lt 4; $attempt++) {
+        $members = New-Object System.UInt32[] $capacity
+        $count = [PiBgConsole]::GetConsoleProcessList($members, $members.Length)
+        if ($count -eq 0) { Console-Error 'GetConsoleProcessList' }
+        if ($count -gt 65536) { throw 'Console membership exceeds safety bound' }
+        if ($count -le $members.Length) {
+            $result = @($members[0..([int]$count - 1)])
+            if (@($result | Select-Object -Unique).Count -ne $result.Count) { throw 'Invalid console membership' }
+            return $result
+        }
+        $capacity = [int]$count
+    }
+    throw 'Console membership did not stabilize'
+}
+function Assert-Identity([int] $targetPid) {
+    if (-not $known.ContainsKey($targetPid)) { throw ('Unauthenticated console process ' + $targetPid) }
+    if (-not $handles.ContainsKey($targetPid)) {
+        $p = [System.Diagnostics.Process]::GetProcessById($targetPid)
+        # Store before accessing Handle so finally also disposes partial failures.
+        $handles[$targetPid] = $p
+        $null = $p.Handle
+    }
+    $p = $handles[$targetPid]
+    $p.Refresh()
+    if ($p.HasExited -or ($p.StartTime.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ss.ffffff', [Globalization.CultureInfo]::InvariantCulture) + 'Z') -cne $known[$targetPid]) {
+        throw ('Process birth identity changed or process exited: ' + $targetPid)
+    }
+}
+function Assert-Members($members) {
+    if ($members -contains ${ownerPid}) { throw 'Console contains Pi owner process' }
+    if ($members -notcontains ${root.pid}) { throw 'Root absent from console' }
+    if ($members -notcontains $PID) { throw 'Helper absent from attached console' }
+    foreach ($member in $members) {
+        if ($member -ne $PID) { Assert-Identity ([int]$member) }
+    }
+}
+try {
+    if ($known.ContainsKey([int]$PID)) { throw 'Helper PID conflicts with target' }
+    Assert-Identity ${root.pid}
+    foreach ($targetPid in @($known.Keys)) { Assert-Identity $targetPid }
+    if (-not [PiBgConsole]::FreeConsole()) {
+        # A pipe-only helper may start without any console.
+        if ([Runtime.InteropServices.Marshal]::GetLastWin32Error() -ne 6) { Console-Error 'FreeConsole' }
+    }
+    if (-not [PiBgConsole]::AttachConsole(${root.pid})) { Console-Error 'AttachConsole (root has no usable console)' }
+    $attached = $true
+    # AttachConsole resets the handler table: ignore Ctrl+C only AFTER attachment.
+    if (-not [PiBgConsole]::SetConsoleCtrlHandler([IntPtr]::Zero, $true)) { Console-Error 'SetConsoleCtrlHandler' }
+    $members = @(Get-ConsoleMembers)
+    Assert-Members $members
+    $again = @(Get-ConsoleMembers)
+    Assert-Members $again
+    if ((($members | Sort-Object) -join ',') -cne (($again | Sort-Object) -join ',')) { throw 'Console membership changed during validation' }
+    # Cached OS handles pin the authenticated process objects. Check births/liveness
+    # again, then take the final membership snapshot immediately before broadcast.
+    foreach ($targetPid in @($handles.Keys)) { Assert-Identity $targetPid }
+    $last = @(Get-ConsoleMembers)
+    if ((($again | Sort-Object) -join ',') -cne (($last | Sort-Object) -join ',')) { throw 'Console membership changed before Ctrl+C' }
+    if (-not [PiBgConsole]::GenerateConsoleCtrlEvent(0, 0)) { Console-Error 'GenerateConsoleCtrlEvent' }
+    # Delivery is asynchronous; do not tear down the sender immediately.
+    Start-Sleep -Milliseconds 250
+} catch {
+    throw ('Graceful stop unsupported/error: ' + $_.Exception.Message)
+} finally {
+    if ($attached) { $null = [PiBgConsole]::FreeConsole() }
+    foreach ($p in $handles.Values) { $p.Dispose() }
+}
+`;
+}