@aefree/pi-plastic 0.7.6 → 0.8.1

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

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

@@ -0,0 +1,75 @@
+import { spawn } from "node:child_process";
+import type { Readable } from "node:stream";
+export const WORKSPACE_LIST_CAPTURE_LIMITS = { stdoutBytes: 1048576, stderrBytes: 65536, timeoutMs: 30000, records: 20000 } as const;
+import { commandExecutionStorage, getActiveAbortSignal } from "./context";
+import { getCmExecutable } from "./process";
+export class WorkspaceListCommandError extends Error {
+    constructor(readonly code: "command_failed" | "aborted" | "capture_incomplete") { super(`Workspace list read failed (${code}).`); }
+}
+
+// Workspace-list-only strict byte transport. Native/default and status routes are unchanged.
+export async function runWorkspaceListFieldsCommand(args: string[], workdir?: string): Promise<Buffer> {
+    const signal = getActiveAbortSignal();
+    if (signal?.aborted) throw new WorkspaceListCommandError("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 WorkspaceListCommandError("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, WORKSPACE_LIST_CAPTURE_LIMITS.stdoutBytes);
+    const stderr = collect(child.stderr, WORKSPACE_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 ?? WORKSPACE_LIST_CAPTURE_LIMITS.timeoutMs, WORKSPACE_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 WorkspaceListCommandError("aborted");
+        if (incomplete) throw new WorkspaceListCommandError("capture_incomplete");
+        if (failed || code !== 0 || errors.length) throw new WorkspaceListCommandError("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/workspace-merge-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 WorkspaceMergeAttempt = { state: "not-attempted" | "not-started" | "started" | "unknown"; terminal: "not-observed" | "observed"; exitCode: number | null; aborted: boolean; timedOut: boolean };
+export const emptyWorkspaceMergeAttempt = (): WorkspaceMergeAttempt => ({ state: "not-attempted", terminal: "not-observed", exitCode: null, aborted: false, timedOut: false });
+export type WorkspaceMergeCapture = { stdoutBytes: number; stderrBytes: number; stdoutRetainedBytes: number; stderrRetainedBytes: number; truncated: boolean; complete: boolean; validUtf8: boolean };
+export type WorkspaceMergeCommandObservation = { attempt: WorkspaceMergeAttempt; capture: WorkspaceMergeCapture; 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 captureWorkspaceMergeCommand(args: string[], workdir?: string, timeoutMs = 30000): Promise<WorkspaceMergeCommandObservation> {
+    const attempt = emptyWorkspaceMergeAttempt();
+    const capture: WorkspaceMergeCapture = { stdoutBytes: 0, stderrBytes: 0, stdoutRetainedBytes: 0, stderrRetainedBytes: 0, truncated: false, complete: false, validUtf8: false };
+    const result: WorkspaceMergeCommandObservation = { 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;
+    }
+}

package/src/operations/add-receipt.ts

@@ -0,0 +1,37 @@
+import { captureAddCommand, emptyAddAttempt } from "../execution/add-command";
+import { ADD_COMMAND, safeAddText, validAddOperands, type AddData, type AddError, type AddReceipt } from "../domain/add-contract";
+export { ADD_COMMAND, safeAddText, validAddOperands } from "../domain/add-contract";
+export type { AddData, AddError, AddReceipt, AddAttempt, AddCapture } from "../domain/add-contract";
+export { presentAddReceipt } from "../presentation/add-results";
+export function emptyAddData(): AddData {
+    return { intendedArgv: [ADD_COMMAND], requestedOperandCount: null, workingDirectory: null, attempt: emptyAddAttempt(), capture: null, observedWorkspaceIdentity: null, observedAddedItems: null, verification: "unverified", effect: "not-attempted" };
+}
+function addHeader(data: AddData) {
+    return { schemaVersion: 1 as const, action: "add" as const, provenance: { source: "plastic" as const, producer: "@aefree/pi-plastic" as const, contentTrust: "external" as const }, completeness: { capture: data.capture ? data.capture.complete ? "complete" as const : "incomplete" as const : "unknown" as const, projection: true as const }, data };
+}
+export function addFailure(data: AddData, code: AddError["code"], message: string): AddReceipt {
+    return { ...addHeader(data), ok: false, outcome: data.effect === "uncertain" ? "uncertain" : "failed", error: { code, message } };
+}
+export async function assembleAddReceipt(args: unknown): Promise<AddReceipt> {
+    const data = emptyAddData(); let dispatched = false;
+    try {
+        if (!args || typeof args !== "object" || Array.isArray(args) || Object.keys(args).some(key => key !== "workdir" && key !== "paths")) return addFailure(data, "invalid_request", "Add accepts paths and workdir only; preview and extra options are unsupported.");
+        const input = args as Record<string, unknown>;
+        const cwd = input.workdir === undefined ? process.cwd() : input.workdir;
+        if (!safeAddText(cwd)) return addFailure(data, "invalid_request", "Working directory must be nonblank bounded text without controls or invalid Unicode.");
+        const paths = Array.isArray(input.paths) && input.paths.length <= 256 ? Array.from(input.paths) : input.paths;
+        if (!validAddOperands(paths)) return addFailure(data, "invalid_request", "Provide 1–256 bounded path operands; CLI options and stdin sentinel are rejected, aggregate UTF8 limit 32768 bytes.");
+        data.workingDirectory = cwd; data.intendedArgv = [ADD_COMMAND, ...paths]; data.requestedOperandCount = paths.length; dispatched = true;
+        const observation = await captureAddCommand([...data.intendedArgv], cwd);
+        data.attempt = observation.attempt; data.capture = observation.capture;
+        if (observation.capture.complete && !observation.failed && observation.attempt.state === "started" && observation.attempt.exitCode === 0) {
+            data.effect = "not-proven";
+            return { ...addHeader(data), ok: true, outcome: "command-completed" };
+        }
+        data.effect = ["started", "unknown"].includes(data.attempt.state) ? "uncertain" : "not-attempted";
+        return addFailure(data, data.attempt.aborted ? "aborted" : data.effect === "uncertain" ? "uncertain" : "launch_failed", data.effect === "uncertain" ? "Add completion is not proven; partial added-item or workspace effects may exist." : "Add did not establish a process start.");
+    } catch {
+        if (dispatched) { data.attempt = { ...emptyAddAttempt(), state: "unknown" }; data.capture = null; data.effect = "uncertain"; }
+        return addFailure(data, "producer_failed", "Add observation failed; no rollback or safe retry is proven.");
+    }
+}

package/src/operations/arguments.ts

@@ -0,0 +1,3 @@
+import { tool } from "../tool-definition";
+
+export const workdirArg = tool.schema.string().optional().describe("Working directory for the workspace.");

package/src/operations/branch-create.ts

@@ -0,0 +1,74 @@
+import { resolveBranchCreationTarget, normalizeBranchSpecForComparison } from "../domain/branches";
+import { emptyBranchCreateAttempt, safeBranchCreateText, parseBranchCreateParent, type BranchCreateRequest, type BranchCreateReceipt, type BranchCreateData, type BranchCreateError } from "../domain/branch-create-contract";
+import { captureBranchCreateCommand } from "../execution/branch-create-command";
+export { presentBranchCreateReceipt } from "../presentation/branch-create";
+export { safeBranchCreateText } from "../domain/branch-create-contract";
+export type { BranchCreateReceipt, BranchCreateAttempt, BranchCreateCapture } from "../domain/branch-create-contract";
+class BranchCreateInputError extends Error {}
+export function validateBranchCreateRequest(input: unknown): asserts input is BranchCreateRequest {
+    if (!input || typeof input !== "object" || Array.isArray(input)) throw new BranchCreateInputError("Branch creation input must be an object.");
+    const r = input as Record<string, unknown>;
+    const strings = ["branch", "parent", "changeset", "label", "comment", "commentsFile", "workdir"];
+    if (Object.keys(r).some(k => ![...strings, "allowRootBranch"].includes(k)) || r.allowRootBranch !== undefined && typeof r.allowRootBranch !== "boolean") throw new BranchCreateInputError("Branch creation input contains unsupported options.");
+    for (const key of strings) if (r[key] !== undefined && (typeof r[key] !== "string" || !safeBranchCreateText(r[key] as string))) throw new BranchCreateInputError("Branch creation strings must be bounded and free of control or malformed characters.");
+    if (typeof r.branch !== "string" || !r.branch.trim()) throw new BranchCreateInputError("Branch must be non-empty.");
+    if (r.changeset && r.label) throw new BranchCreateInputError("Provide either changeset or label, not both.");
+    if (r.comment && r.commentsFile) throw new BranchCreateInputError("Provide either comment or commentsFile, not both.");
+    if (r.comment !== undefined && !(r.comment as string).trim()) throw new BranchCreateInputError("Comment must be non-empty when provided.");
+}
+export async function assembleBranchCreateReceipt(input: unknown): Promise<BranchCreateReceipt> {
+    const data: BranchCreateData = { requested: null, resolvedTarget: null, parentResolution: { basis: "not-required", observedBranch: null, repositoryVerification: "unverified" }, parentCommands: [], command: null, attempt: emptyBranchCreateAttempt(), capture: null, observedCreatedIdentity: null, repositoryVerification: "unverified", workspaceSwitch: "not-requested" };
+    const completeness: BranchCreateReceipt["completeness"] = { capture: "unknown", projection: true };
+    let stage: BranchCreateError["stage"] = "input";
+    const finish = (outcome: BranchCreateReceipt["outcome"], code: BranchCreateError["code"] = "uncertain", message = "Branch creation evidence is unverified; do not retry automatically."): BranchCreateReceipt => ({ schemaVersion: 1, action: "branch-create", provenance: { source: "plastic", producer: "@aefree/pi-plastic", contentTrust: "external" }, completeness, ok: outcome === "command-completed", outcome, data: { ...data, effect: outcome === "command-completed" ? "not-proven" : outcome === "uncertain" ? "uncertain" : "not-attempted" }, ...(outcome === "command-completed" ? {} : { error: { code, stage, message } }) }) as BranchCreateReceipt;
+    try {
+        validateBranchCreateRequest(input);
+        const r = input;
+        data.requested = { branch: r.branch, parent: r.parent ?? null, changeset: r.changeset ?? null, label: r.label ?? null, comment: r.comment ?? null, commentsFile: r.commentsFile ?? null, allowRootBranch: r.allowRootBranch ?? false };
+        const relative = !normalizeBranchSpecForComparison(r.branch).startsWith("/");
+        // These forms formerly discarded qualification. Never dispatch a different scope.
+        if (relative && (r.branch.includes("@") || r.parent?.includes("@"))) return finish("unsupported", "ambiguous_qualifier", "Relative qualifier-bearing branch creation cannot resolve scope safely; provide a full hierarchical target.");
+        stage = "source";
+        if (process.platform !== "win32") return finish("unsupported", "unsupported_source", "Branch creation source is admitted only on Windows.");
+        let parent = r.parent;
+        if (relative && parent === undefined) {
+            stage = "parent"; data.parentResolution.basis = "unresolved";
+            for (const argv of [["status"], ["status", "--compact"]]) {
+                const obs = await captureBranchCreateCommand(argv, r.workdir);
+                data.parentCommands.push({ argv, attempt: obs.attempt, capture: obs.capture });
+                completeness.capture = obs.capture.complete ? "complete" : "incomplete";
+                if (!obs.capture.complete || obs.failed || obs.attempt.exitCode !== 0 || obs.capture.stderrBytes) return finish("failed", "parent_unresolved", "Current parent could not be observed; provide an explicit parent.");
+                // Only standard status has admitted original loaded-branch fidelity.
+                if (argv.length === 1) parent = parseBranchCreateParent(obs.stdout! ) ?? undefined;
+                if (parent !== undefined) break;
+            }
+            if (parent === undefined) return finish("unsupported", "parent_unresolved", "A changeset's owning branch does not identify the loaded branch; provide an explicit parent.");
+            data.parentResolution = { basis: "status", observedBranch: parent, repositoryVerification: "unverified" };
+        } else if (relative) data.parentResolution.basis = "explicit";
+        stage = "input";
+        let target: string;
+        try { target = resolveBranchCreationTarget(r.branch, parent, r.allowRootBranch); }
+        catch {
+            const root = normalizeBranchSpecForComparison(r.branch).startsWith("/") && normalizeBranchSpecForComparison(r.branch).split("/").filter(Boolean).length === 1;
+            throw new BranchCreateInputError(root ? "Refusing to create top-level branch. Provide a hierarchical target or allowRootBranch=true for intentional root creation." : "Parent branch must be a non-root hierarchical branch path.");
+        }
+        if (!safeBranchCreateText(target)) throw new BranchCreateInputError("Resolved branch exceeds the identity bound.");
+        const argv = ["branch", "create", target];
+        if (r.changeset) argv.push(`--changeset=${r.changeset}`);
+        if (r.label) argv.push(`--label=${r.label}`);
+        if (r.comment) argv.push(`-c=${r.comment}`);
+        if (r.commentsFile) argv.push(`-commentsfile=${r.commentsFile}`);
+        if (argv.length > 8 || argv.some(s => s.length > 8192) || Buffer.byteLength(JSON.stringify(argv), "utf8") > 65536) throw new BranchCreateInputError("Branch creation argv exceeds the aggregate bound.");
+        data.resolvedTarget = target; data.command = argv;
+        stage = "create";
+        const obs = await captureBranchCreateCommand(argv, r.workdir);
+        data.attempt = obs.attempt; data.capture = obs.capture;
+        completeness.capture = obs.capture.complete ? "complete" : "incomplete";
+        if (["not-attempted", "not-started"].includes(obs.attempt.state)) return finish("failed", obs.attempt.aborted ? "aborted" : "launch_failed");
+        if (!obs.failed && obs.capture.complete && obs.attempt.state === "started" && obs.attempt.terminal === "observed" && obs.attempt.exitCode === 0 && !obs.attempt.aborted && !obs.attempt.timedOut && !obs.capture.stderrBytes) return finish("command-completed");
+        return finish("uncertain");
+    } catch (error) {
+        if (stage === "create") { if (data.attempt.state === "not-attempted") data.attempt.state = "unknown"; return finish("uncertain", "producer_failed"); }
+        return finish("failed", stage === "input" ? "invalid_request" : "parent_unresolved", error instanceof BranchCreateInputError ? error.message : "Branch target or current parent could not be resolved safely.");
+    }
+}

package/src/operations/branch-delete-receipt.ts

@@ -0,0 +1,25 @@
+import { captureWorkspaceMergeCommand, emptyWorkspaceMergeAttempt } from "../execution/workspace-merge-command";
+import { branchDeleteArgv, safeBranchDeleteText, validBranchDeleteOperand, type BranchDeleteData, type BranchDeleteError, type BranchDeleteReceipt } from "../domain/branch-delete-contract";
+export { branchDeleteArgv, safeBranchDeleteText, validBranchDeleteOperand } from "../domain/branch-delete-contract";
+export type { BranchDeleteReceipt } from "../domain/branch-delete-contract";
+export { presentBranchDeleteReceipt } from "../presentation/branch-delete-results";
+export function emptyBranchDeleteData(): BranchDeleteData { return { intendedArgv:["branch","delete"], requestedBranch:null, workingDirectory:null, deleteChangesetsRequested:null, previewRequested:null, outputFormatRequested:null, attempt:emptyWorkspaceMergeAttempt(), capture:null, observedDeletedBranch:null, observedDeletedChangesets:null, observedRepositoryIdentity:null, observedWorkspaceIdentity:null, verification:"unverified", rollback:"not-proven", effect:"not-attempted" }; }
+function header(data:BranchDeleteData) { return { schemaVersion:1 as const, action:"branch-delete" as const, provenance:{source:"plastic" as const,producer:"@aefree/pi-plastic" as const,contentTrust:"external" as const},completeness:{capture:data.capture?data.capture.complete?"complete" as const:"incomplete" as const:"unknown" as const,projection:true as const},data }; }
+export function branchDeleteFailure(data:BranchDeleteData,code:BranchDeleteError["code"],message:string):BranchDeleteReceipt { return {...header(data),ok:false,outcome:data.effect==="uncertain"?"uncertain":"failed",error:{code,message}}; }
+export async function assembleBranchDeleteReceipt(args:unknown):Promise<BranchDeleteReceipt> {
+ const data=emptyBranchDeleteData();let entered=false;
+ try {
+  if(!args||typeof args!=="object"||Array.isArray(args)||Object.keys(args).some(k=>!["branch","deleteChangesets","preflight","format","workdir"].includes(k)))return branchDeleteFailure(data,"invalid_request","Use only declared bounded branch-delete controls.");
+  const i=Object.freeze({...args}) as Record<string,unknown>,branch=i.branch,cwd=i.workdir??(i.workdir===undefined?process.cwd():null),del=i.deleteChangesets===undefined?false:i.deleteChangesets,preview=i.preflight===undefined?false:i.preflight,format=i.format===undefined?"text":i.format;
+  if(!validBranchDeleteOperand(branch)||!safeBranchDeleteText(cwd)||typeof del!=="boolean"||typeof preview!=="boolean"||!["text","json"].includes(format as string))return branchDeleteFailure(data,"invalid_request","Use one bounded exact branch operand, strict booleans and text/json. Options/stdin are not branch operands.");
+  data.requestedBranch=branch;data.workingDirectory=cwd;data.deleteChangesetsRequested=del;data.previewRequested=preview;data.outputFormatRequested=format as "text"|"json";data.intendedArgv=branchDeleteArgv(branch,del);
+  if(preview)return {...header(data),ok:true,outcome:"preflight"};
+  entered=true;const o=await captureWorkspaceMergeCommand([...data.intendedArgv],cwd);data.attempt=o.attempt;data.capture=o.capture;
+  if(o.capture.complete&&!o.failed&&o.attempt.state==="started"&&o.attempt.exitCode===0){data.effect="not-proven";return {...header(data),ok:true,outcome:"command-completed"};}
+  data.effect=["started","unknown"].includes(data.attempt.state)?"uncertain":"not-attempted";
+  return branchDeleteFailure(data,data.attempt.aborted?"aborted":data.effect==="uncertain"?"uncertain":"launch_failed",data.effect==="uncertain"?"Branch deletion completion is uncertain; branch/history effects may already exist.":"Branch deletion did not establish process start.");
+ }catch{
+  if(entered){data.attempt={...emptyWorkspaceMergeAttempt(),state:"unknown"};data.capture=null;data.effect="uncertain";}
+  return branchDeleteFailure(data,"producer_failed","Branch deletion observation failed; no rollback or safe retry is proven.");
+ }
+}

package/src/operations/branch-list.ts

@@ -0,0 +1,94 @@
+import { cmWhereEquals, cmWhereLike } from "../domain/branches";
+import { runCm } from "../execution/cm";
+import { spawnAndCollect, getCmExecutable } from "../execution/process";
+import { commandExecutionStorage, getActiveAbortSignal } from "../execution/context";
+import { runBranchListNamesCommand, BranchListCommandError, BRANCH_LIST_CAPTURE_LIMITS } from "../execution/branch-list-command";
+
+export type BranchListArgs = { nameLike?: string; parent?: string; owner?: string; includeHidden?: boolean; limit?: number; orderBy?: "date" | "branchname"; descending?: boolean; workdir?: string; source?: "native" | "names"; format?: "text" | "json"; maxItems?: number };
+export type BranchListQuery = { nameLike: string | null; parent: string | null; owner: string | null; includeHidden: boolean; limit: number | null; orderBy: "date" | "branchname" | null; descending: boolean };
+export class BranchListError extends Error {
+    constructor(readonly code: "invalid_identity" | "malformed_output" | "unsupported_query" | "invalid_producer_data" | "output_overflow") { super(`Branch list observation failed (${code}); no reusable rows are available.`); }
+}
+export const validBranchQueryString = (value: string): boolean => value.length <= 4096 && !/[\u0000-\u001f\u007f-\u009f\uD800-\uDFFF]/u.test(value);
+export const validBranchListIdentity = (value: string): boolean => value.length > 0 && value.length <= 4096
+    && /^\/[^/@\\]+(?:\/[^/@\\]+)*$/u.test(value)
+    && !/[\u0000-\u001f\u007f-\u009f\uD800-\uDFFF\uFFFD]/u.test(value)
+    && !(process.platform === "win32" && value.includes("?"));
+export function branchListRequest(args: BranchListArgs): { source: "native" | "names"; maxItems: number; query: BranchListQuery } {
+    for (const value of [args.nameLike, args.parent, args.owner]) if (value !== undefined && (typeof value !== "string" || !validBranchQueryString(value))) throw new BranchListError("invalid_identity");
+    if ((args.source !== undefined && args.source !== "native" && args.source !== "names")
+        || (args.format !== undefined && args.format !== "text" && args.format !== "json")
+        || (args.orderBy !== undefined && args.orderBy !== "date" && args.orderBy !== "branchname")
+        || [args.includeHidden, args.descending].some(value => value !== undefined && typeof value !== "boolean")
+        || (args.limit !== undefined && (!Number.isSafeInteger(args.limit) || args.limit < 1))
+        || (args.maxItems !== undefined && (!Number.isSafeInteger(args.maxItems) || args.maxItems < 1 || args.maxItems > 500))) throw new BranchListError("invalid_producer_data");
+    const source = args.source ?? "native";
+    if (source === "names" && args.includeHidden === true) throw new BranchListError("unsupported_query");
+    return { source, maxItems: args.maxItems ?? 100, query: { nameLike: args.nameLike ?? null, parent: args.parent ?? null, owner: args.owner ?? null, includeHidden: args.includeHidden ?? false, limit: args.limit ?? null, orderBy: args.orderBy ?? null, descending: args.descending ?? false } };
+}
+export function branchListCommand(query: BranchListQuery, source: "native" | "names"): string[] {
+    const where: string[] = [];
+    if (query.nameLike) where.push(cmWhereLike("name", query.nameLike));
+    if (query.parent) where.push(cmWhereEquals("parent", query.parent));
+    if (query.owner) where.push(cmWhereEquals("owner", query.owner));
+    where.push(query.includeHidden ? "(hidden = 'true' or hidden = 'false')" : "hidden = 'false'");
+    return ["find", "branch", `where ${where.join(" and ")}`, ...(query.orderBy ? [`order by ${query.orderBy}${query.descending ? " desc" : " asc"}`] : []), ...(query.limit ? [`limit ${query.limit}`] : []), "--nototal", ...(source === "names" ? ["--format={name}", "--encoding=utf-8"] : [])];
+}
+export function parseBranchListNames(bytes: Uint8Array): string[] {
+    if (bytes.byteLength > BRANCH_LIST_CAPTURE_LIMITS.stdoutBytes) throw new BranchListCommandError("capture_incomplete");
+    let output: string;
+    // Preserve BOM as data: a foreign prefix must not silently disappear.
+    try { output = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes); } catch { throw new BranchListError("invalid_identity"); }
+    if (!output) return [];
+    const rows = output.split(/\r?\n/u);
+    if (rows.at(-1) === "") rows.pop();
+    if (rows.length > BRANCH_LIST_CAPTURE_LIMITS.records) throw new BranchListCommandError("capture_incomplete");
+    const seen = new Set<string>();
+    for (const row of rows) {
+        if (!validBranchListIdentity(row)) throw new BranchListError("invalid_identity");
+        if (seen.has(row)) throw new BranchListError("malformed_output");
+        seen.add(row);
+    }
+    return rows;
+}
+export type BranchListObservation = ReturnType<typeof branchListRequest> & ({ source: "native"; rawResult: string } | { source: "names"; branches: string[] });
+export async function assembleBranchListObservation(args: BranchListArgs, typedNative = false): Promise<BranchListObservation> {
+    const request = branchListRequest(args);
+    const command = branchListCommand(request.query, request.source);
+    if (request.source === "names") {
+        const bytes = await runBranchListNamesCommand(command, args.workdir);
+        if (getActiveAbortSignal()?.aborted) throw new BranchListCommandError("aborted");
+        const branches = parseBranchListNames(bytes);
+        if (getActiveAbortSignal()?.aborted) throw new BranchListCommandError("aborted");
+        return { ...request, source: "names", branches };
+    }
+    // Core default keeps runCm's legacy string/error presentation. The registered
+    // native adapter classifies observed process flags, never formatted errors.
+    if (!typedNative) return { ...request, source: "native", rawResult: await runCm(command, args.workdir) };
+    const signal = getActiveAbortSignal();
+    if (signal?.aborted) throw new BranchListCommandError("aborted");
+    let result;
+    try { result = await spawnAndCollect(getCmExecutable(), command, args.workdir ?? process.cwd(), undefined, signal, commandExecutionStorage.getStore()); }
+    catch { throw new BranchListCommandError(signal?.aborted ? "aborted" : "command_failed"); }
+    if (result.aborted || signal?.aborted) throw new BranchListCommandError("aborted");
+    if (result.timedOut || result.stdoutTruncated || result.stderrTruncated) throw new BranchListCommandError("capture_incomplete");
+    if (result.exitCode !== 0) throw new BranchListCommandError("command_failed");
+    return { ...request, source: "native", rawResult: [result.stdout, result.stderr].filter(Boolean).join("\n").trim() || "(no output)" };
+}
+export function presentBranchListObservation(observation: BranchListObservation): string {
+    if (observation.source === "native") return observation.rawResult;
+    const returned = observation.branches.slice(0, observation.maxItems);
+    const omitted = observation.branches.length - returned.length;
+    return [...(returned.length ? returned : ["(no observed query rows)"]), ...(omitted ? [`(${omitted} observed query rows omitted from presentation.)`] : [])].join("\n");
+}
+
+export const BRANCH_LIST_MAX_BYTES = 131072;
+export function branchListPayload(observation: BranchListObservation) {
+    const common = { schemaVersion: 1, action: "branch-list", provenance: { source: "plastic", producer: "@aefree/pi-plastic", contentTrust: "external" }, ok: true } as const;
+    const data = { scope: "workspace_repository", qualifierVerified: false, query: observation.query, limits: { maxItems: observation.maxItems, identityCodeUnits: 4096, compactUtf8Bytes: BRANCH_LIST_MAX_BYTES } } as const;
+    const payload = observation.source === "native"
+        ? { ...common, completeness: { read: "unknown", capture: "unknown", projection: false }, data: { ...data, mode: "native", basis: "find_branch_native", rows: null, countBasis: "unavailable", counts: null } }
+        : { ...common, completeness: { read: "complete", capture: "complete", projection: observation.branches.length <= observation.maxItems }, data: { ...data, mode: "names", basis: "find_branch_name_utf8", rows: observation.branches.slice(0, observation.maxItems).map(branch => ({ branch })), countBasis: "observed_query_rows", counts: { observed: observation.branches.length, returned: Math.min(observation.branches.length, observation.maxItems), omitted: Math.max(0, observation.branches.length - observation.maxItems), excluded: 0 } } };
+    if (Buffer.byteLength(JSON.stringify(payload), "utf8") > BRANCH_LIST_MAX_BYTES) throw new BranchListError("output_overflow");
+    return payload;
+}