@aefree/pi-plastic 0.5.8 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project follows semantic versioning for public package releases.
 
 ## Unreleased
 
+## [0.6.0] - 2026-09-14
+
+### Added
+
+- Add `plastic_mergeBranches` for one bounded, workspace-free server-side merge between explicitly same-repository/server qualified branches. The command-only preflight never contacts Plastic; completed results require one emitted root-mount target changeset and retain unverified merge-link/xlink effects and uncertain no-op/conflict effects.
+
+### Changed
+
+- Pin the test runner as local devDependency `tsx@4.23.5` and make all package test, live-test, and eval scripts use that local executable instead of an opportunistic `npx` download.
+- Update README's pinned GitHub installation examples to `v0.6.0`.
+
+### Fixed
+
+- Make `plastic_mergeBranches` JSON formatting side-effect free, enforce exact bounded machine-readable record framing/schema, and bound both local capability and merge process lifetimes without retrying uncertain dispatches.
+- Stop workspace merge closeout before target-side mutation when its required switch is canceled for pending changes; the blocked result now includes typed pending context and `checkedIn: false`.
+- Preserve qualified parent-lookup repository/server scope while matching documented local branch-name fields, and report bounded `cm find` failures instead of silently treating them as a missing parent; root and missing branches now remain distinguishable.
+
 ## [0.5.8] - 2026-09-15
 
 ### Fixed

package/README.md

@@ -36,6 +36,7 @@ Removing the approval layer does not relax Plastic safety guards. Command allowl
 - `plastic_branchCreate`
 - `plastic_switchBranch`
 - `plastic_merge`
+- `plastic_mergeBranches`
 - `plastic_mergeToBranch`
 - `plastic_finalizeMerge`
 - `plastic_currentBranch`
@@ -54,7 +55,7 @@ Removing the approval layer does not relax Plastic safety guards. Command allowl
 
 ## Dynamic tool loading
 
-The package exposes 29 public `plastic_*` tools. `plastic_workspaceCreate` is intentionally not registered or discoverable until the package provides a paired, safe workspace-cleanup capability. `plastic_tool_search` is a package-owned loader that searches the explicit Plastic capability catalog, reports bounded matches and safety guidance, and additively enables selected tools for the next model request.
+The package exposes 30 public `plastic_*` tools. `plastic_workspaceCreate` is intentionally not registered or discoverable until the package provides a paired, safe workspace-cleanup capability. `plastic_tool_search` is a package-owned loader that searches the explicit Plastic capability catalog, reports bounded matches and safety guidance, and additively enables selected tools for the next model request.
 
 The default **balanced** session set keeps `plastic_tool_search`, `plastic_status`, and `plastic_currentBranch` active. The other Plastic tools remain registered but inactive until selected; built-in and other-extension tools are not removed. Previous loader additions on the active session branch are restored on startup, resume, fork, and reload.
 
@@ -80,6 +81,7 @@ The Bash guards run only in Pi processes that actually load this package. A proj
 - `plastic_patch` generates review patches with `cm patch`, including `clean` and `integration` filters for branch review workflows. It does not expose patch apply. Unqualified `br:/...` selectors are qualified only with the current workspace selector's exact repository; otherwise pass `br:/<branch>@<repository>@<server>`.
 - Bash safety rails block `cm diff` and unsafe interactive `cm merge --merge` usage.
 - Merge tooling surfaces Plastic `FILE_CONFLICT` records and merge-state metadata from `cm status`.
+- `plastic_mergeBranches` is a separate workspace-free server-side route. It requires fully repository/server-qualified source and target branches in the same exact repository/server and a nonempty message. Its optional preflight only renders the command; it does not analyze remote conflicts. A completed result proves one emitted root-mount target changeset for this dispatch, not source merge-link identity, exclusive target-head ownership, server capability beyond the dispatch, rollback, or xlink effects. No-op and conflict records do not independently prove that no server effect occurred. The route has no workspace fallback, retries, target-head unification, xlink policy, shelve mode, or conflict-policy override; undetected server-side xlink effects remain possible.
 - `plastic_mergeToBranch` performs the common safe closeout flow: resolve the source branch's parent as the default target, switch to the target branch, optionally update, merge a source branch non-interactively, verify merge state, and check in the merge result. It verifies the loaded target before merge/checkin and rejects final-branch mismatches; Plastic checkins stay on the branch where they were created, so switching afterward is not a Git-style integration.
 - `plastic_finalizeMerge` supports reviewed/manual-resolution flows where Plastic still needs merge metadata finalized before checkin.
 
@@ -109,13 +111,13 @@ pi install npm:@aefree/pi-plastic
 Install a pinned GitHub release over HTTPS:
 
 ```bash
-pi install git:github.com/aefreedman/pi-plastic@v0.5.7
+pi install git:github.com/aefreedman/pi-plastic@v0.6.0
 ```
 
 Equivalent SSH install:
 
 ```bash
-pi install git:git@github.com/aefreedman/pi-plastic@v0.5.7
+pi install git:git@github.com/aefreedman/pi-plastic@v0.6.0
 ```
 
 To intentionally track the moving default branch instead of a release tag:

package/index.ts

@@ -68,6 +68,7 @@ const PLASTIC_EXPORTS = [
   "branchCreate",
   "switchBranch",
   "merge",
+  "mergeBranches",
   "mergeToBranch",
   "finalizeMerge",
   "currentBranch",
@@ -223,6 +224,11 @@ const TOOL_CONFIG: Partial<Record<PlasticExportName, ToolConfig>> = {
       return input;
     },
   },
+  mergeBranches: {
+    prepareArguments(args) {
+      return normalizeOutputFormatAlias(normalizeArgs(args));
+    },
+  },
   mergeToBranch: {
     prepareArguments(args) {
       const input = normalizeOutputFormatAlias(normalizeArgs(args));
@@ -714,7 +720,7 @@ export default function plasticTools(pi: ExtensionAPI) {
       },
       async execute(_toolCallId, params, signal, _onUpdate, ctx) {
         const normalizedParams = normalizeArgs(params);
-        if (normalizedParams.workdir === undefined && ctx?.cwd) {
+        if (exportName !== "mergeBranches" && normalizedParams.workdir === undefined && ctx?.cwd) {
           normalizedParams.workdir = ctx.cwd;
         }
         const result = await core.runWithAbortSignal(signal, async () => coreTool.execute(normalizedParams));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aefree/pi-plastic",
-  "version": "0.5.8",
+  "version": "0.6.0",
   "type": "module",
   "engines": {
     "node": ">=22.19.0"
@@ -33,14 +33,15 @@
     ]
   },
   "scripts": {
-    "test": "npx --yes tsx tests/plastic-tool-validation.ts && npx --yes tsx tests/plastic-status-machine-readable.test.ts && npx --yes tsx tests/plastic-checkin-path-resolution.ts && npx --yes tsx tests/plastic-diff-workflow.test.ts && npx --yes tsx tests/plastic-workspace-diff.test.ts && npx --yes tsx tests/plastic-process-lifecycle.test.ts && npx --yes tsx tests/plastic-patch-command.test.ts && npx --yes tsx tests/plastic-capability-diagnostics.test.ts && npx --yes tsx tests/plastic-extension-registration.test.ts && npx --yes tsx tests/plastic-dynamic-tool-loading.test.ts && npx --yes tsx tests/plastic-tool-rendering.test.ts && npx --yes tsx tests/plastic-branch-query.test.ts && npx --yes tsx tests/plastic-workspace.test.ts && npx --yes tsx tests/plastic-mutation-execution.test.ts && npx --yes tsx tests/file-discovery-filter.test.ts && npx --yes tsx tests/file-discovery-filter-registration.test.ts && npx --yes tsx tests/packed-copy-owner-conflict.test.ts && npx --yes tsx tests/plastic-branch-status.test.ts && npx --yes tsx tests/plastic-constrained-sampling.test.ts && npx --yes tsx tests/bash-cm-diff-guard-validation.ts",
-    "test:live": "npx --yes tsx tests/plastic-live-smoke.test.ts",
-    "test:live:branch-create": "npx --yes tsx tests/plastic-branch-create-live.test.ts",
-    "eval:tool-loading": "npx --yes tsx evals/tool-loading/run-eval.ts"
+    "test": "tsx tests/release-registry-preflight.test.ts && tsx tests/plastic-tool-validation.ts && tsx tests/plastic-status-machine-readable.test.ts && tsx tests/plastic-checkin-path-resolution.ts && tsx tests/plastic-diff-workflow.test.ts && tsx tests/plastic-workspace-diff.test.ts && tsx tests/plastic-process-lifecycle.test.ts && tsx tests/plastic-patch-command.test.ts && tsx tests/plastic-capability-diagnostics.test.ts && tsx tests/plastic-extension-registration.test.ts && tsx tests/plastic-dynamic-tool-loading.test.ts && tsx tests/plastic-tool-rendering.test.ts && tsx tests/plastic-branch-query.test.ts && tsx tests/plastic-workspace.test.ts && tsx tests/plastic-mutation-execution.test.ts && tsx tests/plastic-merge-branches.test.ts && tsx tests/file-discovery-filter.test.ts && tsx tests/file-discovery-filter-registration.test.ts && tsx tests/packed-copy-owner-conflict.test.ts && tsx tests/plastic-branch-status.test.ts && tsx tests/plastic-constrained-sampling.test.ts && tsx tests/bash-cm-diff-guard-validation.ts",
+    "test:live": "tsx tests/plastic-live-smoke.test.ts",
+    "test:live:branch-create": "tsx tests/plastic-branch-create-live.test.ts",
+    "eval:tool-loading": "tsx evals/tool-loading/run-eval.ts"
   },
   "devDependencies": {
     "@aefree/pi-file-discovery": "^0.1.1",
     "@earendil-works/pi-coding-agent": "0.83.0",
+    "tsx": "4.23.5",
     "typebox": "^1.3.8"
   },
   "peerDependencies": {

package/skills/using-plastic/SKILL.md

@@ -16,6 +16,8 @@ Treat `plastic_merge` success as provisional until `plastic_status` confirms the
 
 For the common closeout flow of merging a finished source branch into its parent branch, prefer `plastic_mergeToBranch` when available. When `target` is omitted, it resolves the source branch's Plastic parent branch instead of assuming `/dev`. It switches to the target, optionally updates, runs the safe merge, checks merge state, and checks in the merge result. Pass `target` only when the user explicitly wants a different integration branch.
 
+Use `plastic_mergeBranches` only for the separate workspace-free server-side route. It requires explicit same-repository/server `br:/...@<repository>@<server>` source and target selectors plus a nonempty message. Its preflight renders the command only; it does not contact Plastic or analyze conflicts. A completed result proves one emitted root-mount target changeset for the dispatch, but does not verify the source merge link, target-head exclusivity, rollback, or xlink effects. No-op and conflict output do not prove that no effect occurred. Do not use it for xlink handling, conflict-policy selection, shelve merges, retries, target-head unification, or a workspace fallback; undetected server-side xlink effects remain possible.
+
 Plastic merges are workspace- and branch-oriented, not Git fast-forwards: the merge is applied to the branch currently loaded in the workspace, and the merge checkin must be created on that target branch. Switching to the target after a checkin on the source branch does not move or integrate that changeset. Treat any source/target/final-branch mismatch as a failed closeout; inspect target-branch history and rerun the merge from the actual target rather than merely switching branches.
 
 `plastic_diff` is intentionally disabled. Route changed-path listing to `plastic_status()`, one intentional workspace-file comparison to `plastic_diffFile(path="<workspace-path>")`, an explicitly scoped pending review to `plastic_workspaceDiff(paths=[...])`, and an explicit historical pair to `plastic_diffRevisions`. Do not use diffs as routine post-edit validation or checkin preflight. Prefer focused tests, `plastic_status` for pending scope, and direct reads for current file content; diff only when change-boundary evidence is needed. `plastic_diffFile` uses machine-readable status: added and explicitly selected private/new files compare against an empty base; changed, moved, and deleted items use their reported base revision when available. An added empty file reports `status="added-empty"`, not generic unchanged. A `--nodata` base failure means Plastic cannot provide historical bytes; refresh/update the workspace or use two known file-qualified revisions. Explicit `revision` behavior remains a separate historical request. Binary content is reported rather than decoded as text. Text backends receive ASCII-safe package materializations while returned headers preserve logical Unicode labels.

package/src/plastic-core.ts

@@ -1,6 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { isUtf8 } from "node:buffer";
 import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { tool } from "./pi-tool-compat";
 import { promises as fs, realpathSync, statSync } from "node:fs";
 import { tmpdir } from "os";
@@ -12,8 +13,11 @@ type SpawnResult = {
     stderr: string;
     exitCode: number;
     aborted: boolean;
+    timedOut?: boolean;
     stdoutTruncated?: boolean;
     stdoutTotalChars?: number;
+    stderrTruncated?: boolean;
+    stderrTotalChars?: number;
 };
 
 const abortSignalStorage = new AsyncLocalStorage<AbortSignal | undefined>();
@@ -63,7 +67,14 @@ export const runWithAbortSignal = async <T>(
     signal: AbortSignal | undefined,
     fn: () => Promise<T>,
     commandExecution?: SpawnAndCollectDependencies,
-): Promise<T> => abortSignalStorage.run(signal, () => commandExecutionStorage.run(commandExecution, fn));
+): Promise<T> =>
+{
+    const inheritedSignal = getActiveAbortSignal();
+    const inheritedExecution = commandExecutionStorage.getStore();
+    // Nested public-tool execution must retain an injected process seam and the
+    // outer abort signal instead of silently dropping either boundary.
+    return abortSignalStorage.run(signal ?? inheritedSignal, () => commandExecutionStorage.run(commandExecution ?? inheritedExecution, fn));
+};
 
 const writeInput = async (stdin: NodeJS.WritableStream | null | undefined, input: string): Promise<void> =>
 {
@@ -114,6 +125,7 @@ type SpawnAndCollectDependencies = {
     setTimeout?: (callback: () => void, delay: number) => NodeJS.Timeout;
     clearTimeout?: (timeout: NodeJS.Timeout) => void;
     abortKillDelayMs?: number;
+    timeoutMs?: number;
     outputLimitChars?: number;
 };
 
@@ -150,8 +162,10 @@ const spawnAndCollect = async (
     const stdoutPromise = readStream(proc.stdout, dependencies.outputLimitChars);
     const stderrPromise = readStream(proc.stderr, dependencies.outputLimitChars);
     let aborted = false;
+    let timedOut = false;
     let terminalSettled = false;
     let killTimeout: NodeJS.Timeout | undefined;
+    let operationTimeout: NodeJS.Timeout | undefined;
 
     let resolveExit: (exitCode: number) => void;
     let rejectExit: (error: Error) => void;
@@ -185,14 +199,13 @@ const spawnAndCollect = async (
     proc.once("error", onProcessError);
     proc.once("close", onProcessClose);
 
-    const onAbort = () =>
+    const terminate = () =>
     {
         if (terminalSettled)
         {
             return;
         }
 
-        aborted = true;
         try
         {
             proc.kill("SIGTERM");
@@ -217,8 +230,21 @@ const spawnAndCollect = async (
             }
         }, dependencies.abortKillDelayMs ?? 5000);
     };
+    const onAbort = () =>
+    {
+        aborted = true;
+        terminate();
+    };
 
     signal?.addEventListener("abort", onAbort, { once: true });
+    if (dependencies.timeoutMs !== undefined)
+    {
+        operationTimeout = scheduleTimeout(() =>
+        {
+            timedOut = true;
+            terminate();
+        }, dependencies.timeoutMs);
+    }
 
     try
     {
@@ -234,8 +260,11 @@ const spawnAndCollect = async (
             stderr: stderrResult.output,
             exitCode,
             aborted,
+            timedOut,
             stdoutTruncated: stdoutResult.truncated,
             stdoutTotalChars: stdoutResult.totalChars,
+            stderrTruncated: stderrResult.truncated,
+            stderrTotalChars: stderrResult.totalChars,
         };
     }
     finally
@@ -247,6 +276,10 @@ const spawnAndCollect = async (
         {
             cancelTimeout(killTimeout);
         }
+        if (operationTimeout)
+        {
+            cancelTimeout(operationTimeout);
+        }
     }
 };
 
@@ -1217,6 +1250,47 @@ const isSwitchBringBlockedForUnattended = (pendingChoice: "shelve" | "bring" | "
     return pendingChoice === "bring" && profile.hasTrackedPendingChanges;
 };
 
+type CanceledSwitchOutcome = {
+    kind: "canceled";
+    strategy: "cancel-with-pending";
+    branchBefore: string;
+    branchTarget: string;
+    pendingSummary: PendingSummary;
+    pendingSummaryDetailed: PendingItemSummary;
+    pendingPolicy: "cancel";
+    defaultedPolicy: boolean;
+    reason: string;
+};
+
+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.",
+    };
+};
+
 const canSwitchDirectWithPrivateOnlyPending = (
     pendingChoice: "shelve" | "bring" | "cancel",
     defaultedPolicy: boolean,
@@ -2566,30 +2640,130 @@ const buildMergeInProgressCheckinMessage = async (originalMessage: string, workd
     return lines.join("\n");
 };
 
-const resolveBranchParentName = async (branch: string, workdir?: string): Promise<string | undefined> =>
+type BranchParentLookupOutcome =
+    | { kind: "resolved"; branch: string; parent: string }
+    | { kind: "root"; branch: string; matchedBranch: string }
+    | { kind: "not-found"; branch: string; attemptedCandidates: string[] }
+    | { kind: "malformed-output"; branch: string; attemptedCandidates: string[]; diagnostics: string[] }
+    | { kind: "command-failed"; branch: string; attemptedCandidates: string[]; diagnostics: string[] };
+
+type BranchParentRow = { name: string; parent?: string };
+
+const parseBranchParentRows = (output: string): BranchParentRow[] | undefined =>
+{
+    const lines = normalizeFindOutputLines(output);
+    const rows: BranchParentRow[] = [];
+    for (const line of lines)
+    {
+        const separator = line.indexOf("|");
+        if (separator <= 0 || line.indexOf("|", separator + 1) !== -1)
+        {
+            return undefined;
+        }
+        const name = line.slice(0, separator).trim();
+        const parent = line.slice(separator + 1).trim();
+        if (!name)
+        {
+            return undefined;
+        }
+        rows.push({ name, ...(parent ? { parent } : {}) });
+    }
+    return rows;
+};
+
+const branchRepositoryQualifier = (branch: string): string | undefined =>
+{
+    const match = branch.trim().match(/^(?:br:)?[^@]+(@.+)$/);
+    return match?.[1];
+};
+
+const branchRepositorySpec = (branch: string): string | undefined =>
+{
+    const qualifier = branchRepositoryQualifier(branch);
+    return qualifier?.slice(1);
+};
+
+const branchNameForLookup = (branch: string): string => normalizeBranchSpecForComparison(branch);
+
+const qualifyBranchName = (branchName: string, requestedBranch: string): string =>
+{
+    const qualifier = branchRepositoryQualifier(requestedBranch);
+    return qualifier && !branchName.includes("@") ? `${branchName}${qualifier}` : branchName;
+};
+
+const resolveBranchParentName = async (branch: string, workdir?: string): Promise<BranchParentLookupOutcome> =>
 {
-    const normalizedBranch = normalizeBranchSpecForComparison(branch);
-    const candidates = Array.from(new Set([branch.trim(), normalizedBranch, `br:${normalizedBranch}`]
-        .filter((candidate) => candidate.length > 0)));
+    const requestedBranch = branch.trim();
+    // A qualified selector is identity-bearing input; never strip its repository/server.
+    const lookupBranchName = branchNameForLookup(requestedBranch);
+    const candidates = Array.from(new Set(
+        (requestedBranch.includes("@")
+            ? [lookupBranchName]
+            : [requestedBranch, lookupBranchName, `br:${lookupBranchName}`])
+            .filter((candidate) => candidate.length > 0),
+    ));
+    const diagnostics: string[] = [];
+    const repositorySpec = branchRepositorySpec(requestedBranch);
+    const repositoryClause = repositorySpec
+        ? ` on repository '${repositorySpec.replace(/'/g, "''")}'`
+        : "";
 
     for (const candidate of candidates)
     {
-        const output = await runCmRaw([
-            "find",
-            "branch",
-            `where ${cmWhereEquals("name", candidate)}`,
-            "--format={parent}",
-            "--nototal",
-        ], workdir).catch(() => "");
-        const lines = normalizeFindOutputLines(output);
-        const parent = lines[0]?.trim();
-        if (parent)
+        try
         {
-            return parent;
+            const output = await runCmRaw([
+                "find",
+                "branch",
+                `where ${cmWhereEquals("name", candidate)}${repositoryClause}`,
+                "--format={name}|{parent}",
+                "--nototal",
+            ], workdir);
+            const rows = parseBranchParentRows(output);
+            if (!rows || rows.length > 1)
+            {
+                return {
+                    kind: "malformed-output",
+                    branch: requestedBranch,
+                    attemptedCandidates: candidates,
+                    diagnostics: [`Expected one name|parent row, received ${rows ? rows.length : "malformed"}.`],
+                };
+            }
+            const row = rows[0];
+            if (row && branchNameForLookup(row.name) !== lookupBranchName)
+            {
+                return {
+                    kind: "malformed-output",
+                    branch: requestedBranch,
+                    attemptedCandidates: candidates,
+                    diagnostics: ["Returned branch identity did not match the requested branch name."],
+                };
+            }
+            if (row?.parent)
+            {
+                return {
+                    kind: "resolved",
+                    branch: qualifyBranchName(row.name, requestedBranch),
+                    parent: qualifyBranchName(row.parent, requestedBranch),
+                };
+            }
+            if (row)
+            {
+                return { kind: "root", branch: requestedBranch, matchedBranch: qualifyBranchName(row.name, requestedBranch) };
+            }
+        }
+        catch (error)
+        {
+            diagnostics.push(normalizeErrorMessage(error).slice(0, 256));
         }
     }
 
-    return undefined;
+    if (diagnostics.length > 0)
+    {
+        return { kind: "command-failed", branch: requestedBranch, attemptedCandidates: candidates, diagnostics: diagnostics.slice(0, 3) };
+    }
+
+    return { kind: "not-found", branch: requestedBranch, attemptedCandidates: candidates };
 };
 
 const resolveCurrentBranchName = async (workdir?: string): Promise<string> =>
@@ -4047,11 +4221,17 @@ export const switchBranch = tool({
             throw new Error(reason);
         }
 
-        if (pendingChoice === "cancel")
+        const canceledOutcome = createCanceledSwitchOutcome(
+            branchBefore,
+            args.branch,
+            pendingSummary,
+            pendingSummaryDetailed,
+            pendingChoice,
+            defaulted,
+        );
+        if (canceledOutcome)
         {
-            const reason = defaulted
-                ? "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.";
+            const reason = canceledOutcome.reason;
             if (preflight)
             {
                 return toStructuredResult(
@@ -4360,6 +4540,340 @@ export const merge = tool({
     },
 });
 
+type QualifiedServerBranch = {
+    raw: string;
+    branch: string;
+    repository: string;
+    server: string;
+};
+
+type ServerMergeRecord = {
+    operation: string;
+    fields: string[];
+};
+
+type ServerMergeParse = {
+    records: ServerMergeRecord[];
+    malformed: boolean;
+    unknownOperations: string[];
+    changesets: Array<{ id: string; branch: string; repository: string; mount: string }>;
+    isAlreadyConnected: boolean;
+    hasConflict: boolean;
+};
+
+const SERVER_MERGE_OUTPUT_LIMIT = 16_384;
+const SERVER_MERGE_HELP_TIMEOUT_MS = 3_000;
+const SERVER_MERGE_COMMAND_TIMEOUT_MS = 30_000;
+const serverMergeControlPattern = /[\u0000-\u001f\u007f-\u009f]/;
+const serverMergeCapabilityTokens = ["--to", "--merge", "--nointeractiveresolution", "--machinereadable", "--startlineseparator", "--endlineseparator", "--fieldseparator"];
+
+const assertSafeServerMergeValue = (name: string, value: string): string =>
+{
+    const trimmed = value.trim();
+    if (!trimmed || serverMergeControlPattern.test(value))
+    {
+        throw new Error(`${name} must be non-empty and must not contain control characters.`);
+    }
+
+    return trimmed;
+};
+
+const parseQualifiedServerBranch = (name: string, value: string): QualifiedServerBranch =>
+{
+    const raw = assertSafeServerMergeValue(name, value);
+    if (!raw.startsWith("br:/"))
+    {
+        throw new Error(`${name} must use fully qualified syntax 'br:/<branch>@<repository>@<server>'.`);
+    }
+
+    const lastAt = raw.lastIndexOf("@");
+    const previousAt = raw.lastIndexOf("@", lastAt - 1);
+    if (previousAt <= 3 || lastAt <= previousAt + 1 || lastAt === raw.length - 1)
+    {
+        throw new Error(`${name} must use fully qualified syntax 'br:/<branch>@<repository>@<server>'.`);
+    }
+
+    const branch = raw.slice(3, previousAt);
+    const repository = raw.slice(previousAt + 1, lastAt);
+    const server = raw.slice(lastAt + 1);
+    if (!branch.startsWith("/") || branch.endsWith("/") || [branch, repository, server].some((part) => !part || part !== part.trim() || serverMergeControlPattern.test(part)))
+    {
+        throw new Error(`${name} must use fully qualified syntax 'br:/<branch>@<repository>@<server>'.`);
+    }
+
+    return { raw, branch, repository, server };
+};
+
+const createServerMergeSeparators = (): { start: string; end: string; field: string } =>
+{
+    const nonce = randomBytes(16).toString("hex");
+    return {
+        start: `__PI_PLASTIC_MERGE_START_${nonce}__`,
+        end: `__PI_PLASTIC_MERGE_END_${nonce}__`,
+        field: `__PI_PLASTIC_MERGE_FIELD_${nonce}__`,
+    };
+};
+
+const parseServerMergeOutput = (output: string, separators: { start: string; end: string; field: string }): ServerMergeParse =>
+{
+    const records: ServerMergeRecord[] = [];
+    const unknownOperations = new Set<string>();
+    let malformed = false;
+    let cursor = 0;
+
+    while (true)
+    {
+        const start = output.indexOf(separators.start, cursor);
+        if (start < 0)
+        {
+            if (output.slice(cursor).includes(separators.end) || output.slice(cursor).includes(separators.field))
+            {
+                malformed = true;
+            }
+            break;
+        }
+        const prefix = output.slice(cursor, start);
+        if (prefix.includes(separators.end) || prefix.includes(separators.field))
+        {
+            malformed = true;
+        }
+        const payloadStart = start + separators.start.length;
+        const end = output.indexOf(separators.end, payloadStart);
+        if (end < 0)
+        {
+            malformed = true;
+            break;
+        }
+        const payload = output.slice(payloadStart, end);
+        if (!payload || payload.includes(separators.start) || payload.includes(separators.end))
+        {
+            malformed = true;
+        }
+        else
+        {
+            const fields = payload.split(separators.field);
+            const operation = fields[0] ?? "";
+            if (!operation || fields.some((field) => field.length === 0))
+            {
+                malformed = true;
+            }
+            else
+            {
+                records.push({ operation, fields });
+                if (!["FILE_SRC", "CHANGESET", "STATUS", "FILE_CONFLICT"].includes(operation))
+                {
+                    unknownOperations.add(operation);
+                    malformed = true;
+                }
+            }
+        }
+        cursor = end + separators.end.length;
+    }
+
+    const changesets: Array<{ id: string; branch: string; repository: string; mount: string }> = [];
+    let isAlreadyConnected = false;
+    let hasConflict = false;
+    for (const record of records)
+    {
+        switch (record.operation)
+        {
+            case "FILE_SRC":
+                if (record.fields.length !== 5 || !record.fields[1]?.startsWith("/") || !record.fields.slice(2).every((field) => /^\d+$/.test(field)))
+                {
+                    malformed = true;
+                }
+                break;
+            case "CHANGESET":
+            {
+                if (record.fields.length !== 2)
+                {
+                    malformed = true;
+                    break;
+                }
+                const match = record.fields[1]?.match(/^cs:(\d+)@(?<branch>\/[^@]+)@(?<repository>[^@]+) \(mount:'(?<mount>[^']+)'\)$/);
+                if (!match?.groups)
+                {
+                    malformed = true;
+                    break;
+                }
+                changesets.push({
+                    id: match[1]!,
+                    branch: match.groups.branch!,
+                    repository: match.groups.repository!,
+                    mount: match.groups.mount!,
+                });
+                break;
+            }
+            case "STATUS":
+                if (record.fields.length !== 3 || record.fields[1] !== "ALREADY_CONNECTED" || record.fields[2] !== "No merges detected" || isAlreadyConnected)
+                {
+                    malformed = true;
+                }
+                isAlreadyConnected = true;
+                break;
+            case "FILE_CONFLICT":
+                if (record.fields.length !== 6 || !record.fields[1]?.startsWith("/") || !record.fields.slice(2).every((field) => /^\d+$/.test(field)))
+                {
+                    malformed = true;
+                }
+                hasConflict = true;
+                break;
+            default:
+                // Unknown operations were recorded above and make the response uncertain.
+                break;
+        }
+    }
+    return { records, malformed, unknownOperations: [...unknownOperations], changesets, isAlreadyConnected, hasConflict };
+};
+
+const formatServerMergeResult = async (
+    format: OutputFormat,
+    outcome: "preflight" | "completed" | "no-op" | "conflict" | "uncertain" | "unsupported",
+    text: string,
+    data: Record<string, unknown>,
+): Promise<string> =>
+{
+    if (format === "text")
+    {
+        return text;
+    }
+    return `## merge-branches\n\n\`\`\`json\n${JSON.stringify({
+        ok: outcome === "completed" || outcome === "preflight" || outcome === "no-op",
+        action: "merge-branches",
+        outcome,
+        toolVersion: TOOL_VERSION,
+        data,
+    }, null, 2)}\n\`\`\``;
+};
+
+const getServerMergeCapability = async (): Promise<{ supported: boolean; diagnostics: string }> =>
+{
+    const result = await spawnAndCollect(getCmExecutable(), ["help", "merge"], process.cwd(), undefined, getActiveAbortSignal(), {
+        ...(commandExecutionStorage.getStore() ?? {}),
+        timeoutMs: SERVER_MERGE_HELP_TIMEOUT_MS,
+        outputLimitChars: SERVER_MERGE_OUTPUT_LIMIT,
+    });
+    const output = [result.stdout, result.stderr].filter(Boolean).join("\n");
+    const missing = serverMergeCapabilityTokens.filter((token) => !output.includes(token));
+    if (result.aborted || result.timedOut || result.exitCode !== 0 || result.stdoutTruncated || result.stderrTruncated || missing.length > 0)
+    {
+        return { supported: false, diagnostics: `Local cm help merge capability check did not prove required syntax${missing.length > 0 ? `: missing ${missing.join(", ")}` : "."}` };
+    }
+    return { supported: true, diagnostics: "Local cm help merge advertised the required merge-to and machine-readable syntax. Server capability remains unverified until dispatch." };
+};
+
+export const mergeBranches = tool({
+    description: "Perform one bounded workspace-free server-side merge between explicitly qualified branches; merge-link and xlink effects remain unverified.",
+    args: {
+        source: tool.schema.string().min(1).describe("Fully qualified source branch: br:/<branch>@<repository>@<server>."),
+        target: tool.schema.string().min(1).describe("Fully qualified target branch in the same repository/server as source."),
+        message: tool.schema.string().min(1).describe("Non-empty changeset comment; no editor fallback is allowed."),
+        preflight: tool.schema.boolean().optional().describe("Render the exact command only; does not contact Plastic or analyze remote conflicts."),
+        format: outputFormatArg,
+    },
+    async execute(args)
+    {
+        const format = args.format ?? "text";
+        const source = parseQualifiedServerBranch("source", args.source);
+        const target = parseQualifiedServerBranch("target", args.target);
+        const message = assertSafeServerMergeValue("message", args.message);
+        if (source.repository !== target.repository || source.server !== target.server)
+        {
+            throw new Error("source and target must identify the same exact repository and server.");
+        }
+        if (source.branch === target.branch)
+        {
+            throw new Error("source and target must identify different branches.");
+        }
+
+        const separators = createServerMergeSeparators();
+        const command = [
+            "merge", source.raw, `--to=${target.raw}`, "--merge", `-c=${message}`, "--nointeractiveresolution", "--machinereadable",
+            `--startlineseparator=${separators.start}`, `--endlineseparator=${separators.end}`, `--fieldseparator=${separators.field}`,
+        ];
+        const requestedIdentity = { source: source.raw, target: target.raw, repository: source.repository, server: source.server };
+        if (args.preflight)
+        {
+            return formatServerMergeResult(format, "preflight", [
+                "## Server Merge Preflight",
+                "",
+                "- Would run: yes",
+                "- Remote analysis: not performed",
+                `- Command: cm ${command.join(" ")}`,
+            ].join("\n"), { wouldRun: true, requestedIdentity, command: ["cm", ...command] });
+        }
+
+        const capability = await getServerMergeCapability();
+        if (!capability.supported)
+        {
+            return formatServerMergeResult(format, "unsupported", "## Server Merge Unsupported\n\n- No merge command was dispatched because local client syntax could not be proven.", {
+                requestedIdentity,
+                capability,
+                dispatched: false,
+            });
+        }
+
+        const attempt = await spawnAndCollect(getCmExecutable(), command, process.cwd(), undefined, getActiveAbortSignal(), {
+            ...(commandExecutionStorage.getStore() ?? {}),
+            timeoutMs: SERVER_MERGE_COMMAND_TIMEOUT_MS,
+            outputLimitChars: SERVER_MERGE_OUTPUT_LIMIT,
+        });
+        const output = [attempt.stdout, attempt.stderr].filter(Boolean).join("\n");
+        const parsed = parseServerMergeOutput(output, separators);
+        const matchingChangesets = parsed.changesets.filter((changeset) => changeset.branch === target.branch && changeset.repository === target.repository && changeset.mount === "/");
+        const effect = "not-proven";
+        const diagnostics = output.slice(0, 4_000);
+        const baseData = {
+            requestedIdentity,
+            capability,
+            command: ["cm", ...command],
+            dispatched: true,
+            exitCode: attempt.exitCode,
+            aborted: attempt.aborted,
+            timedOut: attempt.timedOut,
+            outputTruncated: Boolean(attempt.stdoutTruncated || attempt.stderrTruncated),
+            records: parsed.records,
+            observedChangesets: parsed.changesets,
+            diagnostics,
+            mergeLinkIdentity: "unverified",
+            xlinkEffects: "unverified",
+            effect,
+        };
+
+        const ambiguous = attempt.aborted || attempt.timedOut || attempt.stdoutTruncated || attempt.stderrTruncated || parsed.malformed
+            || parsed.unknownOperations.length > 0 || parsed.changesets.length > 1
+            || (parsed.changesets.length > 0 && matchingChangesets.length !== 1)
+            || (parsed.hasConflict && parsed.changesets.length > 0)
+            || (parsed.isAlreadyConnected && (parsed.changesets.length > 0 || parsed.hasConflict));
+        if (!ambiguous && attempt.exitCode === 0 && matchingChangesets.length === 1 && !parsed.hasConflict && !parsed.isAlreadyConnected)
+        {
+            const changeset = matchingChangesets[0]!;
+            return formatServerMergeResult(format, "completed", `## Server Merge Completed\n\n- Created target changeset: cs:${changeset.id}\n- Merge-link identity: unverified\n- Xlink effects: unverified`, {
+                ...baseData,
+                createdChangeset: changeset,
+                effect: "changeset-created",
+            });
+        }
+        if (!ambiguous && attempt.exitCode === 0 && parsed.isAlreadyConnected && parsed.changesets.length === 0 && !parsed.hasConflict)
+        {
+            return formatServerMergeResult(format, "no-op", "## Server Merge No-op\n\n- Plastic reported ALREADY_CONNECTED.\n- Effect: not independently verified.", baseData);
+        }
+        if (!ambiguous && attempt.exitCode !== 0 && parsed.hasConflict && parsed.changesets.length === 0)
+        {
+            return formatServerMergeResult(format, "conflict", "## Server Merge Conflict\n\n- Plastic reported a file conflict.\n- Effect: uncertain; inspect the server before any retry.", { ...baseData, effect: "uncertain" });
+        }
+        return formatServerMergeResult(format, "uncertain", "## Server Merge Uncertain\n\n- The command may have had an effect, but its bounded output does not prove a safe classification.\n- Do not retry automatically; inspect server state first.", {
+            ...baseData,
+            effect: "uncertain",
+            parseWarnings: {
+                malformed: parsed.malformed,
+                unknownOperations: parsed.unknownOperations,
+                matchingChangesetCount: matchingChangesets.length,
+            },
+        });
+    },
+});
+
 export const mergeToBranch = tool({
     description: "Merge a source branch into a target branch using safe Plastic update, switch, merge, and checkin steps.",
     args: {
@@ -4379,11 +4893,19 @@ export const mergeToBranch = tool({
         const format = args.format ?? "text";
         const startingBranch = await resolveCurrentBranchName(args.workdir);
         const sourceBranch = args.source ?? startingBranch;
-        const resolvedParentBranch = args.target ? undefined : await resolveBranchParentName(sourceBranch, args.workdir);
-        if (!args.target && !resolvedParentBranch)
-        {
-            throw new Error(`Unable to resolve the parent branch for ${sourceBranch}. Pass target explicitly.`);
-        }
+        const parentLookup = args.target ? undefined : await resolveBranchParentName(sourceBranch, args.workdir);
+        if (!args.target && parentLookup?.kind !== "resolved")
+        {
+            const details = parentLookup?.kind === "command-failed"
+                ? ` Plastic lookup failed: ${parentLookup.diagnostics.join(" | ")}`
+                : parentLookup?.kind === "malformed-output"
+                    ? ` Plastic lookup returned unusable output: ${parentLookup.diagnostics.join(" | ")}`
+                    : parentLookup?.kind === "root"
+                        ? ` ${parentLookup.matchedBranch} is a root branch with no parent.`
+                        : " Plastic found no matching branch row.";
+            throw new Error(`Unable to resolve the parent branch for ${sourceBranch}. Pass target explicitly.${details}`);
+        }
+        const resolvedParentBranch = parentLookup?.kind === "resolved" ? parentLookup.parent : undefined;
         const targetBranch = args.target ?? resolvedParentBranch!;
         const strategy: MergeConflictStrategy = args.strategy ?? "auto";
         const updateTarget = args.updateTarget ?? true;
@@ -4448,12 +4970,50 @@ export const mergeToBranch = tool({
             );
         }
 
+        // Inspect the cancel policy as typed data before any target-side mutation.
+        const pendingBeforeSwitchItems = await getMachineReadablePendingItems(args.workdir);
+        const pendingBeforeSwitchDetailed = summarizePendingItems(pendingBeforeSwitchItems, args.workdir ?? process.cwd());
+        const canceledSwitchOutcome = createCanceledSwitchOutcome(
+            startingBranch,
+            targetBranch,
+            toLegacyPendingSummary(pendingBeforeSwitchDetailed),
+            pendingBeforeSwitchDetailed,
+            "cancel",
+            false,
+        );
+        if (canceledSwitchOutcome)
+        {
+            return toStructuredResult(
+                "merge-to-branch",
+                format,
+                [
+                    "## Merge To Branch Blocked",
+                    "",
+                    `- Source branch: ${sourceBranch}`,
+                    `- Target branch: ${targetBranch}`,
+                    `- ${canceledSwitchOutcome.reason}`,
+                    "- No switch, update, merge, checkin, or shelveset command was run.",
+                ].join("\n"),
+                {
+                    sourceBranch,
+                    targetBranch,
+                    switchOutcome: canceledSwitchOutcome,
+                    checkedIn: false,
+                },
+                args.workdir,
+                [canceledSwitchOutcome.reason],
+                "Resolve or shelve pending changes before retrying the merge closeout.",
+            );
+        }
+
         const switchResult = await switchBranch.execute({
             branch: targetBranch,
             pendingChanges: "cancel",
             format: "json",
             workdir: args.workdir,
         });
+        const branchAfterSwitch = await resolveCurrentBranchName(args.workdir);
+        assertWorkspaceOnBranch(branchAfterSwitch, targetBranch, "branch switch and before target update");
         const updateResult = updateTarget ? await update.execute({ workdir: args.workdir }) : "(skipped)";
         const branchBeforeMerge = await resolveCurrentBranchName(args.workdir);
         assertWorkspaceOnBranch(branchBeforeMerge, targetBranch, "target update and before merge");

package/src/plastic-tool-loading.ts

@@ -33,6 +33,7 @@ export const PLASTIC_SEARCH_CATALOG: readonly PlasticSearchCatalogEntry[] = [
   { name: "plastic_branchCreate", aliases: ["create branch", "new branch"], tags: ["branch", "mutation", "workflow"], guidance: ["Create normal work branches beneath an intended parent, which may differ from the loaded branch. Use allowRootBranch only for intentional top-level branches."] },
   { name: "plastic_switchBranch", aliases: ["switch branch", "checkout branch", "change branch"], tags: ["branch", "workspace", "mutation"], guidance: ["Check pending changes and choose how to handle them before switching branches."] },
   { name: "plastic_merge", aliases: ["merge branch", "merge changes"], tags: ["merge", "conflict", "workflow"], guidance: ["Inspect merge state and resolve conflicts before checkin."] },
+  { name: "plastic_mergeBranches", aliases: ["server merge", "workspace-free merge", "merge qualified branches"], tags: ["merge", "branch", "server", "mutation"], guidance: ["Require explicit same-repository/server qualified source and target plus a nonempty message. Preflight only renders the command; completed output verifies a target changeset, not a merge link, exclusive target ownership, or xlink effects."] },
   { name: "plastic_mergeToBranch", aliases: ["merge to branch", "close branch", "merge closeout"], tags: ["merge", "branch", "closeout"], guidance: ["Plastic merges into the branch loaded in the workspace; confirm source, target, final branch, and target-branch checkin rather than assuming a Git-style fast-forward."] },
   { name: "plastic_finalizeMerge", aliases: ["finalize merge", "complete merge", "resolve merge"], tags: ["merge", "conflict", "finalize"], guidance: ["Use after reviewed manual conflict resolution when Plastic still needs merge metadata finalized."] },
   { name: "plastic_currentBranch", aliases: ["current branch", "which branch", "branch name"], tags: ["branch", "workspace", "inspect"], guidance: ["Inspect the current branch before branch, merge, or checkin operations."] },