@aefree/pi-plastic 0.7.6 → 0.8.0

package/src/operations/branch-reads.ts

@@ -0,0 +1,94 @@
+import { cmWhereEquals, getBranchLeafName, normalizeBranchSpecForComparison } from "../domain/branches";
+import { runStatusCommand, StatusCommandError } from "../execution/status-command";
+import { toStructuredResult, type OutputFormat } from "../presentation/results";
+
+export class BranchReadError extends Error {
+    constructor(readonly code: "command_failed" | "aborted" | "capture_incomplete" | "invalid_identity" | "malformed_output") {
+        super(`Branch read failed (${code}); no verified identity or existence result is available.`);
+    }
+}
+export const validBranchIdentity = (value: string): boolean => value.length > 0 && value.length <= 4096
+    && value === value.trim() && !/[\u0000-\u001f\u007f-\u009f\uFFFD]/u.test(value)
+    && !(process.platform === "win32" && value.includes("?"))
+    && !/[\uD800-\uDFFF]/u.test(value);
+const assertIdentity = (value: string): string => {
+    if (!validBranchIdentity(value)) throw new BranchReadError("invalid_identity");
+    return value;
+};
+const pathIdentity = (value: string): string => {
+    assertIdentity(value);
+    if (!/^\/(?:[^/@\\]+)(?:\/[^/@\\]+)*$/u.test(value)) throw new BranchReadError("malformed_output");
+    return value;
+};
+const read = async (args: string[], workdir?: string): Promise<string> => {
+    try {
+        const result = await runStatusCommand(args, workdir, true);
+        if (result.capture !== "complete") throw new BranchReadError("capture_incomplete");
+        return result.output;
+    } catch (error) {
+        if (error instanceof StatusCommandError) throw new BranchReadError(error.code);
+        throw error;
+    }
+};
+// Inspect every recognized changeset token, including empty/malformed ones.
+// Delimiters accommodate the live cs:N@rep:... and (cs:N - head) forms;
+// decimal/junk suffixes are part of the token, never a reusable numeric prefix.
+const statusChangesetIds = (output: string): string[] => {
+    const tokens = [...output.matchAll(/\bcs:([^\s@)]*)/giu)].map(match => match[1]);
+    if (tokens.length > 1 || tokens.some(token => !/^[0-9]+$/u.test(token))) throw new BranchReadError("malformed_output");
+    return tokens;
+};
+// Only explicit, delimited observations are reusable. Never take a whitespace
+// prefix of a br: selector or normalize an observed path into a different one.
+const statusIdentity = (output: string): string | undefined => {
+    const candidates: string[] = [];
+    for (const line of output.split(/\r?\n/).filter(line => line.trim())) {
+        // At most the explicit leading source prefix may carry a br: marker.
+        // A second selector in either path or repository text is ambiguous, not
+        // part of a fabricated spaced branch or ignorable trailing metadata.
+        const body = line.replace(/^(?:(?:branch\s*[:=]\s*|Branch\s+)(?:br:)?|br:)/iu, "");
+        if (/\bbr:|\bbranch\s*[:=]\s*(?:br:)?\//iu.test(body)) throw new BranchReadError("malformed_output");
+        if (/\bbr:.*[()]|^branch.*\(cs:/iu.test(line)) throw new BranchReadError("malformed_output");
+        const match = line.match(/^(\/[^@]+)@.+$/u) ?? line.match(/^(?:(?:branch\s*[:=]\s*|Branch\s+)(?:br:)?|br:)(\/[^@]+)(?:@.+)?$/iu);
+        if (match) candidates.push(pathIdentity(match[1]));
+        else if (/\bbr:|^branch\b|^\//iu.test(line)) throw new BranchReadError("malformed_output");
+    }
+    if (new Set(candidates).size > 1) throw new BranchReadError("malformed_output");
+    // Pending merge-link changesets describe sources, not the loaded identity.
+    // Exclude only their standard-status lines once an explicit header exists;
+    // changeset-only fallback still validates every token for ambiguity.
+    const identityContext = candidates.length > 0
+        ? output.split(/\r?\n/).filter(line => !/^    Merge from cs:[0-9]+ at /u.test(line)).join("\n")
+        : output;
+    statusChangesetIds(identityContext);
+    return candidates[0];
+};
+export type CurrentBranchObservation = { action: "current-branch"; branch: string; basis: "status" | "compact_status" | "changeset_lookup"; scope: "workspace" };
+export type BranchExistsObservation = { action: "branch-exists"; requestedBranch: string; comparisonBranch: string; scope: "workspace_repository"; qualifierVerified?: false; exists: boolean };
+export type BranchReadObservation = CurrentBranchObservation | BranchExistsObservation;
+export async function assembleCurrentBranchObservation(args: { workdir?: string }): Promise<CurrentBranchObservation> {
+    const normal = await read(["status"], args.workdir);
+    const branch = statusIdentity(normal);
+    if (branch !== undefined) return { action: "current-branch", branch, basis: "status", scope: "workspace" };
+    const compact = await read(["status", "--compact"], args.workdir);
+    const compactBranch = statusIdentity(compact);
+    if (compactBranch !== undefined) return { action: "current-branch", branch: compactBranch, basis: "compact_status", scope: "workspace" };
+    const changesets = statusChangesetIds(compact);
+    if (changesets.length !== 1) throw new BranchReadError("malformed_output");
+    const output = await read(["find", "changeset", `where changesetid=${changesets[0]}`, "--format={branch}", "--nototal"], args.workdir);
+    const rows = output.split(/\r?\n/).filter(line => line.length > 0);
+    if (rows.length !== 1) throw new BranchReadError("malformed_output");
+    return { action: "current-branch", branch: pathIdentity(rows[0]), basis: "changeset_lookup", scope: "workspace" };
+}
+export async function assembleBranchExistsObservation(args: { branch: string; workdir?: string }): Promise<BranchExistsObservation> {
+    assertIdentity(args.branch);
+    if (args.branch.includes("@") && args.branch.split("@").some(segment => segment.length === 0)) throw new BranchReadError("invalid_identity");
+    const comparisonBranch = assertIdentity(normalizeBranchSpecForComparison(args.branch));
+    if (comparisonBranch.includes("//") || comparisonBranch.endsWith("/") || comparisonBranch === "/" || /[|]/u.test(comparisonBranch)) throw new BranchReadError("invalid_identity");
+    const output = await read(["find", "branch", `where ${cmWhereEquals("name", getBranchLeafName(args.branch))}`, "--format={name}", "--nototal"], args.workdir);
+    const rows = output.split(/\r?\n/).filter(line => line.length > 0).map(pathIdentity);
+    if (new Set(rows).size !== rows.length || rows.some(row => getBranchLeafName(row) !== getBranchLeafName(comparisonBranch))) throw new BranchReadError("malformed_output");
+    return { action: "branch-exists", requestedBranch: args.branch, comparisonBranch, scope: "workspace_repository", ...(args.branch.includes("@") ? { qualifierVerified: false as const } : {}), exists: rows.some(row => row === comparisonBranch) };
+}
+export const presentCurrentBranchObservation = (observation: CurrentBranchObservation, args: { format?: OutputFormat; workdir?: string }) => toStructuredResult("current-branch", args.format ?? "text", observation.branch, { branch: observation.branch }, args.workdir);
+export const presentBranchExistsObservation = (observation: BranchExistsObservation): string => observation.exists ? "true" : "false";

package/src/operations/branches.ts

@@ -0,0 +1,111 @@
+import { assembleBranchCreateReceipt } from "./branch-create";
+import { presentBranchCreateReceipt } from "../presentation/branch-create";
+import { assembleBranchListObservation, presentBranchListObservation, branchListPayload } from "./branch-list";
+import { assembleCurrentBranchObservation, assembleBranchExistsObservation, presentCurrentBranchObservation, presentBranchExistsObservation } from "./branch-reads";
+import { getBranchLeafName, resolveBranchCreationTarget } from "../domain/branches";
+import { parsePlasticStatusBranch } from "../plastic-workspace";
+import { tool } from "../tool-definition";
+import { workdirArg } from "./arguments";
+import { assembleBranchDeleteReceipt, presentBranchDeleteReceipt } from "./branch-delete-receipt";
+import { outputFormatArg } from "../presentation/results";
+
+export const __plasticBranchInternals = {
+    getBranchLeafName,
+    parsePlasticStatusBranch,
+    resolveBranchCreationTarget,
+};
+
+// Capture enough subprocess output for diagnostics while keeping the default
+// agent-facing response intentionally small. Callers may opt into a larger
+// focused response, but never the full capture bound.
+
+export const branchCreate = tool({
+    description: "Create a hierarchical Plastic SCM branch, guarding rare top-level branch creation (cm branch create).",
+    args: {
+        branch: tool.schema.string().min(1).describe("Relative new-branch name or full hierarchical branch path. A relative name uses parent, or the current branch when parent is omitted."),
+        parent: tool.schema.string().optional().describe("Parent branch for a relative branch name. May differ from the workspace branch; Plastic uses the parent's latest changeset by default."),
+        changeset: tool.schema.string().optional().describe("Changeset used as the starting point instead of the parent branch's latest changeset."),
+        label: tool.schema.string().optional().describe("Label used as the starting point."),
+        comment: tool.schema.string().optional().describe("Optional branch comment."),
+        commentsFile: tool.schema.string().optional().describe("File path containing the branch comment."),
+        allowRootBranch: tool.schema.boolean().optional().describe("Allow intentional top-level branch creation such as /<new-branch>. Defaults to false."),
+        workdir: workdirArg,
+    },
+    async execute(args)
+    {
+        const dto = await assembleBranchCreateReceipt(args);
+        if (!dto.ok && dto.error.stage === "input") throw new Error(dto.error.message);
+        return presentBranchCreateReceipt(dto);
+    },
+});
+
+export const currentBranch = tool({
+    description: "Get the current Plastic SCM branch from workspace status output.",
+    args: {
+        format: outputFormatArg,
+        workdir: workdirArg,
+    },
+    async execute(args)
+    {
+        return presentCurrentBranchObservation(await assembleCurrentBranchObservation(args), args);
+    },
+});
+
+export const branchList = tool({
+    description: "List Plastic SCM branches using cm find branch with optional filters.",
+    args: {
+        source: tool.schema.enum(["native", "names"]).optional().describe("Observation source. Defaults to native table; names selects strict UTF-8 reusable branch rows."),
+        format: outputFormatArg,
+        maxItems: tool.schema.number().int().min(1).max(500).optional().describe("Canonical projection rows (default 100); independent of the CLI query limit. Native rows are unavailable."),
+        nameLike: tool.schema.string().optional().describe("Filter by branch leaf-name pattern (supports % wildcard); bounded to 4096 code units."),
+        parent: tool.schema.string().optional().describe("Requested parent branch filter, bounded to 4096 code units; repository qualifiers are not verified."),
+        owner: tool.schema.string().optional().describe("Filter by branch owner; bounded to 4096 code units."),
+        includeHidden: tool.schema.boolean().optional().describe("Legacy hidden query policy. True is unsupported for names and rejected before execution."),
+        limit: tool.schema.number().int().min(1).max(Number.MAX_SAFE_INTEGER).optional().describe("CLI query row limit; not a repository total or projection limit."),
+        orderBy: tool.schema.enum(["date", "branchname"]).optional().describe("Sort field for branch queries."),
+        descending: tool.schema.boolean().optional().describe("Sort descending when true."),
+        workdir: workdirArg,
+    },
+    async execute(args)
+    {
+        const observation = await assembleBranchListObservation(args);
+        // Enforce compact projection bounds for canonical and JSON core calls;
+        // default native text remains the legacy table/string route.
+        if (args.source === "names" || args.format === "json") {
+            const dto = branchListPayload(observation);
+            if (args.format === "json") return JSON.stringify(dto);
+        }
+        return presentBranchListObservation(observation);
+    },
+});
+
+export const branchExists = tool({
+    description: "Check whether a branch exists using cm find branch.",
+    args: {
+        branch: tool.schema.string().min(1).describe("Branch name to check."),
+        workdir: workdirArg,
+    },
+    async execute(args)
+    {
+        return presentBranchExistsObservation(await assembleBranchExistsObservation(args));
+    },
+});
+
+export const branchDelete = tool({
+    description: "Delete a Plastic SCM branch (cm branch delete).",
+    args: {
+        branch: tool.schema.string().min(1).describe("Branch spec to delete."),
+        deleteChangesets: tool.schema.boolean().optional().describe("Delete changesets inside the branch when required; completion does not prove history deletion."),
+        preflight: tool.schema.boolean().optional().describe("Command-only preview, no CLI or branch/readiness analysis."),
+        format: outputFormatArg,
+        workdir: workdirArg,
+    },
+    async execute(args)
+    {
+        const request = Object.freeze({ ...args });
+        const dto = await assembleBranchDeleteReceipt(request);
+        const result = presentBranchDeleteReceipt(dto);
+        if (!dto.ok && request.preflight !== true) throw new Error(result);
+        return request.format === "json" ? JSON.stringify(dto) : result;
+    },
+});

package/src/operations/checkin-receipt.ts

@@ -0,0 +1,140 @@
+import { randomBytes } from "node:crypto";
+import { buildFallbackScopePaths } from "../domain/paths";
+import { summarizePendingItems, resolveCheckinPaths, filterPendingItemsByScope, selectPrivatePathsForAutoAdd, type PendingItem } from "../domain/pending";
+import { captureCheckinCommand, type CheckinCommandObservation } from "../execution/checkin-command";
+import { checkinSafeComment, checkinSafeValue, parseCheckinEvidence, parseCheckinPending, type CheckinData, type CheckinReceipt, type CheckinRequest, type CheckinStep, type CheckinSummary } from "../domain/checkin-contract";
+const pendingArgv = ["status", "--machinereadable", "--includeRevId", "--fieldseparator=\x1f"];
+const summary = (items: PendingItem[], cwd: string): CheckinSummary => { const { privatePaths: _, ...s } = summarizePendingItems(items, cwd); return s; };
+const normal = (o: CheckinCommandObservation) => o.capture.complete && !o.failed && o.attempt.state === "started" && o.attempt.terminal === "observed" && o.attempt.exitCode !== null && !o.attempt.aborted && !o.attempt.timedOut;
+const success = (o: CheckinCommandObservation) => normal(o) && o.attempt.exitCode === 0 && o.capture.stderrBytes === 0;
+function validateRequest(input: unknown): asserts input is CheckinRequest {
+    if (!input || typeof input !== "object" || Array.isArray(input)) throw Error("Invalid bounded checkin input.");
+    const r = input as Record<string, unknown>;
+    if (!checkinSafeComment(r.message) || !r.message.trim() || r.workdir !== undefined && !checkinSafeValue(r.workdir) || r.format !== undefined && !["text", "json"].includes(r.format as string)) throw Error("Invalid bounded checkin input.");
+    for (const k of ["applyChanged", "includePrivate", "includeAll", "updateAfter", "preflight"]) if (r[k] !== undefined && typeof r[k] !== "boolean") throw Error("Invalid checkin option.");
+    if (r.paths !== undefined && (!Array.isArray(r.paths) || r.paths.length > 100 || !r.paths.every(p => checkinSafeValue(p) && p.trim() && p !== "-" && !p.startsWith("-")))) throw Error("Invalid bounded checkin paths.");
+    const values = [r.message, r.workdir ?? "", ...(r.paths as string[] ?? [])] as string[];
+    if (values.reduce((n, s) => n + s.length, 0) > 16384 || Buffer.byteLength(JSON.stringify(values), "utf8") > 32768) throw Error("Checkin input exceeds aggregate bound.");
+}
+export async function assembleCheckinReceipt(input: unknown): Promise<CheckinReceipt> {
+    const data: CheckinData = { sourceAdmission: "windows-cm11.0.16.10371-observed", requestedPaths: [], includedPaths: [], fallbackPaths: [], excludedPaths: [], privateAddPaths: [], blockedPrivatePaths: [], itemEvents: [], observedChangesets: [], command: null, steps: [], autoEnabledApplyChanged: false, usedFallbackRetry: false, usedPrivateAutoAddRecovery: false, pendingBefore: null, pendingAfter: null, wouldRun: false, omittedReferences: 0, scopeExhaustion: "unverified", branchHead: "unverified", serverAliasEquivalence: "unverified", xlinkEffects: "unverified", mergeLinkIdentity: "unverified" };
+    let created: CheckinReceipt["data"]["createdChangeset"] = null;
+    const finish = (outcome: CheckinReceipt["outcome"], code = "uncertain", stage: "input" | "pending" | "checkin" | "producer" = "checkin", message = "Checkin evidence is uncertain; inspect workspace/repository state before deciding whether to retry."): CheckinReceipt => {
+        const effects = data.steps.filter(s => s.operation !== "status").map(s => s.effect);
+        const effect = created ? "changeset-created" : effects.includes("uncertain") ? "uncertain" : effects.includes("command-completed") ? "command-completed" : "not-attempted";
+        // Full evidence classification is complete before any whole-reference projection.
+        let remaining = 100;
+        const project = <T>(a: T[]): T[] => { const n = Math.min(a.length, remaining); remaining -= n; data.omittedReferences += a.length - n; return a.slice(0, n); };
+        data.requestedPaths = project(data.requestedPaths); data.includedPaths = project(data.includedPaths); data.fallbackPaths = project(data.fallbackPaths); data.excludedPaths = project(data.excludedPaths); data.privateAddPaths = project(data.privateAddPaths); data.blockedPrivatePaths = project(data.blockedPrivatePaths); data.itemEvents = project(data.itemEvents); data.observedChangesets = project(data.observedChangesets);
+        if (data.command) { if (data.command.length > remaining) { data.omittedReferences += data.command.length; data.command = null; } else remaining -= data.command.length; }
+        const ok = outcome === "preflight" || outcome === "completed";
+        const dto = { schemaVersion: 1, action: "checkin", provenance: { source: "plastic", producer: "@aefree/pi-plastic", contentTrust: "external" }, ok, outcome, completeness: { capture: data.steps.length ? data.steps.every(s => s.capture.complete) ? "complete" : "incomplete" : "unknown", projection: data.omittedReferences === 0 }, data: { ...data, effect, createdChangeset: created }, ...(!ok ? { error: { code, stage, message } } : {}) } as CheckinReceipt;
+        if (Buffer.byteLength(JSON.stringify(dto), "utf8") > 131072) {
+            const d = dto.data;
+            for (const key of ["requestedPaths", "includedPaths", "fallbackPaths", "excludedPaths", "privateAddPaths", "blockedPrivatePaths", "itemEvents", "observedChangesets"] as const) { d.omittedReferences += d[key].length; d[key] = [] as any; }
+            if (d.command) { d.omittedReferences += d.command.length; d.command = null; } dto.completeness.projection = false;
+        }
+        return dto;
+    };
+    let stage: "input" | "pending" | "checkin" | "producer" = "input";
+    let dispatchEntered = false;
+    try {
+        validateRequest(input);
+        if (input.updateAfter) return finish("failed", "UNATTENDED_UPDATE_AFTER_BLOCKED", "input", "updateAfter is disabled for unattended safety. Run plastic_update() then plastic_merge(...) with an explicit conflict policy.");
+        const cwd = input.workdir ?? process.cwd();
+        if (!checkinSafeValue(cwd)) return finish("failed", "invalid_request", "input", "Invalid bounded workdir.");
+        if (process.platform !== "win32") return finish("unsupported", "source_platform_unadmitted", "pending", "Checkin sources are admitted only on the observed Windows client.");
+        data.requestedPaths = input.paths ?? [];
+        const record = async (name: CheckinStep["name"], argv: string[]) => {
+            if (data.steps.length >= 8) throw Error("Step bound exceeded.");
+            dispatchEntered = true;
+            const mutation = argv[0] !== "status";
+            const s: CheckinStep = { name, operation: argv[0] as CheckinStep["operation"], attempt: { state: "unknown", terminal: "not-observed", exitCode: null, aborted: false, timedOut: false }, capture: { stdoutBytes: 0, stderrBytes: 0, stdoutRetainedBytes: 0, stderrRetainedBytes: 0, truncated: false, complete: false, validUtf8: false }, effect: mutation ? "uncertain" : "not-attempted", evidence: "unadmitted", records: 0, summary: null, changeset: null };
+            data.steps.push(s);
+            const o = await captureCheckinCommand(argv, cwd);
+            s.attempt = o.attempt; s.capture = o.capture;
+            if (mutation && ["not-started", "not-attempted"].includes(o.attempt.state)) s.effect = "not-attempted";
+            return { o, s };
+        };
+        const read = async (name: "pending-before" | "pending-recovery" | "pending-after") => {
+            const { o, s } = await record(name, pendingArgv), p = parseCheckinPending(o.stdout ?? "", cwd);
+            s.records = p.records;
+            if (success(o) && p.admitted) { s.evidence = "admitted"; s.effect = "read-observed"; s.summary = summary(p.items, cwd); return p; }
+            return null;
+        };
+        stage = "pending";
+        const before = await read("pending-before");
+        if (!before) return finish("unsupported", "pending_source_unadmitted", "pending", "Pending selection could not be admitted; no mutation was dispatched.");
+        data.pendingBefore = summary(before.items, cwd);
+        let includedAbsolute: string[] = [], scoped = before.items, apply = input.applyChanged ?? false;
+        if (input.paths?.length) {
+            const r = resolveCheckinPaths(input.paths, before.items, cwd);
+            data.includedPaths = r.includedPaths; data.fallbackPaths = r.fallbackPaths; data.excludedPaths = r.excludedPaths; includedAbsolute = r.includedAbsolutePaths;
+            data.autoEnabledApplyChanged = r.shouldApplyChanged && !apply; apply ||= r.shouldApplyChanged;
+            scoped = filterPendingItemsByScope(before.items, includedAbsolute);
+            if (!data.includedPaths.length) return finish("failed", "NO_PENDING_PATHS", "pending", "None of the provided checkin paths have admitted pending changes.");
+        }
+        const nonce = randomBytes(16).toString("hex"), seps = { start: `__PI_CI_START_${nonce}__`, end: `__PI_CI_END_${nonce}__`, field: `__PI_CI_FIELD_${nonce}__` };
+        const command = (paths: string[], force: boolean) => ["checkin", `-c=${input.message}`, ...(input.includeAll ? ["--all"] : []), ...(force ? ["--applychanged"] : []), ...(input.includePrivate ? ["--private"] : []), ...paths, "--machinereadable", `--startlineseparator=${seps.start}`, `--endlineseparator=${seps.end}`, `--fieldseparator=${seps.field}`];
+        const initial = command(data.includedPaths, apply); data.command = ["cm", ...initial]; data.wouldRun = true;
+        if (input.preflight) return finish("preflight");
+        const attempt = async (name: "initial-checkin" | "private-retry" | "fallback-checkin", argv: string[]) => {
+            const { o, s } = await record(name, argv), p = parseCheckinEvidence(o.stdout ?? "", seps); s.records = p.records;
+            const admitted = p.admitted && p.changesets.every(c => c.repository === before.repository);
+            if (admitted && normal(o)) {
+                s.evidence = "admitted";
+                data.itemEvents.push(...p.events); data.observedChangesets.push(...p.changesets);
+            }
+            if (success(o) && admitted && p.changesets.length === 1) { created = p.changesets[0]; s.changeset = created; s.effect = "changeset-created"; }
+            // Only genuine complete native failure without a created record may drive the existing recovery policy.
+            const retryEligible = normal(o) && admitted && o.attempt.exitCode !== 0 && p.changesets.length === 0;
+            return { completed: !!s.changeset, retryEligible, message: retryEligible ? o.stderr ?? "" : "" };
+        };
+        stage = "checkin";
+        let result = await attempt("initial-checkin", initial);
+        if (!result.completed && !result.retryEligible) return finish("uncertain");
+        if (!result.completed && /checkin operation cannot be started because there is a merge in progress|finish it before checkin|in progress merge/i.test(result.message)) {
+            await record("merge-diagnostic", ["status"]);
+            return finish("uncertain", "merge_in_progress", "checkin", "Checkin blocked by a merge in progress. Resolve files and use plastic_finalizeMerge(source=<original source>, strategy=destination) only when that conflict policy is intentional, then inspect before retrying.");
+        }
+        const scopedSummary = summary(scoped, cwd), noChanges = (m: string) => /no changes in the workspace/i.test(m);
+        if (!result.completed && noChanges(result.message) && !input.includePrivate && scopedSummary.private > 0 && scopedSummary.tracked === 0 && (input.includeAll || data.requestedPaths.length)) {
+            const selection = selectPrivatePathsForAutoAdd(scoped, includedAbsolute, cwd); data.blockedPrivatePaths = selection.blockedPaths;
+            if (selection.candidatePaths.length) {
+                const { o, s } = await record("private-add", ["add", ...selection.candidatePaths]);
+                data.privateAddPaths = selection.candidatePaths;
+                if (!normal(o) || o.attempt.exitCode !== 0) return finish("uncertain", "private_add_uncertain");
+                s.effect = "command-completed"; data.usedPrivateAutoAddRecovery = true;
+                result = await attempt("private-retry", initial);
+                if (!result.completed && !result.retryEligible) return finish("uncertain");
+            } else if (selection.blockedPaths.length) return finish("uncertain", "sensitive_private_paths", "checkin", "Only private items matched sensitive filters. Use plastic_add(paths=[...]) with explicit safe paths or includePrivate=true only when intentional.");
+        }
+        if (!result.completed && noChanges(result.message) && !input.includePrivate && scopedSummary.private > 0 && scopedSummary.tracked === 0 && !input.includeAll && !data.requestedPaths.length) return finish("uncertain", "private_items_ineligible", "checkin", "Only private items were pending without includeAll/includePrivate. Add expected files explicitly or use includePrivate=true only when intentional.");
+        if (!result.completed && noChanges(result.message) && scopedSummary.tracked > 0) {
+            const recovery = await read("pending-recovery");
+            if (recovery) data.pendingAfter = summary(recovery.items, cwd);
+            // Observation failure cannot mean clean; even genuinely empty pending cannot prove this checkin completed.
+            return finish("uncertain", recovery ? "no_changes_unverified" : "pending_recovery_failed");
+        }
+        if (!result.completed && input.paths?.length && /is not changed in current workspace|none of the provided checkin paths/i.test(result.message)) {
+            const fallback = data.fallbackPaths.length ? data.fallbackPaths : buildFallbackScopePaths(includedAbsolute, cwd), argv = command(fallback, true);
+            if (fallback.length && argv.join("\0") !== initial.join("\0")) {
+                data.usedFallbackRetry = true; data.fallbackPaths = fallback;
+                result = await attempt("fallback-checkin", argv);
+            }
+        }
+        if (!result.completed) return finish("uncertain");
+        const after = await read("pending-after");
+        if (after) data.pendingAfter = summary(after.items, cwd);
+        // Created identity proof is independent of a later pending-read failure.
+        return finish("completed");
+    } catch {
+        if (stage === "input") return finish("failed", "invalid_request", "input", "Invalid bounded checkin request.");
+        if (dispatchEntered && stage === "checkin") return finish("uncertain", "producer_failed", "producer");
+        return finish("failed", "pending_read_failed", "pending", "Pending read could not be completed; no mutation was dispatched.");
+    }
+}
+
+export { presentCheckinReceipt } from "../presentation/checkin-results";
+export { checkinSafeValue, parseCheckinChangeset } from "../domain/checkin-contract";
+export type { CheckinReceipt } from "../domain/checkin-contract";

package/src/operations/checkin.ts

@@ -0,0 +1,102 @@
+import { assembleCheckinReceipt } from "./checkin-receipt";
+import { presentCheckinReceipt } from "../presentation/checkin-results";
+import { toPathComparisonKeyFromAbsolutePath, isSameFilesystemDevice, buildFallbackScopePaths } from "../domain/paths";
+import { inferPendingItemKind, parseMachineReadablePendingItems, summarizePendingItems, getSensitivePrivatePathReason, selectPrivatePathsForAutoAdd, filterPendingItemsByScope, resolveCheckinPaths } from "../domain/pending";
+import { isRevisionNotFoundError, normalizeDiffFileRevisionSpec, resolveDiffFileRevision, isUnscopedDiffRevisionSpec, extractBranchSelectorFromRevision, extractBranchNameFromSelector } from "../domain/revisions";
+import { runCmRaw } from "../execution/cm";
+import { analyzeMergeStatusOutput } from "../domain/merge-output";
+import { tool } from "../tool-definition";
+import { outputFormatArg } from "../presentation/results";
+import { workdirArg } from "./arguments";
+
+export const shouldRetryCheckinWithFallbackScope = (errorMessage: string): boolean =>
+{
+    const normalized = errorMessage.toLowerCase();
+    return normalized.includes("is not changed in current workspace")
+        || normalized.includes("none of the provided checkin paths have pending changes")
+        || normalized.includes("is not changed in current workspace.")
+        || normalized.includes("none of the provided checkin paths");
+};
+
+export const isNoChangesWorkspaceCheckinError = (errorMessage: string): boolean =>
+{
+    const normalized = errorMessage.toLowerCase();
+    return normalized.includes("there are no changes in the workspace")
+        || normalized.includes("no changes in the workspace");
+};
+
+export const __plasticCheckinInternals = {
+    // Optional policy injection makes path-case behavior deterministic in focused tests.
+    toPathComparisonKeyFromAbsolutePath,
+    isSameFilesystemDevice,
+    inferPendingItemKind,
+    parseMachineReadablePendingItems,
+    summarizePendingItems,
+    getSensitivePrivatePathReason,
+    selectPrivatePathsForAutoAdd,
+    filterPendingItemsByScope,
+    resolveCheckinPaths,
+    buildFallbackScopePaths,
+    isNoChangesWorkspaceCheckinError,
+    isRevisionNotFoundError,
+    normalizeDiffFileRevisionSpec,
+    resolveDiffFileRevision,
+    isUnscopedDiffRevisionSpec,
+    extractBranchSelectorFromRevision,
+    extractBranchNameFromSelector,
+};
+
+export const isMergeInProgressCheckinError = (message: string): boolean =>
+{
+    return /checkin operation cannot be started because there is a merge in progress|finish it before checkin|in progress merge/i.test(message);
+};
+
+export const buildMergeInProgressCheckinMessage = async (originalMessage: string, workdir?: string): Promise<string> =>
+{
+    const statusOutput = await runCmRaw(["status"], workdir).catch(() => "");
+    const mergeState = analyzeMergeStatusOutput(statusOutput);
+    const lines: string[] = [
+        "Checkin blocked: Plastic still has a merge in progress.",
+        originalMessage.trim(),
+    ];
+
+    if (mergeState.pendingMergeLinks.length > 0)
+    {
+        lines.push("", "Pending merge links:");
+        for (const link of mergeState.pendingMergeLinks.slice(0, 10))
+        {
+            lines.push(`- ${link}`);
+        }
+    }
+
+    lines.push(
+        "",
+        "Next steps:",
+        "- If files still need manual work, resolve and validate them first.",
+        "- If files are already resolved and validated, run plastic_finalizeMerge(source=<original source>, strategy=destination) to finalize Plastic merge metadata, then retry plastic_checkin.",
+        "- Use strategy=source/destination only when that conflict policy is intentional.",
+    );
+
+    return lines.join("\n");
+};
+
+export const checkin = tool({
+    description: "Check in pending changes with a required comment (cm checkin -c=...).",
+    args: {
+        message: tool.schema.string().min(1).describe("Changeset comment."),
+        paths: tool.schema.array(tool.schema.string()).optional().describe("Optional paths to check in."),
+        applyChanged: tool.schema.boolean().optional().describe("Include changed items not checked out."),
+        includePrivate: tool.schema.boolean().optional().describe("Include private items."),
+        includeAll: tool.schema.boolean().optional().describe("Include changed, moved, and deleted items."),
+        updateAfter: tool.schema.boolean().optional().describe("Deprecated in unattended mode. Blocked because checkin --update can trigger interactive update-merge."),
+        preflight: tool.schema.boolean().optional().describe("Preview command and included paths without executing checkin."),
+        format: outputFormatArg,
+        workdir: workdirArg,
+    },
+    async execute(args)
+    {
+        const dto = await assembleCheckinReceipt(args);
+        if (!dto.ok && !args.preflight) throw new Error(dto.error.message);
+        return presentCheckinReceipt(dto, args.format);
+    },
+});

package/src/operations/closeout-receipt.ts

@@ -0,0 +1,74 @@
+import { resolve } from "node:path";
+import { parseSwitchTarget, parseSwitchLoadedBranch, compareSwitchTarget, parseSwitchPending, switchPendingArgv, safeSwitchValue } from "../domain/switch-contract";
+import { checkinSafeComment, checkinSafeValue } from "../domain/checkin-contract";
+import { admitCleanStandardStatus } from "../domain/workspace-merge-contract";
+import { parseCopiedPending } from "../domain/copied-merge";
+import { cmWhereEquals } from "../domain/branches";
+import { buildCloseoutParentArgv, CLOSEOUT_STAGE_NAMES, closeoutChildEffect, closeoutCaptures, type CloseoutData, type CloseoutReceipt, type CloseoutRequest, type CloseoutStageName, type CloseoutRead, type CloseoutStage } from "../domain/closeout-contract";
+import { captureWorkspaceMergeCommand, emptyWorkspaceMergeAttempt } from "../execution/workspace-merge-command";
+import { assembleSwitchReceipt } from "./switch-receipt";
+import { assembleUpdateReceipt } from "./update-receipt";
+import { assembleWorkspaceMergeReceipt } from "./workspace-merge-receipt";
+import { assembleCheckinReceipt } from "./checkin-receipt";
+export { presentCloseoutReceipt } from "../presentation/closeout-results";
+export { CLOSEOUT_STAGE_NAMES, CLOSEOUT_DTO_BYTES, closeoutChildEffect, closeoutCaptures } from "../domain/closeout-contract";
+export type { CloseoutReceipt, CloseoutStage, CloseoutRead } from "../domain/closeout-contract";
+export { compareSwitchTarget, parseSwitchTarget, safeSwitchValue, switchPendingArgv } from "../domain/switch-contract";
+export { checkinSafeComment, checkinSafeValue } from "../domain/checkin-contract";
+export { cmWhereEquals } from "../domain/branches";
+export { buildCloseoutParentArgv } from "../domain/closeout-contract";
+export function emptyCloseoutData(): CloseoutData { return {requested:null,sourceBranch:null,targetBranch:null,targetSource:"unresolved",checkinMessage:null,stages:[],unattemptedStages:[...CLOSEOUT_STAGE_NAMES],unobservedChild:null,createdChangeset:null,pendingAfter:null,targetVerification:"unverified",serverAliasEquivalence:"unverified",sourceLink:"unverified",branchHead:"unverified",exclusiveScope:"unverified",rollback:"not-proven",effect:"not-attempted"}; }
+function admitRequest(input:unknown):asserts input is CloseoutRequest { if(!input||typeof input!=="object"||Array.isArray(input))throw Error();const r=input as Record<string,unknown>;if(Object.keys(r).some(k=>!["source","target","message","cardRef","strategy","updateTarget","includePrivate","preflight","format","workdir"].includes(k)))throw Error();for(const k of ["source","target"])if(r[k]!==undefined&&(!safeSwitchValue(r[k])||!parseSwitchTarget(r[k])))throw Error();if(r.message!==undefined&&!checkinSafeComment(r.message))throw Error();if(r.cardRef!==undefined&&!checkinSafeValue(r.cardRef))throw Error();if(r.workdir!==undefined&&!safeSwitchValue(r.workdir))throw Error();if(r.strategy!==undefined&&!["auto","source","destination"].includes(r.strategy as string)||r.format!==undefined&&!["text","json"].includes(r.format as string))throw Error();for(const k of ["updateTarget","includePrivate","preflight"])if(r[k]!==undefined&&typeof r[k]!=="boolean")throw Error();if(Buffer.byteLength(JSON.stringify(r),"utf8")>32768)throw Error(); }
+export async function assembleCloseoutReceipt(input:unknown):Promise<CloseoutReceipt> {
+ const data=emptyCloseoutData();let stage:"input"|CloseoutStageName|"producer"="input";let childEntered=false;
+ const finish=(outcome:CloseoutReceipt["outcome"],code:Extract<CloseoutReceipt,{ok:false}>["error"]["code"]="observation_failed",message="Closeout paused; inspect earlier effects before deciding whether to retry."):CloseoutReceipt=>{
+  const effects=data.stages.map(closeoutChildEffect);data.effect=data.createdChangeset?"changeset-created":effects.includes("uncertain")||childEntered?"uncertain":effects.includes("command-completed")?"command-completed":"not-attempted";
+  const captures=closeoutCaptures(data.stages),projection=data.stages.every(s=>s.kind==="read"||s.result.completeness.projection);
+  const ok=outcome==="completed"||outcome==="preflight";const actual=!ok&&data.effect!=="not-attempted"?"uncertain":outcome;
+  return {schemaVersion:1,action:"merge-to-branch",provenance:{source:"plastic",producer:"@aefree/pi-plastic",contentTrust:"external"},completeness:{capture:!captures.length?"unknown":!data.unobservedChild&&data.stages.every(s=>s.kind!=="read"||s.result.capture!==null)&&captures.every(c=>c.complete)?"complete":"incomplete",projection},data,ok,outcome:actual,...(!ok?{error:{code,stage,message}}:{})} as CloseoutReceipt;
+ };
+ const push=(s:CloseoutStage)=>{if(data.stages.length>=16)throw Error();data.stages.push(s);data.unattemptedStages=data.unattemptedStages.filter(n=>n!==s.name);};
+ const read=async(name:CloseoutStageName,argv:string[])=>{stage=name;const s:CloseoutRead={argv:[...argv],attempt:{...emptyWorkspaceMergeAttempt(),state:"unknown"},capture:null,admission:"unsupported",branch:null,parentPath:null,emptyParentResult:false,summary:null};push({name,kind:"read",result:s});const o=await captureWorkspaceMergeCommand([...argv],data.requested!.workdir);s.attempt=o.attempt;s.capture=o.capture;const success=o.capture.complete&&!o.failed&&o.attempt.state==="started"&&o.attempt.terminal==="observed"&&o.attempt.exitCode===0&&!o.attempt.aborted&&!o.attempt.timedOut&&o.stderr===""&&o.stdout!==null;return {s,o,success};};
+ const loaded=async(name:CloseoutStageName,verify=false)=>{const {s,o,success}=await read(name,["status"]);if(success){s.branch=parseSwitchLoadedBranch(o.stdout!);if(s.branch)s.admission="admitted";}if(!s.branch)return false;if(verify){data.targetVerification=compareSwitchTarget(s.branch,data.targetBranch!);if(data.targetVerification==="unverified")return false;}return true;};
+ const pending=async(name:"pending-before"|"pending-final")=>{const {s,o,success}=await read(name,[...switchPendingArgv]);if(success){const p=parseSwitchPending(o.stdout!,data.requested!.workdir);if(p.summary){s.admission="admitted";s.summary=p.summary;}}return s.summary;};
+ try{
+  const submitted=input&&typeof input==="object"&&!Array.isArray(input)?Object.freeze({...input}):input;admitRequest(submitted);const cwd=submitted.workdir??process.cwd();if(!safeSwitchValue(cwd)||!safeSwitchValue(resolve(cwd)))return finish("failed","invalid_request","Closeout needs a bounded workdir.");data.requested={source:submitted.source??null,target:submitted.target??null,message:submitted.message??null,cardRef:submitted.cardRef??null,strategy:submitted.strategy??"auto",updateTarget:submitted.updateTarget??true,includePrivate:submitted.includePrivate??false,preflight:submitted.preflight??false,outputFormat:submitted.format??"text",workdir:cwd};
+  if(process.platform!=="win32")return finish("failed","unsupported_source","Closeout source is admitted only on observed Windows/client configuration.");
+  if(!await loaded("loaded-before"))return finish("failed");const start=(data.stages[0] as Extract<CloseoutStage,{kind:"read"}>).result.branch!;data.sourceBranch=submitted.source??start.branch;
+  const source=parseSwitchTarget(data.sourceBranch)!;const inScope=(spec:string)=>{const t=parseSwitchTarget(spec)!;return t.repository===null||t.repository===start.repository&&t.server===start.server;};
+  if(!inScope(data.sourceBranch)||submitted.target!==undefined&&!inScope(submitted.target))return finish("failed","target_unverified","Qualified branch repository/server spelling differs from the observed workspace; alias equivalence is unverified. No target mutation permitted.");
+  if(submitted.target!==undefined){data.targetBranch=submitted.target;data.targetSource="explicit";}
+  else{
+   const {s,o,success}=await read("parent",buildCloseoutParentArgv(data.sourceBranch));if(!success)return finish("failed");
+   const lines=o.stdout!.split(/\r?\n/);if(lines.at(-1)==="")lines.pop();
+   if(!lines.length){s.admission="admitted";s.emptyParentResult=true;return finish("failed","observation_failed","Parent query returned no admitted matching branch; pass an explicit target.");}
+   if(lines.length!==1)return finish("failed","observation_failed","Parent leaf query is ambiguous or malformed; pass an explicit target.");
+   const f=lines[0].split("|"),expectedParent=source.branch.slice(0,source.branch.lastIndexOf("/"));
+   if(f.length!==2||f[0]!==source.branch||!parseSwitchTarget(f[0])||!f[1]||f[1]!==expectedParent||!parseSwitchTarget(f[1])||parseSwitchTarget(f[1])!.repository!==null)return finish("failed","observation_failed","Parent read did not admit one matching full branch and direct parent path; pass an explicit target.");
+   s.parentPath=f[1];s.admission="admitted";const target=source.repository===null?f[1]:`${f[1]}@${source.repository}@${source.server}`;
+   if(!parseSwitchTarget(target))return finish("failed","invalid_request","Derived target is outside the bounded branch admission; pass a bounded explicit target.");data.targetBranch=target;data.targetSource="parent-read";
+  }
+  if(source.branch===parseSwitchTarget(data.targetBranch!)!.branch)return finish("failed","invalid_request","Refusing a same-branch closeout within the admitted workspace scope.");
+  const cardLine=submitted.cardRef?.trim()?`\n\n${submitted.cardRef.trim()}`:"";data.checkinMessage=submitted.message?.trim()?submitted.message:`Merge ${data.sourceBranch} into ${data.targetBranch}${cardLine}`;
+  // Reuse child comment admission before any target mutation.
+  if(!checkinSafeComment(data.checkinMessage)||[data.checkinMessage,cwd].reduce((n,s)=>n+s.length,0)>16384||Buffer.byteLength(JSON.stringify([data.checkinMessage,cwd]),"utf8")>32768)return finish("failed","invalid_request","Derived checkin message is outside the existing child admission; supply an admitted explicit message before any target mutation.");
+  const before=await pending("pending-before");if(!before)return finish("failed");data.targetVerification=compareSwitchTarget(start,data.targetBranch!);
+  if(data.requested.preflight)return finish("preflight");
+  if(data.targetVerification==="unverified"&&before.totalPending>0)return finish("blocked","policy_blocked","Pending changes block switching under the unchanged cancel policy; no target mutation permitted.");
+  stage="switch";childEntered=true;const switched=await assembleSwitchReceipt({branch:data.targetBranch!,pendingChanges:"cancel",workdir:cwd});push({name:"switch",kind:"switch",result:switched});childEntered=false;if(!switched.ok)return finish("failed","child_failed");
+  if(!await loaded("loaded-after-switch",true))return finish("failed","target_unverified");
+  if(data.requested.updateTarget){stage="update";childEntered=true;const updated=await assembleUpdateReceipt({workdir:cwd});push({name:"update",kind:"update",result:updated});childEntered=false;if(!updated.ok)return finish("failed","child_failed");}
+  if(!await loaded("loaded-before-merge",true))return finish("failed","target_unverified");
+  stage="merge";childEntered=true;const merged=await assembleWorkspaceMergeReceipt("merge",{source:data.sourceBranch!,strategy:data.requested.strategy,workdir:cwd});push({name:"merge",kind:"merge",result:merged});childEntered=false;if(!merged.ok)return finish("failed","child_failed");
+  const copiedReady=merged.data.protocol==="apply-add-copied";
+  const ready=await read("readiness",copiedReady?[...switchPendingArgv]:["status"]);if(!ready.success||ready.o.stderr!==""||!(copiedReady?!!parseCopiedPending(ready.o.stdout!,cwd):admitCleanStandardStatus(ready.o.stdout!)))return finish("failed","observation_failed","Independent post-merge readiness is outside the admitted profile; no checkin permitted. Prior effects remain possible.");ready.s.admission="admitted";
+  if(!await loaded("loaded-before-checkin",true))return finish("failed","target_unverified");
+  const checkinArgs={message:data.checkinMessage,includeAll:true,includePrivate:data.requested.includePrivate,workdir:cwd};
+  stage="checkin-preflight";childEntered=true;const preview=await assembleCheckinReceipt({...checkinArgs,preflight:true});push({name:"checkin-preflight",kind:"checkin",result:preview});childEntered=false;if(!preview.ok)return finish("failed","child_failed");
+  stage="checkin";childEntered=true;const checked=await assembleCheckinReceipt(checkinArgs);push({name:"checkin",kind:"checkin",result:checked});childEntered=false;data.createdChangeset=checked.data.createdChangeset;if(!checked.ok)return finish("failed","child_failed");
+  if(!await loaded("loaded-final",true))return finish("failed","target_unverified");
+  const final=(data.stages.at(-1)! as Extract<CloseoutStage,{kind:"read"}>).result.branch!;
+  if(!data.createdChangeset||data.createdChangeset.branch!==final.branch||data.createdChangeset.repository!==final.repository||data.createdChangeset.server!==final.server)return finish("failed","target_unverified","Observed changeset retained but its branch/repository/server spelling is not the final loaded target. No alias equivalence or target checkin proof inferred.");
+  const after=await pending("pending-final");if(!after)return finish("failed");data.pendingAfter=after;return finish("completed");
+ }catch{if(childEntered){data.unobservedChild=stage as CloseoutData["unobservedChild"];data.unattemptedStages=data.unattemptedStages.filter(n=>n!==stage);}return finish("failed",stage==="input"?"invalid_request":"producer_failed",stage==="input"?"Use only declared bounded branch selectors, strict closeout controls and admitted checkin text.":"Closeout observation failed; prior effects remain possible. No compensation or automatic replay.");}
+}

package/src/operations/closeout.ts

@@ -0,0 +1,19 @@
+import { tool } from "../tool-definition";
+import { outputFormatArg } from "../presentation/results";
+import { workdirArg } from "./arguments";
+import { assembleCloseoutReceipt, presentCloseoutReceipt } from "./closeout-receipt";
+export const mergeToBranch = tool({
+ description: "Merge a source branch into a target branch with a bounded typed stage ledger; unknown target/readiness stops before checkin and earlier effects remain recorded.",
+ args: {
+  source:tool.schema.string().optional().describe("Bounded hierarchical branch selector. Defaults to the directly observed loaded branch."),
+  target:tool.schema.string().optional().describe("Bounded hierarchical branch selector. Defaults to an admitted source-parent read in the observed repository scope."),
+  cardRef:tool.schema.string().optional().describe("Optional tracker reference in the default checkin message; derived message must meet existing checkin admission."),
+  message:tool.schema.string().optional().describe("Optional checkin message. Defaults to Merge <source> into <target>. Existing child text bounds apply."),
+  strategy:tool.schema.enum(["auto","source","destination"]).optional().describe("Conflict strategy; defaults to auto."),
+  updateTarget:tool.schema.boolean().optional().describe("Update target before merge; defaults to true."),
+  includePrivate:tool.schema.boolean().optional().describe("Include private items in merge checkin; defaults to false."),
+  preflight:tool.schema.boolean().optional().describe("Read-only discovery/pending preview, not zero CLI or applying readiness proof."),
+  format:outputFormatArg,workdir:workdirArg,
+ },
+ async execute(args){const dto=await assembleCloseoutReceipt(args);if(!dto.ok&&!args.preflight)throw Error(dto.error.message);return presentCloseoutReceipt(dto,args.format);},
+});