@aefree/pi-plastic 0.7.6 → 0.8.0

package/src/domain/switch-policy.ts

@@ -0,0 +1,95 @@
+import type { PendingItemSummary, PendingSummary } from "./pending";
+import { isSameBranchSpec } from "./branches";
+export type SwitchPendingProfile = {
+    hasPendingChanges: boolean;
+    hasTrackedPendingChanges: boolean;
+    hasPrivatePendingChanges: boolean;
+    hasPrivateOnlyPendingChanges: boolean;
+};
+
+export const toLegacyPendingSummary = (summary: PendingItemSummary): PendingSummary =>
+{
+    return {
+        totalPending: summary.totalPending,
+        added: summary.added,
+        changed: summary.changed,
+        moved: summary.moved,
+        deleted: summary.deleted,
+        other: summary.other + summary.private,
+    };
+};
+
+export const buildSwitchPendingProfile = (summary: PendingItemSummary): SwitchPendingProfile =>
+{
+    return {
+        hasPendingChanges: summary.totalPending > 0,
+        hasTrackedPendingChanges: summary.tracked > 0,
+        hasPrivatePendingChanges: summary.private > 0,
+        hasPrivateOnlyPendingChanges: summary.private > 0 && summary.tracked === 0,
+    };
+};
+
+export const isSwitchBringBlockedForUnattended = (pendingChoice: "shelve" | "bring" | "cancel", profile: SwitchPendingProfile): boolean =>
+{
+    return pendingChoice === "bring" && profile.hasTrackedPendingChanges;
+};
+
+export type CanceledSwitchOutcome = {
+    kind: "canceled";
+    strategy: "cancel-with-pending";
+    branchBefore: string;
+    branchTarget: string;
+    pendingSummary: PendingSummary;
+    pendingSummaryDetailed: PendingItemSummary;
+    pendingPolicy: "cancel";
+    defaultedPolicy: boolean;
+    reason: string;
+};
+
+export const createCanceledSwitchOutcome = (
+    branchBefore: string,
+    branchTarget: string,
+    pendingSummary: PendingSummary,
+    pendingSummaryDetailed: PendingItemSummary,
+    pendingChoice: "shelve" | "bring" | "cancel",
+    defaultedPolicy: boolean,
+): CanceledSwitchOutcome | undefined =>
+{
+    if (pendingChoice !== "cancel" || pendingSummaryDetailed.totalPending === 0 || isSameBranchSpec(branchBefore, branchTarget))
+    {
+        return undefined;
+    }
+
+    return {
+        kind: "canceled",
+        strategy: "cancel-with-pending",
+        branchBefore,
+        branchTarget,
+        pendingSummary,
+        pendingSummaryDetailed,
+        pendingPolicy: "cancel",
+        defaultedPolicy,
+        reason: defaultedPolicy
+            ? "Switch canceled because pending changes were detected and the default policy is cancel unless pendingChanges is set."
+            : "Switch canceled because pending changes were detected and pendingChanges was set to cancel.",
+    };
+};
+
+export const canSwitchDirectWithPrivateOnlyPending = (
+    pendingChoice: "shelve" | "bring" | "cancel",
+    defaultedPolicy: boolean,
+    profile: SwitchPendingProfile,
+): boolean =>
+{
+    if (!profile.hasPrivateOnlyPendingChanges)
+    {
+        return false;
+    }
+
+    if (pendingChoice === "shelve" || pendingChoice === "bring")
+    {
+        return true;
+    }
+
+    return defaultedPolicy;
+};

package/src/domain/undo-contract.ts

@@ -0,0 +1,24 @@
+import type { UndoAttempt, UndoCapture } from "../execution/undo-command";
+export type { UndoAttempt, UndoCapture } from "../execution/undo-command";
+export const UNDO_COMMAND = "undo" as const;
+export const safeUndoText = (value: unknown): value is string => typeof value === "string" && value.length > 0 && value.length <= 4096 && value.trim().length > 0 && !/[\u0000-\u001f\u007f-\u009f]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(value);
+export function validUndoOperands(paths: unknown): paths is string[] {
+    if (!Array.isArray(paths) || !paths.length || paths.length > 256) return false;
+    let bytes = 0;
+    for (let index = 0; index < paths.length; index++) {
+        const path = paths[index];
+        if (!safeUndoText(path) || path.trimStart().startsWith("-")) return false;
+        bytes += Buffer.byteLength(path, "utf8");
+        if (bytes > 32768) return false;
+    }
+    return true;
+}
+export type UndoData = {
+    intendedArgv: readonly string[]; requestedOperandCount: number | null; workingDirectory: string | null;
+    attempt: UndoAttempt; capture: UndoCapture | null;
+    observedWorkspaceIdentity: null; observedUndoneItems: null;
+    verification: "unverified"; effect: "not-attempted" | "not-proven" | "uncertain";
+};
+type Header = { schemaVersion: 1; action: "undo"; provenance: { source: "plastic"; producer: "@aefree/pi-plastic"; contentTrust: "external" }; completeness: { capture: "complete" | "incomplete" | "unknown"; projection: true }; data: UndoData };
+export type UndoError = { code: "invalid_request" | "launch_failed" | "aborted" | "uncertain" | "producer_failed"; message: string };
+export type UndoReceipt = Header & ({ ok: true; outcome: "command-completed" } | { ok: false; outcome: "failed" | "uncertain"; error: UndoError });

package/src/domain/update-contract.ts

@@ -0,0 +1,16 @@
+import type { UpdateAttempt, UpdateCapture } from "../execution/update-command";
+export type { UpdateAttempt, UpdateCapture } from "../execution/update-command";
+export const UPDATE_ARGV = Object.freeze(["update", "--dontmerge", "--noinput"] as const);
+export const safeUpdateText = (value: unknown): value is string => typeof value === "string" && value.length > 0 && value.length <= 4096 && value.trim().length > 0 && !/[\u0000-\u001f\u007f-\u009f]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(value);
+export type UpdateData = {
+    intendedArgv: typeof UPDATE_ARGV; workingDirectory: string | null;
+    attempt: UpdateAttempt; capture: UpdateCapture | null;
+    observedWorkspaceIdentity: null; observedChanges: null;
+    verification: "unverified"; effect: "not-attempted" | "not-proven" | "uncertain";
+};
+type Header = { schemaVersion: 1; action: "update"; provenance: { source: "plastic"; producer: "@aefree/pi-plastic"; contentTrust: "external" }; completeness: { capture: "complete" | "incomplete" | "unknown"; projection: true }; data: UpdateData };
+export type UpdateError = { code: "invalid_request" | "launch_failed" | "aborted" | "uncertain" | "producer_failed"; message: string };
+export type UpdateReceipt = Header & (
+    { ok: true; outcome: "command-completed" } |
+    { ok: false; outcome: "failed" | "uncertain"; error: UpdateError }
+);

package/src/domain/workspace-merge-contract.ts

@@ -0,0 +1,41 @@
+import type { WorkspaceMergeAttempt, WorkspaceMergeCapture } from "../execution/workspace-merge-command";
+export type { WorkspaceMergeAttempt, WorkspaceMergeCapture } from "../execution/workspace-merge-command";
+export type MergeAction = "merge" | "finalize-merge";
+export type MergeStrategy = "auto" | "source" | "destination";
+export const safeMergeText = (v: unknown): v is string => typeof v === "string" && v.length > 0 && v.length <= 4096 && v.trim().length > 0 && !/[\u0000-\u001f\u007f-\u009f]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(v);
+export type MergeStage = { attempt: WorkspaceMergeAttempt; capture: WorkspaceMergeCapture | null; admission: "not-observed" | "unsupported" | "admitted" };
+export type WorkspaceMergeData = {
+ intendedArgv: readonly string[]; workingDirectory: string | null; requestedSource: string | null; strategy: MergeStrategy | null; cherrypicking: boolean | null; forced: boolean | null; previewRequested: boolean | null; outputFormatRequested: "text" | "json" | null;
+ apply: MergeStage; shortStatus: MergeStage; fullStatus: MergeStage; pendingReadMode: "short" | "copied-machine";
+ commandCompleted: boolean; observedWorkspaceIdentity: null; observedSourceIdentity: null; observedFinalizedMetadata: null; observedPreservation: null; observedPendingItems: null;
+ fileConflictCount: number | null; protocol: "not-observed" | "already-connected" | "file-conflict" | "apply-add" | "apply-add-copied" | "unsupported";
+ checkinReadiness: "unknown" | "blocked" | "supported-no-unresolved-signals"; verification: "unverified"; effect: "not-attempted" | "not-proven" | "uncertain";
+};
+type Header = { schemaVersion: 1; action: MergeAction; provenance: { source: "plastic"; producer: "@aefree/pi-plastic"; contentTrust: "external" }; completeness: { capture: "complete" | "incomplete" | "unknown"; projection: true }; data: WorkspaceMergeData };
+export type WorkspaceMergeReceipt = Header & ({ ok: true; outcome: "preflight" | "command-completed" } | { ok: false; outcome: "failed" | "uncertain" | "blocked"; error: { code: "invalid_request" | "launch_failed" | "aborted" | "uncertain" | "unsupported_readiness" | "conflict" | "producer_failed"; message: string } });
+export function buildWorkspaceMergeArgv(source: string, strategy: MergeStrategy, cherry: boolean, forced: boolean, token: string): string[] {
+ const result = ["merge",source,"--merge","--nointeractiveresolution","--machinereadable",`--startlineseparator=${token}S__`,`--endlineseparator=${token}E__`,`--fieldseparator=${token}F__`];
+ if(strategy === "auto") result.push("--mergetype=try"); else result.push("--mergetype=forced",strategy === "source" ? "--keepsource" : "--keepdestination",`--automaticresolution=all-${strategy === "source" ? "src" : "dst"}`);
+ if(cherry)result.push("--cherrypicking");if(forced)result.push("--forced");return result;
+}
+/** Narrow observed CM profile. Unknown records/text are not missing-conflict proof. */
+export function admitWorkspaceMergeOutput(text: string, token: string): { protocol: WorkspaceMergeData["protocol"]; fileConflictCount: number | null; copiedPaths: string[]; addedPaths: string[] } {
+ const start=token+"S__",end=token+"E__",field=token+"F__";let rest=text,count=0,conflicts=0,connected=0,adds=0; const copiedPaths:string[]=[], addedPaths:string[]=[];
+ while(rest.trim()!==""){
+  if(++count>256)return {protocol:"unsupported",fileConflictCount:null,copiedPaths:[],addedPaths:[]};const s=rest.indexOf(start),e=rest.indexOf(end,s+start.length);
+  if(s<0||e<0||rest.slice(0,s).trim()!=="")return {protocol:"unsupported",fileConflictCount:null,copiedPaths:[],addedPaths:[]};
+  const payload=rest.slice(s+start.length,e);if(payload.includes(start))return {protocol:"unsupported",fileConflictCount:null,copiedPaths:[],addedPaths:[]};const f=payload.split(field);rest=rest.slice(e+end.length);
+  if(f.length===3&&f[0]==="STATUS"&&f[1]==="ALREADY_CONNECTED"&&f[2]==="No merges detected")connected++;
+  else if(f.length===6&&f[0]==="FILE_CONFLICT"&&safeMergeText(f[1])&&f.slice(2).every(v=>/^[0-9]+$/.test(v)))conflicts++;
+  else if(f.length===3&&f[0]==="APPLY"&&f[1]==="ADD"&&safeMergeText(f[2])){adds++;addedPaths.push(f[2]);}
+  else if(f.length===2&&f[0]==="DO_COPIED"&&safeMergeText(f[1]))copiedPaths.push(f[1]);
+  else return {protocol:"unsupported",fileConflictCount:null,copiedPaths:[],addedPaths:[]};
+ }
+ if(!count||connected&&(connected!==1||count!==1)||conflicts&&(adds||copiedPaths.length)||copiedPaths.length&&copiedPaths.length!==adds)return {protocol:"unsupported",fileConflictCount:null,copiedPaths:[],addedPaths:[]};
+ return {protocol:conflicts?"file-conflict":connected?"already-connected":copiedPaths.length?"apply-add-copied":"apply-add",fileConflictCount:conflicts,copiedPaths,addedPaths};
+}
+/** Only the directly observed header-only standard status shape is admitted initially.
+ * Rich/pending/localized/merge-link status stays unknown until independently sourced. */
+export function admitCleanStandardStatus(text: string): boolean {
+ return /^[^\r\n\u0000-\u001f\u007f]+ \(cs:[0-9]+ - head\)\r?\n(?:\r?\n)*$/.test(text)&&text.startsWith("/")&&text.includes("@");
+}

package/src/execution/add-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 AddAttempt = { state: "not-attempted" | "not-started" | "started" | "unknown"; terminal: "not-observed" | "observed"; exitCode: number | null; aborted: boolean; timedOut: boolean };
+export const emptyAddAttempt = (): AddAttempt => ({ state: "not-attempted", terminal: "not-observed", exitCode: null, aborted: false, timedOut: false });
+export type AddCapture = { stdoutBytes: number; stderrBytes: number; stdoutRetainedBytes: number; stderrRetainedBytes: number; truncated: boolean; complete: boolean; validUtf8: boolean };
+export type AddCommandObservation = { attempt: AddAttempt; capture: AddCapture; 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 captureAddCommand(args: string[], workdir?: string, timeoutMs = 30000): Promise<AddCommandObservation> {
+    const attempt = emptyAddAttempt();
+    const capture: AddCapture = { stdoutBytes: 0, stderrBytes: 0, stdoutRetainedBytes: 0, stderrRetainedBytes: 0, truncated: false, complete: false, validUtf8: false };
+    const result: AddCommandObservation = { 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/branch-create-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 BranchCreateAttempt = { state: "not-attempted" | "not-started" | "started" | "unknown"; terminal: "not-observed" | "observed"; exitCode: number | null; aborted: boolean; timedOut: boolean };
+export const emptyBranchCreateAttempt = (): BranchCreateAttempt => ({ state: "not-attempted", terminal: "not-observed", exitCode: null, aborted: false, timedOut: false });
+export type BranchCreateCapture = { stdoutBytes: number; stderrBytes: number; stdoutRetainedBytes: number; stderrRetainedBytes: number; truncated: boolean; complete: boolean; validUtf8: boolean };
+export type BranchCreateCommandObservation = { attempt: BranchCreateAttempt; capture: BranchCreateCapture; 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 captureBranchCreateCommand(args: string[], workdir?: string, timeoutMs = 30000): Promise<BranchCreateCommandObservation> {
+    const attempt = emptyBranchCreateAttempt();
+    const capture: BranchCreateCapture = { stdoutBytes: 0, stderrBytes: 0, stdoutRetainedBytes: 0, stderrRetainedBytes: 0, truncated: false, complete: false, validUtf8: false };
+    const result: BranchCreateCommandObservation = { 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/branch-list-command.ts

@@ -0,0 +1,75 @@
+import { spawn } from "node:child_process";
+import type { Readable } from "node:stream";
+export const BRANCH_LIST_CAPTURE_LIMITS = { stdoutBytes: 1048576, stderrBytes: 65536, timeoutMs: 30000, records: 20000 } as const;
+import { commandExecutionStorage, getActiveAbortSignal } from "./context";
+import { getCmExecutable } from "./process";
+export class BranchListCommandError extends Error {
+    constructor(readonly code: "command_failed" | "aborted" | "capture_incomplete") { super(`Branch list read failed (${code}).`); }
+}
+
+// Branch-list-only strict byte transport. Native/default and status routes are unchanged.
+export async function runBranchListNamesCommand(args: string[], workdir?: string): Promise<Buffer> {
+    const signal = getActiveAbortSignal();
+    if (signal?.aborted) throw new BranchListCommandError("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 BranchListCommandError("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, BRANCH_LIST_CAPTURE_LIMITS.stdoutBytes);
+    const stderr = collect(child.stderr, BRANCH_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 ?? BRANCH_LIST_CAPTURE_LIMITS.timeoutMs, BRANCH_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 BranchListCommandError("aborted");
+        if (incomplete) throw new BranchListCommandError("capture_incomplete");
+        if (failed || code !== 0 || errors.length) throw new BranchListCommandError("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/checkin-command.ts

@@ -0,0 +1,116 @@
+import { spawn } from "node:child_process";
+import type { Readable } from "node:stream";
+import { commandExecutionStorage, getActiveAbortSignal } from "./context";
+import { getCmExecutable } from "./process";
+export type CheckinAttempt = { state: "not-attempted" | "not-started" | "started" | "unknown"; terminal: "not-observed" | "observed"; exitCode: number | null; aborted: boolean; timedOut: boolean };
+export type CheckinCapture = { stdoutBytes: number; stderrBytes: number; stdoutRetainedBytes: number; stderrRetainedBytes: number; truncated: boolean; complete: boolean; validUtf8: boolean };
+export const emptyCheckinAttempt = (): CheckinAttempt => ({ state: "not-attempted", terminal: "not-observed", exitCode: null, aborted: false, timedOut: false });
+export type CheckinCommandObservation = { attempt: CheckinAttempt; capture: CheckinCapture; 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 captureCheckinCommand(args: string[], workdir: string, timeoutMs = 30000): Promise<CheckinCommandObservation> {
+    if (args.length > 120 || args.reduce((n, a) => n + a.length, 0) > 32768 || Buffer.byteLength(JSON.stringify(args), "utf8") > 65536) throw new Error("Checkin argv exceeds the admitted bound.");
+    const attempt = emptyCheckinAttempt();
+    const capture: CheckinCapture = { stdoutBytes: 0, stderrBytes: 0, stdoutRetainedBytes: 0, stderrRetainedBytes: 0, truncated: false, complete: false, validUtf8: false };
+    const result: CheckinCommandObservation = { 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, 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; }
+                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 = () => { 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 : null;
+            if (!started || 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 {
+            // Preserve a BOM as evidence 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;
+    }
+}