@aefree/pi-plastic 0.5.8 → 0.6.1

package/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project follows semantic versioning for public package releases.
 
 ## Unreleased
 
+## [0.6.1] - 2026-09-14
+
+### Fixed
+
+- Clarify that `cm cat --file` writes to and can overwrite its destination, including when stdout is redirected. Route ordinary baseline reviews through typed diff tools, require new external temporary destinations for necessary manual exports, and distinguish changeset numbers from file revision IDs.
+
+## [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.1
 ```
 
 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.1
 ```
 
 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.1",
   "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

@@ -10,12 +10,16 @@ Purpose: PlasticSCM operations for Unity workflows.
 
 Never run `cm diff` in Pi. It may launch GUI windows and block the CLI agent.
 
+`cm cat --file=<path>` writes to that path and can overwrite existing files; `--file` is never an input selector. Never point it at a canonical workspace file during inspection or review, even when piping stdout elsewhere. Use typed diff tools for baseline comparisons. If a typed tool cannot represent a required export, read the [historical export rules](references/changeset-operations.md#historical-export-fallback) first. A changeset number is not a file revision ID; never turn `cs:<number>` into `revid:<number>`.
+
 Never run interactive `cm merge --merge` flows. Use `plastic_merge` (preferred) or explicitly pass `--nointeractiveresolution --mergetype=try` (safe default). Use source/destination policy flags only as explicit overrides.
 
 Treat `plastic_merge` success as provisional until `plastic_status` confirms there are no merge-in-progress hints. Pending merge links are expected until the merge result is checked in; merge-in-progress hints are not. If files are manually resolved and validated but checkin is blocked by Plastic merge metadata, use `plastic_finalizeMerge` with an explicit source/destination policy before retrying checkin.
 
 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/skills/using-plastic/references/changeset-operations.md

@@ -84,6 +84,20 @@ plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevisio
 
 The typed diff tools own historical `cm cat --file` materialization and cleanup; do not create agent-authored temporary files for ordinary diffs. `cm cat --raw` is unsupported for this workflow. Use typed retrieval first; `cm cat --file` is the byte-preserving low-level fallback only when a typed tool cannot represent the case.
 
+## Historical Export Fallback
+
+Use this fallback only when typed retrieval cannot represent the required case. For an ordinary workspace-base comparison, omit `revision` from `plastic_diffFile`; for a changeset comparison, supply its `revision="cs:<number>"` argument.
+
+`cm cat <revspec> --file=<output-file>` writes historical bytes to the output file and can overwrite it. `--file` does not select the source. Piping this command to `Set-Content` or redirecting stdout does not change the destination or protect it: with `--file`, the file contents are written there rather than to stdout.
+
+Before a necessary manual export:
+
+- Verify the source selector. `revid:<id>` means an actual file revision ID, not a workspace changeset number. Use a verified repository/server-qualified revision ID, or a file-qualified `<path>#cs:<number>` selector for a file at a changeset.
+- Create a new unique temporary directory outside the workspace and select a new absolute output path within it. Confirm that the destination does not exist. Never use a canonical workspace path or an existing baseline as the export destination.
+- Export directly to that temporary destination; do not combine `--file` with a stdout pipeline to capture the content. Check command success and the exported content before comparison. Keep comparison baselines immutable.
+
+If an export overwrites a workspace file, stop further exports and edits, record the exact command and destination, and inspect pending status. A clean status after exporting base revisions can mean pending work was erased; it does not prove successful review. Report the incident before attempting recovery, and preserve unrelated user changes.
+
 ## Commit Message Format
 
 Use conventional commits from ../../_shared/references/conventional-commits.md.

package/skills/using-plastic/references/reviewing-changes.md

@@ -33,6 +33,8 @@ plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevisio
 
 The diff tools materialize historical bytes and remove their temporary files internally. Added and explicitly selected private/new files use an empty base; an added empty file is reported as `added-empty`, not generic unchanged. Changed, moved, and deleted records use their status revision ID when available. A `--nodata` item cannot supply historical/base bytes: refresh the workspace or use two known file-qualified revisions. `plastic_workspaceDiff` requires selected paths or `allPending=true` and returns per-file unavailable outcomes instead of aborting the batch. Text-diff tools use bounded GNU/POSIX text diff, materialize backend operands to ASCII-safe package paths while preserving logical Unicode output labels, treat valid Unity YAML as text, and report genuine binary content explicitly. Do not construct `cm cat` temporary-file recipes for ordinary review. `cm cat --raw` is unsupported in this workflow; typed retrieval owns cleanup, and `cm cat --file` is the byte-preserving low-level fallback only when needed.
 
+`cm cat --file` is a filesystem write: its argument is the output destination, never the source file. Pointing it at a working file overwrites pending changes even if stdout is piped to a temporary file. Reviewers must use typed comparisons for ordinary baseline review; a necessary unsupported export must follow the [historical export rules](changeset-operations.md#historical-export-fallback), with a new absolute temporary destination outside the workspace and a verified file revision selector.
+
 ## Metadata Listing (No GUI Diff)
 
 Use changeset metadata to understand branch activity:

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."] },