@aefree/pi-plastic 0.7.6 → 0.8.1

package/src/execution/cli-version.ts

@@ -0,0 +1,31 @@
+import { runCmRaw, normalizeFindOutputLines } from "./cm";
+
+let cachedCmVersion: string | null = null;
+let cmVersionPromise: Promise<string> | null = null;
+
+export const getCmVersion = async (workdir?: string): Promise<string> =>
+{
+    if (cachedCmVersion)
+    {
+        return cachedCmVersion;
+    }
+
+    if (!cmVersionPromise)
+    {
+        cmVersionPromise = runCmRaw(["version"], workdir)
+            .then((value) =>
+            {
+                const parsed = normalizeFindOutputLines(value)[0] ?? "unknown";
+                cachedCmVersion = parsed;
+                cmVersionPromise = null;
+                return parsed;
+            })
+            .catch(() =>
+            {
+                cmVersionPromise = null;
+                return "unknown";
+            });
+    }
+
+    return cmVersionPromise;
+};

package/src/execution/cm.ts

@@ -0,0 +1,59 @@
+import { getActiveAbortSignal, commandExecutionStorage } from "./context";
+import { getCmExecutable, spawnAndCollect } from "./process";
+
+export const BLOCKED_CM_DIFF_MESSAGE = "`cm diff` is blocked in Pi because it may launch GUI windows and hang the CLI. Use `plastic_status` when only changed paths are needed. Do not diff routinely; when change-boundary evidence is necessary, use `plastic_diff` with explicit mode=file, revisions, or workspace and bounded scope.";
+
+export const ensureCmCommandAllowed = (args: string[]): void =>
+{
+    const command = (args[0] ?? "").trim().toLowerCase();
+    if (command === "diff" || command === "differences")
+    {
+        throw new Error(BLOCKED_CM_DIFF_MESSAGE);
+    }
+};
+
+export const runCm = async (args: string[], workdir?: string, input?: string, signal: AbortSignal | undefined = getActiveAbortSignal()): Promise<string> =>
+{
+    ensureCmCommandAllowed(args);
+    const cwd = workdir ?? process.cwd();
+    const { stdout, stderr, exitCode, aborted } = await spawnAndCollect(getCmExecutable(), args, cwd, input, signal, commandExecutionStorage.getStore());
+    const output = [stdout, stderr].filter(Boolean).join("\n").trim();
+
+    if (aborted)
+    {
+        throw new Error(output.length > 0 ? `cm ${args.join(" ")} aborted.\n\n${output}` : `cm ${args.join(" ")} aborted.`);
+    }
+
+    if (exitCode !== 0)
+    {
+        throw new Error(output.length > 0 ? output : `cm ${args.join(" ")} failed with exit code ${exitCode}`);
+    }
+
+    return output.length > 0 ? output : "(no output)";
+};
+
+export const runCmRaw = async (args: string[], workdir?: string, input?: string, signal: AbortSignal | undefined = getActiveAbortSignal()): Promise<string> =>
+{
+    ensureCmCommandAllowed(args);
+    const cwd = workdir ?? process.cwd();
+    const { stdout, stderr, exitCode, aborted } = await spawnAndCollect(getCmExecutable(), args, cwd, input, signal, commandExecutionStorage.getStore());
+
+    if (aborted)
+    {
+        const output = [stdout, stderr].filter(Boolean).join("\n").trim();
+        throw new Error(output.length > 0 ? `cm ${args.join(" ")} aborted.\n\n${output}` : `cm ${args.join(" ")} aborted.`);
+    }
+
+    if (exitCode !== 0)
+    {
+        const output = [stdout, stderr].filter(Boolean).join("\n").trim();
+        throw new Error(output.length > 0 ? output : `cm ${args.join(" ")} failed with exit code ${exitCode}`);
+    }
+
+    return stdout ?? "";
+};
+
+export const normalizeFindOutputLines = (output: string): string[] => output
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && line !== "(no output)");

package/src/execution/code-review-find-command.ts

@@ -0,0 +1,75 @@
+import { spawn } from "node:child_process";
+import type { Readable } from "node:stream";
+export const CODE_REVIEW_FIND_CAPTURE_LIMITS = { stdoutBytes: 1048576, stderrBytes: 65536, timeoutMs: 30000, records: 20000 } as const;
+import { commandExecutionStorage, getActiveAbortSignal } from "./context";
+import { getCmExecutable } from "./process";
+export class CodeReviewFindCommandError extends Error {
+    constructor(readonly code: "command_failed" | "aborted" | "capture_incomplete") { super(`Code review find read failed (${code}).`); }
+}
+
+// Code-review-find-only strict byte transport. Native/default and other read routes are unchanged.
+export async function runCodeReviewFindIdsCommand(args: string[], workdir?: string): Promise<Buffer> {
+    const signal = getActiveAbortSignal();
+    if (signal?.aborted) throw new CodeReviewFindCommandError("aborted");
+    const dependencies = commandExecutionStorage.getStore() ?? {};
+    let child;
+    try { child = (dependencies.spawn ?? spawn)(getCmExecutable(), args, { cwd: workdir ?? process.cwd(), shell: false, stdio: ["ignore", "pipe", "pipe"] }); }
+    catch { throw new CodeReviewFindCommandError("command_failed"); }
+    const schedule = dependencies.setTimeout ?? setTimeout;
+    const cancel = dependencies.clearTimeout ?? clearTimeout;
+    let aborted = false, incomplete = false, failed = false, settled = false;
+    let killTimer: NodeJS.Timeout | undefined;
+    const terminate = () => {
+        if (settled) return;
+        try { child.kill("SIGTERM"); } catch { /* process may already have exited */ }
+        if (killTimer === undefined) killTimer = schedule(() => { if (!settled) { try { child.kill("SIGKILL"); } catch { /* process may already have exited */ } } }, dependencies.abortKillDelayMs ?? 5000);
+    };
+    const collectors: Array<{ dispose(): void }> = [];
+    const collect = (stream: Readable | null, cap: number) => {
+        let length = 0;
+        const chunks: Buffer[] = [];
+        if (!stream) { failed = true; return Promise.resolve(Buffer.alloc(0)); }
+        if (stream.readableEncoding) { failed = true; terminate(); }
+        return new Promise<Buffer>(resolve => {
+            let done = false;
+            const finish = () => { if (!done) { done = true; resolve(Buffer.concat(chunks, length)); } };
+            const data = (chunk: unknown) => {
+                // Already-decoded streams cannot attest exact source bytes.
+                if (!(chunk instanceof Uint8Array)) { failed = true; terminate(); return; }
+                const available = cap - length;
+                if (chunk.byteLength > available) { incomplete = true; terminate(); }
+                if (available > 0) { const part = Buffer.from(chunk.subarray(0, available)); chunks.push(part); length += part.length; }
+                // Keep draining beyond the cap until process/streams settle.
+            };
+            const error = () => { failed = true; terminate(); finish(); };
+            const closed = () => { if (!done && !stream.readableEnded) failed = true; finish(); };
+            stream.on("data", data); stream.once("end", finish); stream.once("error", error); stream.once("close", closed);
+            collectors.push({ dispose: () => { stream.removeListener("data", data); stream.removeListener("end", finish); stream.removeListener("error", error); stream.removeListener("close", closed); } });
+        });
+    };
+    let onClose: (code: number | null) => void;
+    let onError: () => void;
+    const exit = new Promise<number>(resolve => {
+        onClose = code => { settled = true; resolve(code ?? 1); };
+        onError = () => { failed = true; settled = true; child.stdout?.destroy(); child.stderr?.destroy(); resolve(1); };
+        child.once("close", onClose); child.once("error", onError);
+    });
+    const stdout = collect(child.stdout, CODE_REVIEW_FIND_CAPTURE_LIMITS.stdoutBytes);
+    const stderr = collect(child.stderr, CODE_REVIEW_FIND_CAPTURE_LIMITS.stderrBytes);
+    const onAbort = () => { aborted = true; terminate(); };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const timeout = schedule(() => { incomplete = true; terminate(); }, Math.min(dependencies.timeoutMs ?? CODE_REVIEW_FIND_CAPTURE_LIMITS.timeoutMs, CODE_REVIEW_FIND_CAPTURE_LIMITS.timeoutMs));
+    if (signal?.aborted) onAbort();
+    try {
+        const [code, bytes, errors] = await Promise.all([exit, stdout, stderr]);
+        if (aborted || signal?.aborted) throw new CodeReviewFindCommandError("aborted");
+        if (incomplete) throw new CodeReviewFindCommandError("capture_incomplete");
+        if (failed || code !== 0 || errors.length) throw new CodeReviewFindCommandError("command_failed");
+        return bytes;
+    } finally {
+        cancel(timeout); if (killTimer !== undefined) cancel(killTimer);
+        signal?.removeEventListener("abort", onAbort);
+        child.removeListener("close", onClose!); child.removeListener("error", onError!);
+        for (const collector of collectors) collector.dispose();
+    }
+}

package/src/execution/context.ts

@@ -0,0 +1,20 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { SpawnAndCollectDependencies } from "./process";
+
+const abortSignalStorage = new AsyncLocalStorage<AbortSignal | undefined>();
+export const commandExecutionStorage = new AsyncLocalStorage<SpawnAndCollectDependencies | undefined>();
+
+export const getActiveAbortSignal = (): AbortSignal | undefined => abortSignalStorage.getStore();
+
+export const runWithAbortSignal = async <T>(
+    signal: AbortSignal | undefined,
+    fn: () => Promise<T>,
+    commandExecution?: SpawnAndCollectDependencies,
+): Promise<T> =>
+{
+    const inheritedSignal = getActiveAbortSignal();
+    const inheritedExecution = commandExecutionStorage.getStore();
+    // Nested public-tool execution must retain an injected process seam and the
+    // outer abort signal instead of silently dropping either boundary.
+    return abortSignalStorage.run(signal ?? inheritedSignal, () => commandExecutionStorage.run(commandExecution ?? inheritedExecution, fn));
+};

package/src/execution/diff-revisions-command.ts

@@ -0,0 +1,74 @@
+import { spawn } from "node:child_process";
+import type { Readable } from "node:stream";
+export const DIFF_REVISIONS_CAPTURE_LIMITS = { stdoutBytes: 1048576, stderrBytes: 65536, timeoutMs: 30000 } as const;
+import { commandExecutionStorage, getActiveAbortSignal } from "./context";
+export class DiffRevisionsCommandError extends Error {
+    constructor(readonly code: "command_failed" | "aborted" | "capture_incomplete") { super(`Revision comparison read failed (${code}).`); }
+}
+
+// Revision-comparison-only strict byte transport. Native/default and other read routes are unchanged.
+export async function runDiffRevisionsCommand(executable: string, args: string[], cwd: string, allowedExitCodes: readonly number[]): Promise<{ stdout: Buffer; exitCode: number }> {
+    const signal = getActiveAbortSignal();
+    if (signal?.aborted) throw new DiffRevisionsCommandError("aborted");
+    const dependencies = commandExecutionStorage.getStore() ?? {};
+    let child;
+    try { child = (dependencies.spawn ?? spawn)(executable, args, { cwd, shell: false, stdio: ["ignore", "pipe", "pipe"] }); }
+    catch { throw new DiffRevisionsCommandError("command_failed"); }
+    const schedule = dependencies.setTimeout ?? setTimeout;
+    const cancel = dependencies.clearTimeout ?? clearTimeout;
+    let aborted = false, incomplete = false, failed = false, settled = false;
+    let killTimer: NodeJS.Timeout | undefined;
+    const terminate = () => {
+        if (settled) return;
+        try { child.kill("SIGTERM"); } catch { /* process may already have exited */ }
+        if (killTimer === undefined) killTimer = schedule(() => { if (!settled) { try { child.kill("SIGKILL"); } catch { /* process may already have exited */ } } }, dependencies.abortKillDelayMs ?? 5000);
+    };
+    const collectors: Array<{ dispose(): void }> = [];
+    const collect = (stream: Readable | null, cap: number) => {
+        let length = 0;
+        const chunks: Buffer[] = [];
+        if (!stream) { failed = true; terminate(); return Promise.resolve(Buffer.alloc(0)); }
+        if (stream.readableEncoding) { failed = true; terminate(); }
+        return new Promise<Buffer>(resolve => {
+            let done = false;
+            const finish = () => { if (!done) { done = true; resolve(Buffer.concat(chunks, length)); } };
+            const data = (chunk: unknown) => {
+                // Already-decoded streams cannot attest exact source bytes.
+                if (!(chunk instanceof Uint8Array)) { failed = true; terminate(); return; }
+                const available = cap - length;
+                if (chunk.byteLength > available) { incomplete = true; terminate(); }
+                if (available > 0) { const part = Buffer.from(chunk.subarray(0, available)); chunks.push(part); length += part.length; }
+                // Keep draining beyond the cap until process/streams settle.
+            };
+            const error = () => { failed = true; terminate(); finish(); };
+            const closed = () => { if (!done && !stream.readableEnded) failed = true; finish(); };
+            stream.on("data", data); stream.once("end", finish); stream.once("error", error); stream.once("close", closed);
+            collectors.push({ dispose: () => { stream.removeListener("data", data); stream.removeListener("end", finish); stream.removeListener("error", error); stream.removeListener("close", closed); } });
+        });
+    };
+    let onClose: (code: number | null, signal?: string | null) => void;
+    let onError: () => void;
+    const exit = new Promise<number>(resolve => {
+        onClose = (code, signal) => { settled = true; if (code === null || signal) failed = true; resolve(code ?? -1); };
+        onError = () => { failed = true; settled = true; child.stdout?.destroy(); child.stderr?.destroy(); resolve(1); };
+        child.once("close", onClose); child.once("error", onError);
+    });
+    const stdout = collect(child.stdout, DIFF_REVISIONS_CAPTURE_LIMITS.stdoutBytes);
+    const stderr = collect(child.stderr, DIFF_REVISIONS_CAPTURE_LIMITS.stderrBytes);
+    const onAbort = () => { aborted = true; terminate(); };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const timeout = schedule(() => { incomplete = true; terminate(); }, Math.min(dependencies.timeoutMs ?? DIFF_REVISIONS_CAPTURE_LIMITS.timeoutMs, DIFF_REVISIONS_CAPTURE_LIMITS.timeoutMs));
+    if (signal?.aborted) onAbort();
+    try {
+        const [code, bytes, errors] = await Promise.all([exit, stdout, stderr]);
+        if (aborted || signal?.aborted) throw new DiffRevisionsCommandError("aborted");
+        if (incomplete) throw new DiffRevisionsCommandError("capture_incomplete");
+        if (failed || !allowedExitCodes.includes(code) || errors.length) throw new DiffRevisionsCommandError("command_failed");
+        return { stdout: bytes, exitCode: code };
+    } finally {
+        cancel(timeout); if (killTimer !== undefined) cancel(killTimer);
+        signal?.removeEventListener("abort", onAbort);
+        child.removeListener("close", onClose!); child.removeListener("error", onError!);
+        for (const collector of collectors) collector.dispose();
+    }
+}

package/src/execution/process.ts

@@ -0,0 +1,260 @@
+import { spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
+
+export type SpawnResult = {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    aborted: boolean;
+    timedOut?: boolean;
+    stdoutTruncated?: boolean;
+    stdoutTotalChars?: number;
+    stderrTruncated?: boolean;
+    stderrTotalChars?: number;
+};
+
+export type ExecutableEnvironment = Record<string, string | undefined>;
+
+export const resolveExecutable = (environment: ExecutableEnvironment, overrideVariable: string, fallback: string): string =>
+{
+    const override = environment[overrideVariable]?.trim();
+    return override || fallback;
+};
+
+export const getCmExecutable = (): string => resolveExecutable(process.env, "PI_PLASTIC_CM_EXECUTABLE", "cm");
+// `diff -u` has compatible exit semantics on Windows GNU diff and macOS BSD diff.
+// Keep the executable name configurable rather than assuming a .exe suffix or package-manager path.
+export const getDiffExecutable = (): string => resolveExecutable(process.env, "PI_PLASTIC_DIFF_EXECUTABLE", "diff");
+export const executableNotFoundError = (command: string, error: Error): Error =>
+{
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT")
+    {
+        return error;
+    }
+
+    if (command === getCmExecutable())
+    {
+        return new Error(`Unable to launch Plastic SCM executable '${command}' (ENOENT). Set PI_PLASTIC_CM_EXECUTABLE to the full path to cm, or add cm to PATH.`);
+    }
+
+    if (command === getDiffExecutable())
+    {
+        return new Error(`Unable to launch GNU/POSIX text diff executable '${command}' (ENOENT). Set PI_PLASTIC_DIFF_EXECUTABLE to the full path of GNU/POSIX diff (paths containing spaces are supported), or install bare diff on PATH. Pi does not discover Git Bash paths automatically.`);
+    }
+
+    return new Error(`Unable to launch executable '${command}' (ENOENT). Verify that it is installed and available on PATH.`);
+};
+
+export const writeInput = async (stdin: NodeJS.WritableStream | null | undefined, input: string): Promise<void> =>
+{
+    if (!stdin)
+    {
+        return;
+    }
+
+    await new Promise<void>((resolvePromise, rejectPromise) =>
+    {
+        stdin.write(`${input}\n`, (error) =>
+        {
+            if (error)
+            {
+                rejectPromise(error);
+                return;
+            }
+
+            stdin.end();
+            resolvePromise();
+        });
+    });
+};
+
+export const readStream = async (stream: NodeJS.ReadableStream | null | undefined, maxChars?: number): Promise<{ output: string; truncated: boolean; totalChars: number }> =>
+{
+    if (!stream)
+    {
+        return { output: "", truncated: false, totalChars: 0 };
+    }
+
+    let output = "";
+    let totalChars = 0;
+    const decoder = new StringDecoder("utf8");
+    const append = (text: string): void =>
+    {
+        totalChars += text.length;
+        if (maxChars === undefined || output.length < maxChars)
+        {
+            output += maxChars === undefined ? text : text.slice(0, Math.max(0, maxChars - output.length));
+        }
+    };
+    for await (const chunk of stream)
+    {
+        // Byte boundaries are not character boundaries. Already-decoded streams
+        // retain their strings; flush pending bytes before switching to text.
+        append(typeof chunk === "string" ? decoder.end() + chunk : decoder.write(chunk));
+    }
+    append(decoder.end());
+    return { output, truncated: maxChars !== undefined && totalChars > maxChars, totalChars };
+};
+
+export type SpawnAndCollectDependencies = {
+    spawn?: typeof spawn;
+    setTimeout?: (callback: () => void, delay: number) => NodeJS.Timeout;
+    clearTimeout?: (timeout: NodeJS.Timeout) => void;
+    abortKillDelayMs?: number;
+    timeoutMs?: number;
+    outputLimitChars?: number;
+};
+
+export const spawnAndCollect = async (
+    command: string,
+    args: string[],
+    cwd: string,
+    input?: string,
+    signal?: AbortSignal,
+    dependencies: SpawnAndCollectDependencies = {},
+): Promise<SpawnResult> =>
+{
+    if (signal?.aborted)
+    {
+        throw new Error(`cm ${args.join(" ")} aborted before start.`);
+    }
+
+    let proc: ReturnType<typeof spawn>;
+    try
+    {
+        proc = (dependencies.spawn ?? spawn)(command, args, {
+            cwd,
+            stdio: [input ? "pipe" : "ignore", "pipe", "pipe"],
+            shell: false,
+        });
+    }
+    catch (error)
+    {
+        throw executableNotFoundError(command, error instanceof Error ? error : new Error(String(error)));
+    }
+
+    const scheduleTimeout = dependencies.setTimeout ?? setTimeout;
+    const cancelTimeout = dependencies.clearTimeout ?? clearTimeout;
+    const stdoutPromise = readStream(proc.stdout, dependencies.outputLimitChars);
+    const stderrPromise = readStream(proc.stderr, dependencies.outputLimitChars);
+    let aborted = false;
+    let timedOut = false;
+    let terminalSettled = false;
+    let killTimeout: NodeJS.Timeout | undefined;
+    let operationTimeout: NodeJS.Timeout | undefined;
+
+    let resolveExit: (exitCode: number) => void;
+    let rejectExit: (error: Error) => void;
+    const exitPromise = new Promise<number>((resolvePromise, rejectPromise) =>
+    {
+        resolveExit = resolvePromise;
+        rejectExit = rejectPromise;
+    });
+    const onProcessError = (error: Error) =>
+    {
+        if (terminalSettled)
+        {
+            return;
+        }
+
+        terminalSettled = true;
+        rejectExit(executableNotFoundError(command, error));
+    };
+    const onProcessClose = (code: number | null) =>
+    {
+        if (terminalSettled)
+        {
+            return;
+        }
+
+        terminalSettled = true;
+        resolveExit(code ?? 1);
+    };
+
+    // Register terminal listeners before any asynchronous stdin work can cause an error or close.
+    proc.once("error", onProcessError);
+    proc.once("close", onProcessClose);
+
+    const terminate = () =>
+    {
+        if (terminalSettled)
+        {
+            return;
+        }
+
+        try
+        {
+            proc.kill("SIGTERM");
+        }
+        catch
+        {
+            // The process may have settled between the state check and signal.
+        }
+        killTimeout = scheduleTimeout(() =>
+        {
+            // ChildProcess.killed only means a signal was sent. It does not mean the process settled.
+            if (!terminalSettled)
+            {
+                try
+                {
+                    proc.kill("SIGKILL");
+                }
+                catch
+                {
+                    // The process may have settled between the state check and signal.
+                }
+            }
+        }, dependencies.abortKillDelayMs ?? 5000);
+    };
+    const onAbort = () =>
+    {
+        aborted = true;
+        terminate();
+    };
+
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (dependencies.timeoutMs !== undefined)
+    {
+        operationTimeout = scheduleTimeout(() =>
+        {
+            timedOut = true;
+            terminate();
+        }, dependencies.timeoutMs);
+    }
+
+    try
+    {
+        const exitCode = input
+            ? await Promise.race([
+                exitPromise,
+                writeInput(proc.stdin, input).then(() => exitPromise),
+            ])
+            : await exitPromise;
+        const [stdoutResult, stderrResult] = await Promise.all([stdoutPromise, stderrPromise]);
+        return {
+            stdout: stdoutResult.output,
+            stderr: stderrResult.output,
+            exitCode,
+            aborted,
+            timedOut,
+            stdoutTruncated: stdoutResult.truncated,
+            stdoutTotalChars: stdoutResult.totalChars,
+            stderrTruncated: stderrResult.truncated,
+            stderrTotalChars: stderrResult.totalChars,
+        };
+    }
+    finally
+    {
+        signal?.removeEventListener("abort", onAbort);
+        proc.removeListener("error", onProcessError);
+        proc.removeListener("close", onProcessClose);
+        if (killTimeout)
+        {
+            cancelTimeout(killTimeout);
+        }
+        if (operationTimeout)
+        {
+            cancelTimeout(operationTimeout);
+        }
+    }
+};

package/src/execution/removal-command.ts

@@ -0,0 +1,118 @@
+import { spawn } from "node:child_process";
+import type { Readable } from "node:stream";
+import { commandExecutionStorage, getActiveAbortSignal } from "./context";
+import { getCmExecutable } from "./process";
+export type RemovalAttempt = { state: "not-attempted" | "not-started" | "started" | "unknown"; terminal: "not-observed" | "observed"; exitCode: number | null; aborted: boolean; timedOut: boolean };
+export const emptyRemovalAttempt = (): RemovalAttempt => ({ state: "not-attempted", terminal: "not-observed", exitCode: null, aborted: false, timedOut: false });
+export type RemovalCapture = { stdoutBytes: number; stderrBytes: number; stdoutRetainedBytes: number; stderrRetainedBytes: number; truncated: boolean; complete: boolean; validUtf8: boolean };
+export type RemovalCommandObservation = { attempt: RemovalAttempt; capture: RemovalCapture; stdout: string | null; stderr: string | null; failed: boolean };
+// Forced-retirement guards have no per-command state or retained buffers.
+const ignoreRetiredError = () => {};
+/** Selected-tool byte capture; never retries, changes encoding, or discards effect uncertainty. */
+export async function captureRemovalCommand(args: string[], workdir?: string, timeoutMs = 30000): Promise<RemovalCommandObservation> {
+    const attempt = emptyRemovalAttempt();
+    const capture: RemovalCapture = { stdoutBytes: 0, stderrBytes: 0, stdoutRetainedBytes: 0, stderrRetainedBytes: 0, truncated: false, complete: false, validUtf8: false };
+    const result: RemovalCommandObservation = { attempt, capture, stdout: null, stderr: null, failed: false };
+    const signal = getActiveAbortSignal(), deps = commandExecutionStorage.getStore() ?? {};
+    if (signal?.aborted) { attempt.aborted = true; return result; }
+    let child: ReturnType<typeof spawn>;
+    try { child = (deps.spawn ?? spawn)(getCmExecutable(), args, { cwd: workdir ?? process.cwd(), shell: false, stdio: ["ignore", "pipe", "pipe"] }); }
+    catch { attempt.state = "not-started"; result.failed = true; return result; }
+    attempt.state = "unknown";
+    const schedule = deps.setTimeout ?? setTimeout, cancel = deps.clearTimeout ?? clearTimeout;
+    let settled = false, failed = false, started = false, retired = false, finalized = false;
+    let terminationRequested = false, killTimer: NodeJS.Timeout | undefined, retireTimer: NodeJS.Timeout | undefined;
+    let settleExit!: () => void;
+    const finishers: Array<() => void> = [], disposers: Array<() => void> = [];
+    const retire = () => {
+        if (retired || finalized) return;
+        retired = true; failed = true;
+        // Retirement is not an observed terminal event or proof that the child stopped.
+        for (const emitter of [child, child.stdout, child.stderr]) emitter?.on("error", ignoreRetiredError);
+        settleExit();
+        for (const finish of finishers) finish();
+        child.stdout?.destroy(); child.stderr?.destroy();
+    };
+    const terminate = () => {
+        if (terminationRequested || retired || finalized) return;
+        terminationRequested = true;
+        const grace = deps.abortKillDelayMs ?? 5000;
+        if (!settled) { try { child.kill("SIGTERM"); } catch { /* not termination proof */ } }
+        killTimer = schedule(() => {
+            if (finalized || retired) return;
+            if (!settled) { try { child.kill("SIGKILL"); } catch { /* not termination proof */ } }
+            // Same bounded drain grace after KILL; terminal state never gates retirement.
+            retireTimer = schedule(retire, grace);
+        }, grace);
+    };
+    const collect = (stream: Readable | null, cap: number, name: "stdout" | "stderr") => {
+        let length = 0; const parts: Buffer[] = [];
+        if (!stream) { failed = true; terminate(); return Promise.resolve(Buffer.alloc(0)); }
+        if (stream.readableEncoding) { failed = true; terminate(); }
+        return new Promise<Buffer>(resolve => {
+            let done = false;
+            const finish = () => { if (!done) { done = true; const bytes = Buffer.concat(parts, length); parts.length = 0; resolve(bytes); } };
+            finishers.push(finish);
+            const data = (chunk: unknown) => {
+                if (done || retired || finalized) return;
+                if (!(chunk instanceof Uint8Array)) { failed = true; terminate(); return; }
+                const key = name === "stdout" ? "stdoutBytes" : "stderrBytes";
+                capture[key] = Math.min(Number.MAX_SAFE_INTEGER, capture[key] + chunk.byteLength);
+                const available = cap - length;
+                if (chunk.byteLength > available) { capture.truncated = true; terminate(); }
+                if (available > 0) { const part = Buffer.from(chunk.subarray(0, available)); parts.push(part); length += part.length; }
+            };
+            const error = () => { if (retired || finalized) return; failed = true; terminate(); finish(); };
+            const close = () => { if (retired || finalized) return; if (!done && !stream.readableEnded) failed = true; finish(); };
+            stream.on("data", data); stream.once("end", finish); stream.on("error", error); stream.once("close", close);
+            disposers.push(() => { stream.removeListener("data", data); stream.removeListener("end", finish); stream.removeListener("error", error); stream.removeListener("close", close); });
+        });
+    };
+    let onClose!: (code: number | null, terminalSignal?: string | null) => void, onError!: (error: NodeJS.ErrnoException) => void;
+    const onSpawn = () => { if (retired || finalized) return; started = true; attempt.state = "started"; };
+    const exit = new Promise<void>(resolve => {
+        settleExit = resolve;
+        onClose = (code, terminalSignal) => {
+            if (settled || retired || finalized) return; settled = true; attempt.terminal = "observed";
+            attempt.exitCode = Number.isInteger(code) && code !== null && code >= 0 && code <= 2147483647 ? code : null;
+            // A terminal event is not a substitute for the native start event.
+            if (!started) failed = true;
+            if (attempt.exitCode === null || terminalSignal) failed = true;
+            resolve();
+        };
+        onError = error => {
+            if (retired || finalized) return;
+            failed = true;
+            if (!started && ["ENOENT", "EACCES", "ENOTDIR"].includes(error.code ?? "")) {
+                attempt.state = "not-started"; settled = true; child.stdout?.destroy(); child.stderr?.destroy(); resolve();
+            } else { terminate(); }
+        };
+        child.once("spawn", onSpawn); child.once("close", onClose); child.on("error", onError);
+    });
+    const out = collect(child.stdout, 65536, "stdout"), err = collect(child.stderr, 16384, "stderr");
+    const onAbort = () => { if (retired || finalized) return; attempt.aborted = true; terminate(); };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const timer = schedule(() => { if (retired || finalized) return; attempt.timedOut = true; terminate(); }, Math.min(deps.timeoutMs ?? timeoutMs, timeoutMs));
+    if (signal?.aborted) onAbort();
+    try {
+        const [, stdout, stderr] = await Promise.all([exit, out, err]);
+        capture.stdoutRetainedBytes = stdout.length; capture.stderrRetainedBytes = stderr.length;
+        result.failed = failed;
+        try {
+            // Retain a literal UTF-8 BOM rather than silently removing source bytes.
+            result.stdout = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(stdout);
+            result.stderr = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(stderr);
+            capture.validUtf8 = true;
+        } catch { result.stdout = null; result.stderr = null; }
+        if (signal?.aborted) attempt.aborted = true;
+        capture.complete = !failed && !result.failed && !attempt.aborted && !attempt.timedOut && capture.validUtf8 && !capture.truncated && attempt.terminal === "observed";
+        return result;
+    } finally {
+        finalized = true;
+        cancel(timer); if (killTimer !== undefined) cancel(killTimer); if (retireTimer !== undefined) cancel(retireTimer);
+        signal?.removeEventListener("abort", onAbort);
+        child.removeListener("spawn", onSpawn); child.removeListener("close", onClose); child.removeListener("error", onError);
+        for (const dispose of disposers) dispose();
+        finishers.length = 0; disposers.length = 0;
+    }
+}