@aefree/pi-plastic 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows semantic versioning for public package releases.
 
+## [0.5.4] - 2026-08-13
+
+### Fixed
+
+- Recognize both `smartbranch` and `br` branch forms in Plastic workspace selectors, including quoted values produced by different checkout workflows.
+- Use a valid local selector as the footer's authoritative branch source instead of launching an unnecessary `cm status` process; malformed or missing branch selectors retain the bounded CLI fallback.
+
+## [0.5.3] - 2026-08-09
+
+### Changed
+
+- Clarified executable routing: macOS bare `diff` is PATH-dependent and may be GNU Diffutils or Apple BSD `diff`; text-diff selection does not auto-select `gdiff`. Plastic 11 macOS validation confirmed that Apple BSD `/usr/bin/diff` supports text diffs but rejects `cm patch`'s `--binary` argument, so `plastic_patch` now identifies that contract failure and directs callers to the separate GNU Diffutils-compatible patch executable policy.
+
+### Fixed
+
+- Made historical and workspace text diffs Unicode-safe for the configured Windows backend: package-owned ASCII materializations are the only operands passed to `diff`, while returned unified headers retain stable logical Unicode labels.
+- Report an added empty pending file as `added-empty` with explicit text/JSON/workspace semantics instead of generic unchanged.
+- Clean package-owned `cm cat --file` outputs after retrieval failures, including failure-created zero-byte files; public guidance now treats `cm cat --raw` as unsupported and names typed retrieval or `cm cat --file` as the byte-preserving fallback.
+- Documented patch moved-item encoding as backend-determined (move-aware or delete/add) rather than claiming unverified runtime behavior.
+- Hardened `plastic_patch` on Windows: it now uses the dedicated `PI_PLASTIC_PATCH_EXECUTABLE` policy (or an explicit `toolPath`) instead of silently reusing the incompatible GnuWin32 text-diff backend, qualifies unqualified branch selectors against the exact current workspace repository, and rejects ambiguous selectors before `cm patch`.
+- Made requested patch output transactional: existing paths are rejected before generation; package-owned sibling staging is validated and atomically published only on success, with failed and zero-byte staging artifacts removed.
+- Reject branch-switch and merge-closeout success when the workspace is not actually on the requested target branch, including checks after target update, before merge checkin, and after checkin.
+- Clarify that Plastic merge checkins belong to the branch loaded in the workspace and cannot be integrated by switching branches afterward like a Git fast-forward.
+
 ## [0.5.2] - 2026-08-05
 
 ### Fixed

package/README.md

@@ -4,7 +4,7 @@ Pi tools, footer status, and skill guidance for Plastic SCM / Unity Version Cont
 
 ## Plastic branch footer status
 
-When Pi starts inside a Plastic workspace, this package adds a themed `Plastic <branch>` status to Pi's built-in footer. It discovers the nearest enclosing `.plastic/plastic.workspace`, reads the local selector as a fast credential-free fallback, and confirms the branch with a bounded `cm status` call. Selector changes and successful same-workspace `plastic_*` tools refresh the status; sibling workspaces are ignored.
+When Pi starts inside a Plastic workspace, this package adds a themed `Plastic <branch>` status to Pi's built-in footer. It discovers the nearest enclosing `.plastic/plastic.workspace` and reads either the selector's `smartbranch` or `br` form as the credential-free branch source. A bounded `cm status` call is used only when the selector has no valid branch. Selector changes and successful same-workspace `plastic_*` tools refresh the status; sibling workspaces are ignored.
 
 The extension owns only the `plastic-branch` status key. It does not replace Pi's footer or suppress Pi's Git branch display, so Git and Plastic information can appear together in nested workspaces. If the Plastic marker exists but neither the selector nor `cm` yields a branch, the footer shows `Plastic branch unavailable`. Non-Plastic directories show no Plastic status.
 
@@ -73,12 +73,12 @@ Pi 0.82 and newer use canonical `sourceInfo` provenance to identify this package
 The Bash guards run only in Pi processes that actually load this package. A project-local install does not protect a delegated child process whose working directory resolves different project settings. Install `pi-plastic` at user scope (the default `pi install`, without `-l`) when subagents and sessions in arbitrary workspaces must inherit the guards. Restart existing Pi processes after installation or source changes.
 
 - `plastic_branchCreate` supports an explicit parent branch independent of the loaded workspace branch, defaults relative names to the current branch when no parent is supplied, and rejects top-level paths unless `allowRootBranch=true` is explicit.
-- `plastic_diff` remains a disabled alias by design. Use `plastic_status` for changed-path listing; do not diff as routine post-edit validation or checkin preflight. When change-boundary evidence is needed, use `plastic_diffFile` for one exact file, `plastic_workspaceDiff` with selected paths or explicit `allPending=true`, or `plastic_diffRevisions` for an explicit historical pair. Diff responses use small defaults and caller-controlled `maxChars` bounds.
+- `plastic_diff` remains a disabled alias by design. Use `plastic_status` for changed-path listing; do not diff as routine post-edit validation or checkin preflight. When change-boundary evidence is needed, use `plastic_diffFile` for one exact file, `plastic_workspaceDiff` with selected paths or explicit `allPending=true`, or `plastic_diffRevisions` for an explicit historical pair. Diff responses use small defaults and caller-controlled `maxChars` bounds. Historical and workspace bytes are copied to ASCII-safe package-owned paths before the backend runs, while normalized headers retain the logical Unicode labels.
 - Preflight is not routine confirmation. Use it for ambiguous or broad mutation scope, moved/deleted path rewriting, compound operations, or explicit preview requests; otherwise rely on exact targets and the tools' runtime guards.
-- `plastic_patch` generates review patches with `cm patch`, including `clean` and `integration` filters for branch review workflows. It does not expose patch apply.
+- `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_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.
+- `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.
 
 ## Patch generation examples
@@ -90,7 +90,7 @@ plastic_patch(source="<left-spec>", destination="<right-spec>")
 plastic_patch(source="<branch-spec>", toolPath="<path-to-diff-tool>")
 ```
 
-If `output` is omitted, Plastic prints patch content to stdout. If `output` is provided, Plastic writes a new patch file and refuses to overwrite an existing file. Inspect patches before sharing them because they can contain source code, binary content, local paths, or secrets that were present in the changed files.
+If `output` is omitted, the package returns patch content. If `output` is provided, it must be a new path: the package generates into a package-owned sibling staging file, validates it, and atomically publishes it without overwriting an existing path. Plastic/server patch output may encode a moved item either as a move or as delete/add records; `pi-plastic` does not claim a representation without a live backend fixture. Inspect patches before sharing them because they can contain source code, binary content, local paths, or secrets that were present in the changed files.
 
 ## Included skill
 
@@ -107,13 +107,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.1
+pi install git:github.com/aefreedman/pi-plastic@v0.5.4
 ```
 
 Equivalent SSH install:
 
 ```bash
-pi install git:git@github.com:aefreedman/pi-plastic@v0.5.1
+pi install git:git@github.com/aefreedman/pi-plastic@v0.5.4
 ```
 
 To intentionally track the moving default branch instead of a release tag:
@@ -141,8 +141,9 @@ Project-local installation protects only Pi processes that load those project se
 - Node.js 22.19.0 or newer
 - Pi 0.82.0 or newer; the current development and eval baseline is Pi 0.83
 - Plastic SCM / Unity Version Control CLI (`cm`) available on `PATH`, or `PI_PLASTIC_CM_EXECUTABLE` set to its full executable path
-- GNU/POSIX-compatible `diff` available on `PATH`, or `PI_PLASTIC_DIFF_EXECUTABLE` set to its full executable path (including paths containing spaces), for text-only diff and patch tools. Pi does not discover Git Bash paths automatically.
-- A configured Plastic workspace for workspace-scoped operations
+- A GNU/POSIX-compatible text `diff` available on `PATH`, or `PI_PLASTIC_DIFF_EXECUTABLE` set to its full executable path (including paths containing spaces), for text-only diff tools. Pi invokes that resolved executable as-is and does not discover Git Bash paths automatically. On macOS, bare `diff` is PATH-dependent: it may be GNU Diffutils (often installed as `diff` ahead of system paths) or Apple’s BSD `/usr/bin/diff`; the package does not substitute one for the other. Configure the intended text executable explicitly when that distinction matters.
+- Patch generation has a separate executable policy: `toolPath` is the one-call highest-priority override, followed by `PI_PLASTIC_PATCH_EXECUTABLE`. On Windows, set one to a verified patch-capable non-GUI executable such as Git's `diff.exe`; the package deliberately does not reuse `PI_PLASTIC_DIFF_EXECUTABLE`/GnuWin32 as a patch default. macOS validation with Plastic 11 found that Apple BSD `/usr/bin/diff` supports text-only diffs but rejects the `--binary` argument supplied by `cm patch`; configure a verified GNU Diffutils-compatible executable explicitly for `plastic_patch`. The non-Windows fallback to `PI_PLASTIC_DIFF_EXECUTABLE` or bare `diff` remains only for environments whose resolved executable satisfies that patch contract.
+- A configured Plastic workspace for workspace-scoped operations. Text diffs require an ASCII-safe temporary directory; if the configured backend cannot accept Unicode paths, set `TEMP` and `TMP` to a writable ASCII-only location.
 - `pi-file-discovery` is an optional independently loaded integration. When its `discover_candidate_files` tool is active, it receives the advisory Plastic ignore/cloak filter through the shared global capability protocol; when absent, `pi-plastic` loads without file-discovery filtering. The tarball does not embed linked sibling workspaces or `node_modules` paths.
 
 ## Testing

package/extensions/plastic-branch-status.ts

@@ -219,7 +219,8 @@ export function createPlasticBranchStatusExtension(overrides: Partial<BranchStat
       if (!active || generation !== ownedGeneration || refreshSequence !== ownedRefresh) return;
 
       const hasSelectorBranch = selectorBranch ? displayBranch(selectorBranch) : false;
-      if (!hasSelectorBranch) displayUnavailable();
+      if (hasSelectorBranch) return;
+      displayUnavailable();
 
       const controller = new AbortController();
       confirmationController = controller;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aefree/pi-plastic",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "type": "module",
   "engines": {
     "node": ">=22.19.0"
@@ -15,10 +15,8 @@
     "index.ts",
     "extensions/",
     "src/",
-    "references/",
     "skills/",
     "CHANGELOG.md",
-    "CONTRIBUTING.md",
     "LICENSE",
     "README.md",
     "SECURITY.md"

package/skills/using-plastic/SKILL.md

@@ -16,9 +16,13 @@ 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.
 
-`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. 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.
+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_workspaceDiff` requires selected paths or explicit `allPending=true`, runs status once, has small default file/per-file/combined-output bounds, and returns per-file outcomes without aborting when one file is unavailable. Selected private paths are included; whole-workspace private review additionally requires `includePrivate=true`. Keep `maxChars` small unless more output is intentional. Use `plastic_patch` for review patch generation with `clean` and `integration` filters; it is generation-only and does not apply patches. It uses `PI_PLASTIC_DIFF_EXECUTABLE` when set, otherwise GNU/POSIX `diff` on PATH; paths containing spaces are supported, but Pi does not discover Git Bash paths automatically. Pass `toolPath` only for an intentional one-call override. For a large patch, pass an intentional new `output` path because Plastic will not overwrite it.
+`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.
+
+`plastic_workspaceDiff` requires selected paths or explicit `allPending=true`, runs status once, has small default file/per-file/combined-output bounds, and returns per-file outcomes without aborting when one file is unavailable. Selected private paths are included; whole-workspace private review additionally requires `includePrivate=true`. Keep `maxChars` small unless more output is intentional. Text-diff selection and patch-backend selection are distinct: text tools use `PI_PLASTIC_DIFF_EXECUTABLE` or bare PATH `diff`. On macOS, bare `diff` can resolve either to GNU Diffutils or Apple’s BSD `/usr/bin/diff`; Pi uses the resolved executable and does not auto-select `gdiff`.
+
+Use `plastic_patch` for review patch generation with `clean` and `integration` filters; it is generation-only and does not apply patches. `toolPath` is its highest-priority one-call patch-backend override, followed by `PI_PLASTIC_PATCH_EXECUTABLE`. On Windows, configure one to a verified patch-capable non-GUI executable such as Git's `diff.exe`: patch generation deliberately does not reuse `PI_PLASTIC_DIFF_EXECUTABLE`/GnuWin32. On macOS with Plastic 11, Apple BSD `/usr/bin/diff` works for text-only `plastic_diffFile` but rejects the `--binary` argument used by `cm patch`; set the patch-specific policy to a verified GNU Diffutils-compatible non-GUI executable. The non-Windows fallback to the text setting or bare `diff` is only valid when that executable accepts the local Plastic patch arguments. Unqualified `br:/...` patch selectors are qualified only from the current workspace's exact selector repository; otherwise pass `br:/<branch>@<repository>@<server>`. For a large patch, pass an intentional new `output` path: the package stages and atomically publishes it, never overwriting an existing path. Do not use `cm cat --raw`: it is unsupported for this workflow. Typed retrieval owns cleanup; the low-level byte-preserving fallback is `cm cat --file` only when a typed tool cannot represent the case. Plastic/server output may represent moves as moves or delete/add records, so inspect generated patches rather than assuming a move-aware encoding.
 
 Prefer runtime `plastic_*` tools first. Keep `cm` shell commands as manual fallback.
 

package/skills/using-plastic/references/changeset-operations.md

@@ -82,7 +82,7 @@ plastic_diffFile(path="<workspace-path>", revision="cs:<number>")
 plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
 ```
 
-The typed diff tools own historical `cm cat --file` materialization and cleanup; do not create agent-authored temporary files for ordinary diffs.
+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.
 
 ## Commit Message Format
 

package/skills/using-plastic/references/integration.md

@@ -9,6 +9,8 @@
 
 ## Autonomous Merge Workflow
 
+Plastic does not perform a Git-style fast-forward. It applies the merge into the branch currently loaded in the workspace, and the resulting merge changeset belongs to the branch where checkin runs. Switching branches afterward does not move an incorrectly placed changeset.
+
 - Switch to the target branch/workspace and ensure you understand the current pending state.
 - Run `plastic_merge(...)`.
 - If Plastic stops on a delete/change directory conflict and source deletion is the intended resolution, run `plastic_resolveDeleteChangeConflict(...)`, then rerun `plastic_merge(...)`.
@@ -17,6 +19,7 @@
 - If `plastic_status()` still shows `Pending merge links`, merge-in-progress state, or conflict-like pending items, stop and follow troubleshooting before any checkin.
 - After compile/tests, run `plastic_status()` again so Unity-generated private artifacts are not mistaken for merge fallout.
 - Only then create the merge checkin.
+- Verify the merge checkin was created on the target branch. If the workspace or changeset is on the source branch, stop: do not switch to the target and claim completion. Inspect target history and rerun the merge while the target is actually loaded.
 
 ## Review Workflow
 
@@ -31,9 +34,11 @@ cm find changeset "where branch = '<branch-name>' order by changesetid desc limi
 
 ```text
 plastic_patch(source="<branch-spec>", integration=true)
-plastic_patch(source="<branch-spec>", clean=true, integration=true, output="<patch-file>")
+plastic_patch(source="<branch-spec>", clean=true, integration=true, output="<new-patch-file>")
 ```
 
+  On Windows configure `PI_PLASTIC_PATCH_EXECUTABLE` (or one-call `toolPath`) to a verified patch-capable non-GUI executable; do not rely on the text-diff/GnuWin32 setting. Use a repository-qualified `br:/...@<repository>@<server>` selector when the current workspace selector cannot supply the exact repository. Requested output is staged and atomically published only when successful.
+
 - When change-boundary evidence is needed, inspect specific files first and opt into multi-file output explicitly:
 
 ```text

package/skills/using-plastic/references/quick-reference.md

@@ -16,7 +16,7 @@ Note: command examples target current `cm` 11.x CLI syntax; legacy aliases may d
 | Merge | `plastic_merge(source="<source-branch-spec>")` | `cm merge <source-branch-spec> --merge --nointeractiveresolution --mergetype=try` | Surfaces `FILE_CONFLICT`; run `plastic_status()` before checkin |
 | Finalize merge metadata | `plastic_finalizeMerge(source="<source-branch-spec>", strategy="destination")` | `cm merge <source-branch-spec> --merge --nointeractiveresolution --mergetype=forced --keepdestination` | Use after manual/reviewed resolution when checkin says merge is still in progress |
 | Shelve | `plastic_shelvesetCreate(comment="description")` | `cm shelveset create -c="description"` | Save work temporarily |
-| Patch for review | `plastic_patch(source="<branch-spec>", clean=true, integration=true, output="<patch-file>")` | `cm patch <branch-spec> --clean --integration --output=<patch-file>` | Focused branch-review patch; inspect before sharing |
+| Patch for review | `plastic_patch(source="<branch-spec>", clean=true, integration=true, output="<new-patch-file>")` | `cm patch <branch-spec> --clean --integration --output=<patch-file>` | Uses `toolPath` then `PI_PLASTIC_PATCH_EXECUTABLE`; Windows requires a verified patch-capable non-GUI executable. New output is staged and atomically published without overwrite; use repository-qualified `br:/...@<repository>@<server>` if selector resolution is unavailable |
 | Changed-file listing | `plastic_status(machineReadable=true)` | `cm status --all` | Lists changed, added, moved, deleted, and private items without GUI diff |
 | Diff (one workspace file) | `plastic_diffFile(path="<workspace-path>", maxChars=4000)` | None recommended | Intentional focused comparison only; not routine validation |
 | Diff (pending review) | `plastic_workspaceDiff(paths=["<workspace-path>"], maxChars=3000)` | None recommended | Requires selected paths or explicit `allPending=true`; use status for changed-path listing |
@@ -25,9 +25,12 @@ Note: command examples target current `cm` 11.x CLI syntax; legacy aliases may d
 
 ## Merge verification checklist
 
+Plastic merges into the branch currently loaded in the workspace; switching afterward does not move a source-branch changeset to the target.
+
 - Run `plastic_merge(...)`.
 - If `plastic_merge(...)` reports `FILE_CONFLICT`, inspect/resolve the listed paths and validate before finalizing.
 - Immediately run `plastic_status()`.
 - Pending merge links are expected until the merge result is checked in; merge-in-progress hints are blockers.
 - If validation/tests were run after the merge, run `plastic_status()` again before checkin so generated private artifacts do not muddy the result.
 - If `plastic_checkin(...)` says a merge is still in progress after files are resolved and validated, run `plastic_finalizeMerge(source=..., strategy="destination")`, then retry checkin.
+- Confirm the merge changeset and final workspace branch are the intended target. A source/target mismatch is failure, even when the command returned success or the workspace is clean.

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

@@ -13,11 +13,10 @@ Use `plastic_patch` when you need a branch-review patch for AI assistance, code
 ```text
 plastic_patch(source="<branch-spec>", integration=true)
 plastic_patch(source="<branch-spec>", clean=true, integration=true, output="<patch-file>")
-plastic_patch(source="<left-spec>", destination="<right-spec>")
 plastic_patch(source="<branch-spec>", toolPath="<path-to-diff-tool>")
 ```
 
-`integration=true` shows changes pending merge into the parent branch. `clean=true` strips content that arrived via merges. Use `output` for large patches; Plastic refuses to overwrite an existing output file. Inspect patch contents before sharing because patches can contain source code, binary data, local paths, or secrets present in changed files.
+`integration=true` shows changes pending merge into the parent branch. `clean=true` strips content that arrived via merges. Plastic/server output may encode moved items as moves or as delete/add records, so inspect the generated patch rather than assuming a move-aware representation. `toolPath` is the highest-priority patch backend override, followed by `PI_PLASTIC_PATCH_EXECUTABLE`. On macOS with Plastic 11, Apple BSD `/usr/bin/diff` is validated for text-only diffs but rejects the `--binary` argument passed by `cm patch`; configure a verified GNU Diffutils-compatible non-GUI executable through the patch-specific setting or `toolPath`. Text-diff configuration is independent. The non-Windows fallback to `PI_PLASTIC_DIFF_EXECUTABLE` or bare `diff` is suitable only when that executable accepts the local Plastic patch arguments. This macOS observation does not validate a Windows backend; verify an explicit Windows patch backend locally. `destination` passes a second spec to `cm patch`, but its two-spec behavior is not yet an established review workflow. Unqualified `br:/...` selectors are qualified only from the exact current workspace repository, otherwise use `br:/<branch>@<repository>@<server>`. Use `output` for large patches and choose a new path: the package stages, validates, and atomically publishes it without overwriting an existing file. Inspect patch contents before sharing because patches can contain source code, binary data, local paths, or secrets present in changed files.
 
 ## Text-Only Diff Options
 
@@ -32,7 +31,7 @@ plastic_diffFile(path="<workspace-path>", revision="cs:<number>") # explicit his
 plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevision="<right-file-qualified-revspec>")
 ```
 
-The diff tools materialize historical bytes and remove their temporary files internally. Added and explicitly selected private/new files use an empty base; 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. All tools use bounded GNU/POSIX text diff, treat valid Unity YAML as text, and report genuine binary content explicitly. Do not construct `cm cat` temporary-file recipes for ordinary review.
+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.
 
 ## Metadata Listing (No GUI Diff)
 

package/skills/using-plastic/references/troubleshooting.md

@@ -20,6 +20,13 @@ cm switch --silent --noinput <branch-spec>
 
 Agent preference: use runtime `plastic_*` methods first; keep shell commands as manual fallback.
 
+## Patch Backend Rejects `--binary` on macOS
+
+- Symptom: `plastic_patch(...)` reports that its diff executable rejected `--binary` and names `PI_PLASTIC_PATCH_EXECUTABLE`.
+- With Plastic 11 on macOS, this is the observed result when `cm patch` uses Apple BSD `/usr/bin/diff`: that executable works for text-only diffs but rejects the patch backend's `--binary` argument.
+- Set `PI_PLASTIC_PATCH_EXECUTABLE` to a verified GNU Diffutils-compatible non-GUI executable, or pass that executable as `toolPath` for one call. Keep `PI_PLASTIC_DIFF_EXECUTABLE` configured separately for text-only review tools.
+- This is a macOS diagnostic, not validation of Windows patch backends or two-spec patch behavior; verify those locally.
+
 ## Code Review Creation Failed
 
 - Use GUI or document changeset in plan/issue tracker.

package/src/plastic-core.ts

@@ -4,8 +4,8 @@ import { spawn } from "node:child_process";
 import { tool } from "./pi-tool-compat";
 import { promises as fs, realpathSync, statSync } from "node:fs";
 import { tmpdir } from "os";
-import { dirname, extname, isAbsolute, join, relative, resolve, win32 } from "path";
-import { parsePlasticStatusBranch } from "./plastic-workspace";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, win32 } from "path";
+import { discoverPlasticWorkspace, parsePlasticSelector, parsePlasticStatusBranch } from "./plastic-workspace";
 
 type SpawnResult = {
     stdout: string;
@@ -31,6 +31,10 @@ const getCmExecutable = (): string => resolveExecutable(process.env, "PI_PLASTIC
 // `diff -u` has compatible exit semantics on Windows GNU diff and macOS BSD diff.
 // Keep the executable name configurable rather than assuming a .exe suffix or package-manager path.
 const getDiffExecutable = (): string => resolveExecutable(process.env, "PI_PLASTIC_DIFF_EXECUTABLE", "diff");
+const PLASTIC_PATCH_EXECUTABLE_ENV = "PI_PLASTIC_PATCH_EXECUTABLE";
+// Plastic's server/backend determines whether a moved item is encoded as a
+// move or as delete/add records. Do not claim either without a live fixture.
+const PATCH_MOVE_REPRESENTATION = "backend-determined" as const;
 
 const executableNotFoundError = (command: string, error: Error): Error =>
 {
@@ -1070,6 +1074,22 @@ const isSameBranchSpec = (left: string, right: string): boolean =>
     return normalizeBranchSpecForComparison(left) === normalizeBranchSpecForComparison(right);
 };
 
+const assertWorkspaceOnBranch = (actualBranch: string, expectedBranch: string, phase: string): void =>
+{
+    if (isSameBranchSpec(actualBranch, expectedBranch))
+    {
+        return;
+    }
+
+    throw new Error([
+        `Plastic workspace branch mismatch after ${phase}.`,
+        `Expected target: ${expectedBranch}`,
+        `Actual branch: ${actualBranch}`,
+        "The requested merge/checkin was not completed on the target branch.",
+        "Do not switch branches and assume the changeset moved; Plastic changesets remain on the branch where they were created. Inspect branch history and retry the merge from the actual target branch.",
+    ].join("\n"));
+};
+
 const getBranchLeafName = (branch: string): string =>
 {
     const normalized = normalizeBranchSpecForComparison(branch);
@@ -1178,16 +1198,219 @@ const assertNonBlankPatchValue = (name: keyof PatchCommandArgs, value: string |
     }
 };
 
-const resolvePatchToolPath = (toolPath?: string): string =>
+const resolvePatchToolPath = (
+    toolPath?: string,
+    environment: ExecutableEnvironment = process.env,
+    platform: NodeJS.Platform = process.platform,
+): string =>
 {
+    // A per-call path is deliberately the strongest override: callers may
+    // select a known patch-capable executable without changing process policy.
     if (toolPath?.trim())
     {
         return toolPath.trim();
     }
 
-    // Keep cm patch on the same configurable portable diff executable used by
-    // text-only file diffs. `diff` remains a PATH lookup on both platforms.
-    return getDiffExecutable();
+    const configuredPatchExecutable = environment[PLASTIC_PATCH_EXECUTABLE_ENV]?.trim();
+    if (configuredPatchExecutable)
+    {
+        return configuredPatchExecutable;
+    }
+
+    if (platform === "win32")
+    {
+        // GnuWin32 diff 2.8.7 is known to reject cm patch directory operands.
+        // Do not inherit PI_PLASTIC_DIFF_EXECUTABLE here: that setting remains
+        // for text diffs and may name the incompatible executable.
+        throw new Error(
+            "cm patch requires a patch-capable non-GUI diff executable on Windows. Set PI_PLASTIC_PATCH_EXECUTABLE to a verified tool (for example Git's diff.exe), or pass toolPath for this one call. PI_PLASTIC_DIFF_EXECUTABLE is used only for text diffs and is not a safe Windows patch default.",
+        );
+    }
+
+    // Retain the pre-existing non-Windows fallback while keeping the patch-specific
+    // environment variable authoritative. The caller must verify that the resolved
+    // executable supports the local Plastic client's patch argument contract.
+    return resolveExecutable(environment, "PI_PLASTIC_DIFF_EXECUTABLE", "diff");
+};
+
+type ResolvedPatchBranchSpecs = Pick<PatchCommandArgs, "source" | "destination">;
+
+// Repository selectors are a single cm argv value, so spaces within a repository
+// name are not shell separators. Require non-empty @-separated components without
+// edge whitespace, while retaining Plastic's valid internal spaces and punctuation.
+const isSafePatchRepositorySelector = (repository: string | undefined): repository is string =>
+{
+    if (!repository || repository !== repository.trim() || /[\u0000-\u001f\u007f-\u009f]/.test(repository))
+    {
+        return false;
+    }
+
+    return repository.split("@").every((component) => /^[^@\s](?:[^@]*[^@\s])?$/.test(component));
+};
+
+const qualifyPatchBranchSpec = (branchSpec: string, repository?: string): string =>
+{
+    const normalizedBranchSpec = branchSpec.trim();
+    if (!/^br:\/.+/i.test(normalizedBranchSpec) || normalizedBranchSpec.includes("@"))
+    {
+        return normalizedBranchSpec;
+    }
+
+    if (!isSafePatchRepositorySelector(repository))
+    {
+        throw new Error(
+            `Cannot safely qualify unqualified branch selector '${normalizedBranchSpec}' against this workspace. Use the exact repository-qualified syntax 'br:/<branch>@<repository>@<server>'.`,
+        );
+    }
+
+    return `${normalizedBranchSpec}@${repository}`;
+};
+
+const resolvePatchBranchSpecs = async (args: PatchCommandArgs, cwd: string): Promise<ResolvedPatchBranchSpecs> =>
+{
+    const branchSpecs = [args.source, args.destination].filter((value): value is string => Boolean(value && /^br:\/.+/i.test(value.trim())));
+    const needsQualification = branchSpecs.some((value) => !value.includes("@"));
+    if (!needsQualification)
+    {
+        return { source: args.source.trim(), ...(args.destination ? { destination: args.destination.trim() } : {}) };
+    }
+
+    const workspace = await discoverPlasticWorkspace(cwd);
+    if (workspace.kind !== "found")
+    {
+        throw new Error("Cannot safely qualify an unqualified branch selector because the current Plastic workspace repository is unavailable. Use exact repository-qualified syntax 'br:/<branch>@<repository>@<server>'.");
+    }
+
+    const selectorText = await fs.readFile(join(workspace.value.plasticDir, "plastic.selector"), "utf8").catch(() => undefined);
+    const selector = selectorText === undefined ? { kind: "not_found" as const } : parsePlasticSelector(selectorText);
+    const repository = selector.kind === "found" ? selector.value.repository : undefined;
+    return {
+        source: qualifyPatchBranchSpec(args.source, repository),
+        ...(args.destination ? { destination: qualifyPatchBranchSpec(args.destination, repository) } : {}),
+    };
+};
+
+type PatchOutputStaging = {
+    requestedOutput: string;
+    stagingOutput: string;
+    cleanup: () => Promise<void>;
+};
+
+const ensurePatchOutputDoesNotExist = async (requestedOutput: string): Promise<void> =>
+{
+    const existing = await fs.lstat(requestedOutput).catch((error: unknown) =>
+    {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+        throw error;
+    });
+    if (existing)
+    {
+        throw new Error(`Refusing to overwrite existing patch output '${requestedOutput}'. Choose a new output path.`);
+    }
+};
+
+const createPatchOutputStaging = async (requestedOutput: string): Promise<PatchOutputStaging> =>
+{
+    await ensurePatchOutputDoesNotExist(requestedOutput);
+    let stagingDirectory: string;
+    try
+    {
+        stagingDirectory = await fs.mkdtemp(join(dirname(requestedOutput), ".pi-plastic-patch-"));
+    }
+    catch (error)
+    {
+        throw new Error(`Cannot create package-owned patch staging beside '${requestedOutput}'. Ensure its parent directory exists and is writable. ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    return {
+        requestedOutput,
+        stagingOutput: join(stagingDirectory, "patch-output"),
+        cleanup: async () => fs.rm(stagingDirectory, { recursive: true, force: true }),
+    };
+};
+
+const validatePatchStagingOutput = async (stagingOutput: string, requireContent = false): Promise<void> =>
+{
+    const patchStat = await fs.lstat(stagingOutput).catch(() => null);
+    if (!patchStat?.isFile())
+    {
+        throw new Error("Plastic reported patch generation success but did not create package-owned staging output.");
+    }
+    if (requireContent && patchStat.size === 0)
+    {
+        // An omitted output may intentionally report an empty patch. A caller
+        // who requested a file, however, must never receive a zero-byte file
+        // that is indistinguishable from a failed/truncated backend outcome.
+        throw new Error("Refusing to publish an empty patch output. Plastic produced no patch bytes; rerun without output to inspect the empty result or verify the patch backend.");
+    }
+};
+
+// Creating a hard link is atomic and fails if the requested path appeared
+// after our preflight. Unlike rename(), it can never replace an existing file.
+const publishPatchOutput = async (stagingOutput: string, requestedOutput: string): Promise<void> =>
+{
+    await validatePatchStagingOutput(stagingOutput, true);
+    try
+    {
+        await fs.link(stagingOutput, requestedOutput);
+    }
+    catch (error)
+    {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code === "EEXIST")
+        {
+            throw new Error(`Refusing to overwrite existing patch output '${requestedOutput}'. Choose a new output path.`);
+        }
+        throw new Error(`Could not atomically publish patch output '${requestedOutput}'. ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
+
+const runPatchOutputTransaction = async (requestedOutput: string, generate: (stagingOutput: string) => Promise<void>): Promise<void> =>
+{
+    const staging = await createPatchOutputStaging(requestedOutput);
+    try
+    {
+        await generate(staging.stagingOutput);
+        await publishPatchOutput(staging.stagingOutput, staging.requestedOutput);
+    }
+    finally
+    {
+        await staging.cleanup();
+    }
+};
+
+const redactPatchStagingOutput = (message: string, stagingOutput: string): string =>
+{
+    const stagingPaths = new Set([stagingOutput]);
+    try
+    {
+        // macOS commonly exposes /var through the canonical /private/var path.
+        // cm may report the latter even though it received the former.
+        stagingPaths.add(join(realpathSync.native(dirname(stagingOutput)), basename(stagingOutput)));
+    }
+    catch
+    {
+        // The staging parent normally exists; retain raw-path redaction if it does not.
+    }
+
+    return Array.from(stagingPaths)
+        .sort((left, right) => right.length - left.length)
+        .reduce((redacted, path) => redacted.split(path).join("<package-owned-staging-file>"), message);
+};
+
+const withPatchBackendContractDiagnostic = (error: unknown, toolPath: string, stagingOutput: string): Error =>
+{
+    const message = redactPatchStagingOutput(error instanceof Error ? error.message : String(error), stagingOutput);
+    // Plastic 11 on macOS invokes its patch backend with --binary. Apple's BSD
+    // /usr/bin/diff rejects that flag, while GNU diffutils accepts it. Detect
+    // the observed contract failure instead of guessing from a path or OS.
+    if (/unrecognized option [`']?--binary/i.test(message))
+    {
+        return new Error(
+            `${message}\n\nPlastic patch requires a diff executable that accepts --binary. '${toolPath}' rejected that argument. Configure PI_PLASTIC_PATCH_EXECUTABLE (or this call's toolPath) to a verified GNU diffutils-compatible non-GUI diff executable. Text diff configuration is independent; Apple BSD diff may still be used for text-only diffs.`,
+        );
+    }
+    return new Error(message);
 };
 
 const buildPatchCommandArgs = (args: PatchCommandArgs): string[] =>
@@ -1238,6 +1461,13 @@ export const __plasticProcessInternals = {
 export const __plasticPatchInternals = {
     buildPatchCommandArgs,
     resolvePatchToolPath,
+    qualifyPatchBranchSpec,
+    resolvePatchBranchSpecs,
+    createPatchOutputStaging,
+    publishPatchOutput,
+    runPatchOutputTransaction,
+    withPatchBackendContractDiagnostic,
+    PATCH_MOVE_REPRESENTATION,
 };
 
 export const __plasticCheckinInternals = {
@@ -1265,6 +1495,7 @@ export const __plasticSwitchInternals = {
     toLegacyPendingSummary,
     normalizeBranchSpecForComparison,
     isSameBranchSpec,
+    assertWorkspaceOnBranch,
     buildSwitchPendingProfile,
     isSwitchBringBlockedForUnattended,
     canSwitchDirectWithPrivateOnlyPending,
@@ -1333,7 +1564,7 @@ const boundDiffOutput = (output: string): Pick<TextDiffResult, "output" | "trunc
 const runPortableTextDiff = async (
     leftPath: string,
     rightPath: string,
-    cwd: string,
+    _cwd: string,
     leftLabel: string,
     rightLabel: string,
 ): Promise<TextDiffResult> =>
@@ -1344,36 +1575,54 @@ const runPortableTextDiff = async (
         return { backend: "diff", changed: !leftContent.equals(rightContent), binary: true, output: "", truncated: false, totalChars: 0 };
     }
 
-    const { stdout, stderr, exitCode, aborted, stdoutTruncated, stdoutTotalChars } = await spawnAndCollect(
-        getDiffExecutable(),
-        ["-u", leftPath, rightPath],
-        cwd,
-        undefined,
-        getActiveAbortSignal(),
-        { ...commandExecutionStorage.getStore(), outputLimitChars: DIFF_OUTPUT_MAX_CHARS },
-    );
-    if (aborted)
+    // Do not pass either workspace or historical source paths to diff: a
+    // Unicode workspace path reproduces an Invalid argument failure in the
+    // configured Windows GnuWin32 backend. Labels intentionally stay out of
+    // argv and are restored by stableDiffHeaders below.
+    const materializationDir = await createAsciiTempDirectory("pi-plastic-diff-");
+    const materializedLeftPath = join(materializationDir, `left${safeTempExtension(leftPath)}`);
+    const materializedRightPath = join(materializationDir, `right${safeTempExtension(rightPath)}`);
+    try
     {
-        throw new Error("Text diff was aborted.");
+        await Promise.all([
+            fs.writeFile(materializedLeftPath, leftContent),
+            fs.writeFile(materializedRightPath, rightContent),
+        ]);
+        const { stdout, stderr, exitCode, aborted, stdoutTruncated, stdoutTotalChars } = await spawnAndCollect(
+            getDiffExecutable(),
+            ["-u", materializedLeftPath, materializedRightPath],
+            materializationDir,
+            undefined,
+            getActiveAbortSignal(),
+            { ...commandExecutionStorage.getStore(), outputLimitChars: DIFF_OUTPUT_MAX_CHARS },
+        );
+        if (aborted)
+        {
+            throw new Error("Text diff was aborted.");
+        }
+        if (exitCode > 1)
+        {
+            const diagnostic = [stdout, stderr].filter(Boolean).join("\n").trim();
+            const sanitized = diagnostic
+                .split(materializedLeftPath).join(leftLabel)
+                .split(materializedRightPath).join(rightLabel);
+            throw new Error(sanitized || `Text diff failed with exit code ${exitCode}.`);
+        }
+
+        const normalized = stableDiffHeaders(stdout, leftLabel, rightLabel);
+        const bounded = stdoutTruncated
+            ? {
+                output: `${normalized}\n\n[Diff output truncated at ${DIFF_OUTPUT_MAX_CHARS} characters; inspect a narrower file or generate a review patch for the complete change.]`,
+                truncated: true,
+                totalChars: stdoutTotalChars ?? normalized.length,
+            }
+            : boundDiffOutput(normalized);
+        return { backend: "diff", changed: exitCode === 1, binary: false, ...bounded };
     }
-    if (exitCode > 1)
+    finally
     {
-        const diagnostic = [stdout, stderr].filter(Boolean).join("\n").trim();
-        const sanitized = diagnostic
-            .split(leftPath).join(leftLabel)
-            .split(rightPath).join(rightLabel);
-        throw new Error(sanitized || `Text diff failed with exit code ${exitCode}.`);
+        await fs.rm(materializationDir, { recursive: true, force: true });
     }
-
-    const normalized = stableDiffHeaders(stdout, leftLabel, rightLabel);
-    const bounded = stdoutTruncated
-        ? {
-            output: `${normalized}\n\n[Diff output truncated at ${DIFF_OUTPUT_MAX_CHARS} characters; inspect a narrower file or generate a review patch for the complete change.]`,
-            truncated: true,
-            totalChars: stdoutTotalChars ?? normalized.length,
-        }
-        : boundDiffOutput(normalized);
-    return { backend: "diff", changed: exitCode === 1, binary: false, ...bounded };
 };
 
 const safeTempExtension = (pathValue: string): string =>
@@ -1382,6 +1631,20 @@ const safeTempExtension = (pathValue: string): string =>
     return /^\.[A-Za-z0-9]{1,12}$/.test(extension) ? extension : ".tmp";
 };
 
+const isAsciiPath = (pathValue: string): boolean => /^[\x20-\x7e]*$/.test(pathValue);
+
+// GnuWin32 diff cannot reliably accept Unicode operands. Keep every package
+// materialization path ASCII-only; labels are restored after the backend exits.
+const createAsciiTempDirectory = async (prefix: string): Promise<string> =>
+{
+    const temporaryRoot = tmpdir();
+    if (!isAsciiPath(temporaryRoot))
+    {
+        throw new Error("Text diff requires an ASCII-safe temporary directory because the configured backend cannot reliably accept Unicode paths. Set TEMP and TMP to a writable ASCII-only path.");
+    }
+    return fs.mkdtemp(join(temporaryRoot, prefix));
+};
+
 const materializeRevision = async (revision: string, destination: string, workdir?: string): Promise<void> =>
 {
     // --file keeps historical bytes out of the decoded stdout path. This is
@@ -1389,17 +1652,20 @@ const materializeRevision = async (revision: string, destination: string, workdi
     try
     {
         await runCm(["cat", revision, `--file=${destination}`], workdir);
+        const destinationStat = await fs.stat(destination).catch(() => null);
+        if (!destinationStat?.isFile())
+        {
+            throw new Error("Plastic did not materialize the requested historical file content.");
+        }
     }
     catch (error)
     {
+        // cm cat --file can leave a zero-byte output on failure. The destination
+        // is package-owned, so remove it before surfacing a sanitized diagnostic.
+        await fs.rm(destination, { force: true }).catch(() => undefined);
         const message = error instanceof Error ? error.message : String(error);
         throw new Error(message.split(destination).join("<package-owned-temp-file>"));
     }
-    const destinationStat = await fs.stat(destination).catch(() => null);
-    if (!destinationStat?.isFile())
-    {
-        throw new Error("Plastic did not materialize the requested historical file content.");
-    }
 };
 
 const normalizeDiffResponseMaxChars = (value: unknown): number =>
@@ -1422,10 +1688,10 @@ const formatTextDiff = async (
 ): Promise<string> =>
 {
     const result = boundTextDiffResult(unboundedResult, normalizeDiffResponseMaxChars(maxChars));
-    const status = result.binary ? (result.changed ? "binary-different" : "unchanged") : (result.changed ? "changed" : "unchanged");
+    const status = result.binary ? (result.changed ? "binary-different" : "unchanged") : (result.changed ? "changed" : (comparisonKind === "workspace-added" ? "added-empty" : "unchanged"));
     const text = result.binary
         ? (result.changed ? "Binary content differs; a text diff is unavailable." : "No differences.")
-        : (result.changed ? result.output : "No differences.");
+        : (result.changed ? result.output : (status === "added-empty" ? "Added file is empty; no text diff hunks." : "No differences."));
     const data = {
         comparisonKind,
         ...comparisonMetadata,
@@ -1497,6 +1763,8 @@ export const __plasticDiffInternals = {
     boundDiffOutput,
     runPortableTextDiff,
     safeTempExtension,
+    isAsciiPath,
+    createAsciiTempDirectory,
     materializeRevision,
     isNoDataError,
     withWorkspaceBaseUnavailableDiagnostic,
@@ -2675,44 +2943,76 @@ export const diff = tool({
 });
 
 export const patch = tool({
-    description: "Generate a Plastic SCM patch with the configured portable diff backend and optional clean/integration filtering (cm patch).",
+    description: "Generate a Plastic SCM review patch with a patch-specific non-GUI diff backend; branch selectors are qualified to the current workspace repository and requested outputs publish atomically without overwrite (cm patch).",
     args: {
-        source: tool.schema.string().min(1).describe("Source changeset or branch spec, for example a changeset spec or branch spec selected from the current workspace."),
+        source: tool.schema.string().min(1).describe("Source changeset or branch spec. Unqualified br:/ selectors are qualified only from the exact current workspace repository."),
         destination: tool.schema.string().optional().describe("Optional second changeset or branch spec for two-spec patch generation."),
-        output: tool.schema.string().optional().describe("Optional output file path. If omitted, patch content is printed to stdout."),
-        toolPath: tool.schema.string().optional().describe("Optional path to the diff executable used by cm patch. Defaults to PI_PLASTIC_DIFF_EXECUTABLE or diff on PATH."),
+        output: tool.schema.string().optional().describe("Optional new output file path. The package stages then atomically publishes it and refuses any existing path. If omitted, patch content is returned."),
+        toolPath: tool.schema.string().optional().describe("Optional patch-capable non-GUI diff executable for this call (highest priority). Otherwise use PI_PLASTIC_PATCH_EXECUTABLE; non-Windows falls back to PI_PLASTIC_DIFF_EXECUTABLE/diff, which must support the local Plastic patch argument contract."),
         clean: tool.schema.boolean().optional().describe("Exclude content that arrived via merges and include only direct checkins."),
         integration: tool.schema.boolean().optional().describe("Show branch changes pending integration into the parent branch."),
         workdir: workdirArg,
     },
     async execute(args)
     {
+        // Validate before staging or launching any process, including direct
+        // callers that bypass the TypeBox schema layer.
+        assertRequiredPatchValue("source", args.source);
+        assertNonBlankPatchValue("destination", args.destination);
+        assertNonBlankPatchValue("output", args.output);
+        assertNonBlankPatchValue("toolPath", args.toolPath);
+
         const cwd = args.workdir ?? process.cwd();
-        const tempDir = args.output ? null : await fs.mkdtemp(join(tmpdir(), "plastic-patch-"));
-        const requestedOutput = args.output ?? join(tempDir!, "review.patch");
-        const resolvedOutput = isAbsolute(requestedOutput) ? requestedOutput : resolve(cwd, requestedOutput);
+        const toolPath = resolvePatchToolPath(args.toolPath);
+        const branchSpecs = await resolvePatchBranchSpecs(args, cwd);
+        const temporaryOutputDirectory = args.output ? null : await fs.mkdtemp(join(tmpdir(), "plastic-patch-"));
+        const requestedOutput = args.output
+            ? (isAbsolute(args.output) ? args.output : resolve(cwd, args.output))
+            : join(temporaryOutputDirectory!, "review.patch");
+        let commandOutput = "";
+
+        const generate = async (stagingOutput: string): Promise<void> =>
+        {
+            const cmdArgs = buildPatchCommandArgs({
+                ...args,
+                ...branchSpecs,
+                output: stagingOutput,
+                toolPath,
+            });
+            try
+            {
+                commandOutput = await runCm(cmdArgs, args.workdir);
+            }
+            catch (error)
+            {
+                throw withPatchBackendContractDiagnostic(error, toolPath, stagingOutput);
+            }
+            await validatePatchStagingOutput(stagingOutput);
+        };
 
         try
         {
-            const cmdArgs = buildPatchCommandArgs({ ...args, output: requestedOutput, toolPath: resolvePatchToolPath(args.toolPath) });
-            const commandOutput = await runCm(cmdArgs, args.workdir);
-            const patchStat = await fs.stat(resolvedOutput).catch(() => null);
-            if (!patchStat?.isFile())
+            if (args.output)
             {
-                throw new Error(`Plastic reported patch generation success but did not create '${requestedOutput}'.`);
+                await runPatchOutputTransaction(requestedOutput, generate);
+            }
+            else
+            {
+                await generate(requestedOutput);
             }
 
-            const patchBytes = await fs.readFile(resolvedOutput);
+            const patchBytes = await fs.readFile(requestedOutput);
             const isText = isUtf8(patchBytes);
             const patchText = isText ? patchBytes.toString("utf8") : "";
             const bounded = boundDiffOutput(patchText);
             const binaryLimited = /Binary files? .* differ|cannot diff|binary (?:content|file) (?:is )?not supported/i.test(`${patchText}\n${commandOutput}`);
             const metadata = {
                 status: patchBytes.length === 0 ? "empty" : (binaryLimited ? "generated-with-binary-warning" : "generated"),
-                output: args.output ? requestedOutput : null,
+                output: args.output ? args.output : null,
                 bytes: patchBytes.length,
                 empty: patchBytes.length === 0,
                 binaryLimited: !isText || binaryLimited,
+                moveRepresentation: PATCH_MOVE_REPRESENTATION,
                 truncated: !args.output && bounded.truncated,
                 content: args.output ? null : bounded.output,
             };
@@ -2720,9 +3020,9 @@ export const patch = tool({
         }
         finally
         {
-            if (tempDir)
+            if (temporaryOutputDirectory)
             {
-                await fs.rm(tempDir, { recursive: true, force: true });
+                await fs.rm(temporaryOutputDirectory, { recursive: true, force: true });
             }
         }
     },
@@ -2747,7 +3047,7 @@ export const diffRevisions = tool({
         const cwd = args.workdir ?? process.cwd();
         const leftLabel = args.leftRevision.includes("#") ? args.leftRevision.replace("#", "@") : args.leftRevision;
         const rightLabel = args.rightRevision.includes("#") ? args.rightRevision.replace("#", "@") : args.rightRevision;
-        const tempDir = await fs.mkdtemp(join(tmpdir(), "plastic-core-"));
+        const tempDir = await createAsciiTempDirectory("plastic-core-");
         const leftPath = join(tempDir, `left${safeTempExtension(args.leftRevision)}`);
         const rightPath = join(tempDir, `right${safeTempExtension(args.rightRevision)}`);
 
@@ -2807,7 +3107,7 @@ const diffPendingWorkspaceFile = async (
         throw new Error(`Plastic status identified '${args.path}' as deleted but did not provide its base revision ID.`);
     }
 
-    const tempDir = await fs.mkdtemp(join(tmpdir(), "plastic-core-"));
+    const tempDir = await createAsciiTempDirectory("plastic-core-");
     const basePath = join(tempDir, `base${safeTempExtension(workspacePath)}`);
     const emptyWorkspacePath = join(tempDir, `workspace${safeTempExtension(workspacePath)}`);
     try
@@ -2876,7 +3176,7 @@ export const diffFile = tool({
             }
             const displayPath = isAbsolute(args.path) ? toCommandPath(workspacePath, cwd) : args.path;
             const revision = resolveDiffFileRevision(displayPath || args.path, args.revision);
-            const tempDir = await fs.mkdtemp(join(tmpdir(), "plastic-core-"));
+            const tempDir = await createAsciiTempDirectory("plastic-core-");
             const basePath = join(tempDir, `base${safeTempExtension(workspacePath)}`);
             try
             {
@@ -3123,10 +3423,10 @@ export const workspaceDiff = tool({
                 const remaining = Math.max(0, WORKSPACE_DIFF_CONTENT_MAX_CHARS - totalOutputChars);
                 const perFile = boundWorkspaceDiffResult(compared.result, maxChars);
                 const bounded = boundWorkspaceDiffResult(perFile, remaining);
-                const status = bounded.binary ? (bounded.changed ? "binary-different" : "unchanged") : (bounded.changed ? "changed" : "unchanged");
+                const status = bounded.binary ? (bounded.changed ? "binary-different" : "unchanged") : (bounded.changed ? "changed" : (compared.comparisonKind === "workspace-added" ? "added-empty" : "unchanged"));
                 const diffOutput = bounded.changed && !bounded.binary ? bounded.output : undefined;
-                outcomes.push({ path: displayPath, kind: item.kind, status, changed: bounded.changed, binary: bounded.binary, truncated: bounded.truncated, totalChars: bounded.totalChars, ...(diffOutput ? { diff: diffOutput } : {}) });
-                const body = bounded.binary ? (bounded.changed ? "Binary content differs; a text diff is unavailable." : "No differences.") : (bounded.changed ? bounded.output : "No differences.");
+                outcomes.push({ path: displayPath, kind: item.kind, comparisonKind: compared.comparisonKind, status, changed: bounded.changed, binary: bounded.binary, truncated: bounded.truncated, totalChars: bounded.totalChars, ...(diffOutput ? { diff: diffOutput } : {}) });
+                const body = bounded.binary ? (bounded.changed ? "Binary content differs; a text diff is unavailable." : "No differences.") : (bounded.changed ? bounded.output : (status === "added-empty" ? "Added file is empty; no text diff hunks." : "No differences."));
                 const section = `### ${displayPath} (${item.kind})\n${body}`;
                 textSections.push(section);
                 totalOutputChars += section.length;
@@ -3338,6 +3638,7 @@ export const switchBranch = tool({
 
             const output = await runCm(switchCmd, args.workdir);
             const branchAfter = await resolveCurrentBranchName(args.workdir);
+            assertWorkspaceOnBranch(branchAfter, args.branch, "cm switch");
             return toStructuredResult(
                 "switch-branch",
                 format,
@@ -3398,6 +3699,7 @@ export const switchBranch = tool({
 
             const output = await runCm(switchCmd, args.workdir);
             const branchAfter = await resolveCurrentBranchName(args.workdir);
+            assertWorkspaceOnBranch(branchAfter, args.branch, "cm switch with private-only pending items");
             return toStructuredResult(
                 "switch-branch",
                 format,
@@ -3569,6 +3871,7 @@ export const switchBranch = tool({
 
         const switchOutput = await runCm(switchCmd, args.workdir);
         const branchAfter = await resolveCurrentBranchName(args.workdir).catch(() => branchBefore);
+        assertWorkspaceOnBranch(branchAfter, args.branch, "cm switch after shelving");
 
         return toStructuredResult(
             "switch-branch",
@@ -3860,6 +4163,8 @@ export const mergeToBranch = tool({
             workdir: args.workdir,
         });
         const updateResult = updateTarget ? await update.execute({ workdir: args.workdir }) : "(skipped)";
+        const branchBeforeMerge = await resolveCurrentBranchName(args.workdir);
+        assertWorkspaceOnBranch(branchBeforeMerge, targetBranch, "target update and before merge");
         const mergeResult = await merge.execute({
             source: sourceBranch,
             strategy,
@@ -3898,6 +4203,9 @@ export const mergeToBranch = tool({
             );
         }
 
+        const branchBeforeCheckin = await resolveCurrentBranchName(args.workdir);
+        assertWorkspaceOnBranch(branchBeforeCheckin, targetBranch, "merge and before checkin");
+
         const preflightResult = await checkin.execute({
             message: checkinMessage,
             includeAll: true,
@@ -3914,6 +4222,7 @@ export const mergeToBranch = tool({
             workdir: args.workdir,
         });
         const finalBranch = await resolveCurrentBranchName(args.workdir);
+        assertWorkspaceOnBranch(finalBranch, targetBranch, "merge checkin");
         const finalShortStatus = await runCmRaw(["status", "--short"], args.workdir).catch(() => "");
         const finalPendingSummary = summarizeShortStatus(finalShortStatus);
 

package/src/plastic-tool-loading.ts

@@ -33,7 +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_mergeToBranch", aliases: ["merge to branch", "close branch", "merge closeout"], tags: ["merge", "branch", "closeout"], guidance: ["Confirm source and target branches before the non-interactive merge closeout flow."] },
+  { 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."] },
   { name: "plastic_branchList", aliases: ["list branches", "find branch", "branches"], tags: ["branch", "inspect", "query"], guidance: ["Use the returned full branch paths when selecting a branch for another operation."] },

package/src/plastic-workspace.ts

@@ -78,7 +78,8 @@ const parseSelectorValue = (line: string, key: string): string | undefined => {
 /** Parse the local selector without treating it as proof that a workspace exists. */
 export function parsePlasticSelector(content: string): ParseOutcome<PlasticSelector> {
   let repository: string | undefined;
-  let branch: string | undefined;
+  let smartBranch: string | undefined;
+  let explicitBranch: string | undefined;
   let sawBranchKey = false;
 
   for (const line of content.split(/\r?\n/)) {
@@ -86,13 +87,18 @@ export function parsePlasticSelector(content: string): ParseOutcome<PlasticSelec
     if (/^\s*repository(?:\s|$)/i.test(line)) repository = parseSelectorValue(line, "repository");
     if (/^\s*smartbranch(?:\s|$)/i.test(line)) {
       sawBranchKey = true;
-      branch = parseSelectorValue(line, "smartbranch");
+      smartBranch = parseSelectorValue(line, "smartbranch");
+    }
+    if (/^\s*br(?:\s|$)/i.test(line)) {
+      sawBranchKey = true;
+      explicitBranch = parseSelectorValue(line, "br");
     }
   }
 
   if (!sawBranchKey) return { kind: "not_found" };
+  const branch = smartBranch ?? explicitBranch;
   if (!branch || /[\u0000-\u001f\u007f]/.test(branch)) {
-    return { kind: "malformed", reason: "Selector smartbranch is blank or contains control characters." };
+    return { kind: "malformed", reason: "Selector branch is blank or contains control characters." };
   }
 
   return {

package/CONTRIBUTING.md

@@ -1,88 +0,0 @@
-# Contributing
-
-Thanks for improving Pi Plastic.
-
-## Prerequisites
-
-- Node.js 22.19.0 or newer
-- npm
-- Plastic SCM / Unity Version Control CLI for opt-in live validation
-- Git for the text-only diff tools
-
-## Setup
-
-```bash
-npm ci --ignore-scripts --no-audit --no-fund
-npm test
-```
-
-The default suite is credential-free. Keep it that way. Tests that require Plastic access must remain explicitly opt-in and target a dedicated disposable workspace.
-
-## Making changes
-
-- Keep public tool names and output shapes stable unless the change intentionally documents a breaking release.
-- Preserve built-in and foreign-extension tools when changing active-tool composition.
-- Do not weaken confirmation, preflight, path, process, or mutation safeguards.
-- Add focused regression coverage for behavior changes.
-- Update README documentation when user-facing behavior changes.
-- Keep unreleased user-visible changes under `## Unreleased` in `CHANGELOG.md` during ordinary development.
-- Do not bump the package version for every implementation commit. Convert the accumulated Unreleased section into one dated SemVer release only when preparing a release.
-
-## Validation
-
-Run:
-
-```bash
-npm test
-npm run eval:tool-loading -- --dry-run
-npm pack --dry-run
-```
-
-Review the tarball list for machine-specific paths, credentials, raw provider payloads, generated results, and unrelated files.
-
-Plastic live tests are intentionally local-only. This project has no shared Plastic Cloud account or CI credentials, and contributors must authenticate `cm` with their own account and use a repository they are authorized to modify. Never add Plastic credentials, tokens, cloud organization details, or private repository data to tests, fixtures, logs, pull requests, or GitHub Actions.
-
-For an opt-in read-only Plastic smoke test:
-
-```bash
-PI_PLASTIC_TEST_WORKSPACE=/absolute/path/to/dedicated/sandbox npm run test:live
-```
-
-For branch-creation behavior, use the opt-in mutation test only against a clean, dedicated disposable repository:
-
-```bash
-PI_PLASTIC_TEST_WORKSPACE=/absolute/path/to/dedicated/sandbox \
-PI_PLASTIC_ALLOW_MUTATION_TESTS=true \
-npm run test:live:branch-create
-```
-
-The mutation test creates uniquely named hierarchical branches, verifies explicit-parent behavior and the top-level guard, does not switch the workspace, and removes temporary branches in cleanup.
-
-### Behavior completion gate
-
-When a change modifies how a `plastic_*` tool invokes or interprets real Plastic behavior:
-
-1. Add or update credential-free regression coverage for policy, parsing, and command construction.
-2. Locally run the narrowest relevant opt-in live test in a clean disposable Plastic repository using the contributor's own authenticated account.
-3. Verify the workspace state and temporary-resource cleanup afterward.
-4. Report the exact live test and that an authenticated disposable repository was used, without exposing account, organization, server, credential, or private repository details.
-
-GitHub Actions is not expected to run Plastic live tests. If local authenticated validation is unavailable, describe the work as implemented with live validation pending; do not claim the behavior is done or verified. Documentation-only and purely internal changes may mark live validation as not applicable with a reason.
-
-Follow `evals/tool-loading/README.md` before any live model evaluation. Never use an ordinary production workspace for mutation testing.
-
-## Pull requests
-
-Keep pull requests focused. Describe:
-
-- the behavior changed;
-- safety or compatibility considerations;
-- tests and environments actually run;
-- checks intentionally skipped;
-- relevant before/after metadata or latency measurements for loader changes.
-
-Do not include secrets, account data, private repository content, or raw provider captures.
-
-## Security reports
-
-Follow [SECURITY.md](SECURITY.md) instead of opening a public issue for vulnerabilities.