@aefree/pi-plastic 0.7.6 → 0.8.0

package/src/execution/server-merge-command.ts

@@ -0,0 +1,92 @@
+import { spawn } from "node:child_process";
+import type { Readable } from "node:stream";
+import { commandExecutionStorage, getActiveAbortSignal } from "./context";
+import { getCmExecutable } from "./process";
+export type MergeAttempt = { state: "not-attempted" | "not-started" | "started" | "unknown"; terminal: "not-observed" | "observed"; exitCode: number | null; aborted: boolean; timedOut: boolean };
+export type MergeCapture = { stdoutBytes: number; stderrBytes: number; stdoutRetainedBytes: number; stderrRetainedBytes: number; truncated: boolean; complete: boolean; validUtf8: boolean };
+export const emptyMergeAttempt = (): MergeAttempt => ({ state: "not-attempted", terminal: "not-observed", exitCode: null, aborted: false, timedOut: false });
+export type ServerCommandObservation = { attempt: MergeAttempt; capture: MergeCapture; stdout: string | null; stderr: string | null; failed: boolean };
+/** Selected-tool byte capture; never retries, changes encoding, or discards effect uncertainty. */
+export async function captureServerMergeCommand(args: string[], timeoutMs: number): Promise<ServerCommandObservation> {
+    const attempt = emptyMergeAttempt();
+    const capture: MergeCapture = { stdoutBytes: 0, stderrBytes: 0, stdoutRetainedBytes: 0, stderrRetainedBytes: 0, truncated: false, complete: false, validUtf8: false };
+    const result: ServerCommandObservation = { 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: 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, killTimer: NodeJS.Timeout | undefined;
+    const terminate = () => {
+        if (settled) return;
+        try { child.kill("SIGTERM"); } catch { /* completion race */ }
+        if (killTimer === undefined) killTimer = schedule(() => { if (!settled) { try { child.kill("SIGKILL"); } catch { /* completion race */ } } }, deps.abortKillDelayMs ?? 5000);
+    };
+    const disposers: Array<() => void> = [];
+    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; resolve(Buffer.concat(parts, length)); } };
+            const data = (chunk: unknown) => {
+                if (!(chunk instanceof Uint8Array)) { failed = true; terminate(); return; }
+                capture[name === "stdout" ? "stdoutBytes" : "stderrBytes"] += 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 = () => { failed = true; terminate(); finish(); };
+            const close = () => { if (!done && !stream.readableEnded) failed = true; finish(); };
+            stream.on("data", data); stream.once("end", finish); stream.once("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 = () => { started = true; attempt.state = "started"; };
+    const exit = new Promise<void>(resolve => {
+        onClose = (code, terminalSignal) => {
+            if (settled) return; settled = true; attempt.terminal = "observed";
+            attempt.exitCode = Number.isInteger(code) && code !== null && code >= 0 ? code : null;
+            if (!failed && attempt.exitCode !== null && !terminalSignal) attempt.state = "started";
+            if (attempt.exitCode === null || terminalSignal) failed = true;
+            resolve();
+        };
+        onError = error => {
+            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.once("error", onError);
+    });
+    const out = collect(child.stdout, 65536, "stdout"), err = collect(child.stderr, 16384, "stderr");
+    const onAbort = () => { attempt.aborted = true; terminate(); };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const timer = schedule(() => { 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 {
+            result.stdout = new TextDecoder("utf-8", { fatal: true }).decode(stdout);
+            result.stderr = new TextDecoder("utf-8", { fatal: true }).decode(stderr);
+            capture.validUtf8 = true;
+            // Updated CM help includes the resolution-file contract (~19 KiB).
+            // Keep a bounded 32 KiB decoded help gate; merge evidence uses source bytes.
+            if (timeoutMs === 3000 && (result.stdout.length > 32768 || result.stderr.length > 16384)) { result.failed = 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 {
+        cancel(timer); if (killTimer !== undefined) cancel(killTimer);
+        signal?.removeEventListener("abort", onAbort);
+        child.removeListener("spawn", onSpawn); child.removeListener("close", onClose); child.removeListener("error", onError);
+        for (const dispose of disposers) dispose();
+    }
+}

package/src/execution/shelveset-list-command.ts

@@ -0,0 +1,75 @@
+import { spawn } from "node:child_process";
+import type { Readable } from "node:stream";
+export const SHELVESET_LIST_CAPTURE_LIMITS = { stdoutBytes: 1048576, stderrBytes: 65536, timeoutMs: 30000, records: 20000 } as const;
+import { commandExecutionStorage, getActiveAbortSignal } from "./context";
+import { getCmExecutable } from "./process";
+export class ShelvesetListCommandError extends Error {
+    constructor(readonly code: "command_failed" | "aborted" | "capture_incomplete") { super(`Shelveset list read failed (${code}).`); }
+}
+
+// Shelveset-list-only strict byte transport. Native/default and other read routes are unchanged.
+export async function runShelvesetListIdsCommand(args: string[], workdir?: string): Promise<Buffer> {
+    const signal = getActiveAbortSignal();
+    if (signal?.aborted) throw new ShelvesetListCommandError("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 ShelvesetListCommandError("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, SHELVESET_LIST_CAPTURE_LIMITS.stdoutBytes);
+    const stderr = collect(child.stderr, SHELVESET_LIST_CAPTURE_LIMITS.stderrBytes);
+    const onAbort = () => { aborted = true; terminate(); };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const timeout = schedule(() => { incomplete = true; terminate(); }, Math.min(dependencies.timeoutMs ?? SHELVESET_LIST_CAPTURE_LIMITS.timeoutMs, SHELVESET_LIST_CAPTURE_LIMITS.timeoutMs));
+    if (signal?.aborted) onAbort();
+    try {
+        const [code, bytes, errors] = await Promise.all([exit, stdout, stderr]);
+        if (aborted || signal?.aborted) throw new ShelvesetListCommandError("aborted");
+        if (incomplete) throw new ShelvesetListCommandError("capture_incomplete");
+        if (failed || code !== 0 || errors.length) throw new ShelvesetListCommandError("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/status-command.ts

@@ -0,0 +1,29 @@
+import { commandExecutionStorage, getActiveAbortSignal } from "./context";
+import { getCmExecutable, spawnAndCollect } from "./process";
+
+export class StatusCommandError extends Error {
+    constructor(readonly code: "command_failed" | "aborted" | "capture_incomplete") {
+        super(code === "aborted" ? "Status read was cancelled." : code === "capture_incomplete" ? "Status capture was incomplete." : "Status command failed; CLI support or availability is not established.");
+    }
+}
+
+// Status-only transport evidence. No raw command/error text crosses this seam on failure.
+export const runStatusCommand = async (args: string[], workdir?: string, raw = false) => {
+    const signal = getActiveAbortSignal();
+    if (signal?.aborted) throw new StatusCommandError("aborted");
+    let result;
+    try {
+        result = await spawnAndCollect(getCmExecutable(), args, workdir ?? process.cwd(), undefined, signal, commandExecutionStorage.getStore());
+    } catch {
+        throw new StatusCommandError(signal?.aborted ? "aborted" : "command_failed");
+    }
+    if (result.aborted) throw new StatusCommandError("aborted");
+    if (result.timedOut || result.stdoutTruncated || result.stderrTruncated) throw new StatusCommandError("capture_incomplete");
+    if (result.exitCode !== 0) throw new StatusCommandError("command_failed");
+    const combined = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
+    return {
+        output: raw ? result.stdout : combined || "(no output)",
+        // Successful stderr is not machine status evidence. Do not expose its content.
+        capture: raw && result.stderr.length > 0 ? "unknown" as const : "complete" as const,
+    };
+};

package/src/execution/status-xml-command.ts

@@ -0,0 +1,72 @@
+import { spawn } from "node:child_process";
+import type { Readable } from "node:stream";
+import { STATUS_XML_LIMITS } from "./status-xml-limits";
+import { commandExecutionStorage, getActiveAbortSignal } from "./context";
+import { getCmExecutable } from "./process";
+import { StatusCommandError } from "./status-command";
+
+// Status-only raw byte capture. Generic command adapters retain their existing semantics.
+export async function runStatusXmlCommand(workdir?: string): Promise<Buffer> {
+    const signal = getActiveAbortSignal();
+    if (signal?.aborted) throw new StatusCommandError("aborted");
+    const dependencies = commandExecutionStorage.getStore() ?? {};
+    let child;
+    try { child = (dependencies.spawn ?? spawn)(getCmExecutable(), ["status", "--xml", "--encoding=utf-8", "--fullpaths"], { cwd: workdir ?? process.cwd(), shell: false, stdio: ["ignore", "pipe", "pipe"] }); }
+    catch { throw new StatusCommandError("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)); }
+        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, STATUS_XML_LIMITS.stdoutBytes);
+    const stderr = collect(child.stderr, STATUS_XML_LIMITS.stderrBytes);
+    const onAbort = () => { aborted = true; terminate(); };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const timeout = schedule(() => { incomplete = true; terminate(); }, Math.min(dependencies.timeoutMs ?? STATUS_XML_LIMITS.timeoutMs, STATUS_XML_LIMITS.timeoutMs));
+    if (signal?.aborted) onAbort();
+    try {
+        const [code, bytes, errors] = await Promise.all([exit, stdout, stderr]);
+        if (aborted || signal?.aborted) throw new StatusCommandError("aborted");
+        if (incomplete) throw new StatusCommandError("capture_incomplete");
+        if (failed || code !== 0 || errors.length) throw new StatusCommandError("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/status-xml-limits.ts

@@ -0,0 +1 @@
+export const STATUS_XML_LIMITS = { stdoutBytes: 1048576, stderrBytes: 65536, depth: 16, records: 20000, path: 4096, code: 64, text: 8192, timeoutMs: 30000 } as const;

package/src/execution/switch-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 SwitchAttempt = { state: "not-attempted" | "not-started" | "started" | "unknown"; terminal: "not-observed" | "observed"; exitCode: number | null; aborted: boolean; timedOut: boolean };
+export const emptySwitchAttempt = (): SwitchAttempt => ({ state: "not-attempted", terminal: "not-observed", exitCode: null, aborted: false, timedOut: false });
+export type SwitchCapture = { stdoutBytes: number; stderrBytes: number; stdoutRetainedBytes: number; stderrRetainedBytes: number; truncated: boolean; complete: boolean; validUtf8: boolean };
+export type SwitchCommandObservation = { attempt: SwitchAttempt; capture: SwitchCapture; 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 captureSwitchCommand(args: string[], workdir?: string, timeoutMs = 30000): Promise<SwitchCommandObservation> {
+    const attempt = emptySwitchAttempt();
+    const capture: SwitchCapture = { stdoutBytes: 0, stderrBytes: 0, stdoutRetainedBytes: 0, stderrRetainedBytes: 0, truncated: false, complete: false, validUtf8: false };
+    const result: SwitchCommandObservation = { 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, args.includes("--machinereadable") ? 1048576 : 65536, "stdout"), err = collect(child.stderr, args.includes("--machinereadable") ? 65536 : 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;
+    }
+}

package/src/execution/test-seams.ts

@@ -0,0 +1,10 @@
+import { ExecutableEnvironment, resolveExecutable, spawnAndCollect } from "./process";
+import { runCm, runCmRaw } from "./cm";
+
+export const __plasticProcessInternals = {
+    resolveCmExecutable: (environment: ExecutableEnvironment = process.env): string => resolveExecutable(environment, "PI_PLASTIC_CM_EXECUTABLE", "cm"),
+    resolveDiffExecutable: (environment: ExecutableEnvironment = process.env): string => resolveExecutable(environment, "PI_PLASTIC_DIFF_EXECUTABLE", "diff"),
+    spawnAndCollect,
+    runCm,
+    runCmRaw,
+};

package/src/execution/undo-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 UndoAttempt = { state: "not-attempted" | "not-started" | "started" | "unknown"; terminal: "not-observed" | "observed"; exitCode: number | null; aborted: boolean; timedOut: boolean };
+export const emptyUndoAttempt = (): UndoAttempt => ({ state: "not-attempted", terminal: "not-observed", exitCode: null, aborted: false, timedOut: false });
+export type UndoCapture = { stdoutBytes: number; stderrBytes: number; stdoutRetainedBytes: number; stderrRetainedBytes: number; truncated: boolean; complete: boolean; validUtf8: boolean };
+export type UndoCommandObservation = { attempt: UndoAttempt; capture: UndoCapture; 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 captureUndoCommand(args: string[], workdir?: string, timeoutMs = 30000): Promise<UndoCommandObservation> {
+    const attempt = emptyUndoAttempt();
+    const capture: UndoCapture = { stdoutBytes: 0, stderrBytes: 0, stdoutRetainedBytes: 0, stderrRetainedBytes: 0, truncated: false, complete: false, validUtf8: false };
+    const result: UndoCommandObservation = { 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;
+    }
+}