@aefree/pi-plastic 0.7.5 → 0.8.0

package/src/plastic-renderers.ts

@@ -13,8 +13,7 @@ const separator = " \u00b7 ";
 
 const titles: Record<string, string> = {
   status: "Status", currentBranch: "Current branch", update: "Update", add: "Add", checkin: "Check in", undo: "Undo",
-  resolveDeleteChangeConflict: "Resolve deletion", diff: "Diff (disabled)", patch: "Review patch", diffRevisions: "Revision diff",
-  diffFile: "File diff", workspaceDiff: "Workspace diff", branchCreate: "Create branch", switchBranch: "Switch branch",
+  resolveDeleteChangeConflict: "Resolve deletion", diff: "Diff", patch: "Review patch", branchCreate: "Create branch", switchBranch: "Switch branch",
   merge: "Merge", mergeBranches: "Server merge", mergeToBranch: "Merge and check in", finalizeMerge: "Finalize merge",
   branchList: "Branches", branchExists: "Branch exists", branchDelete: "Delete branch", shelvesetCreate: "Create shelveset",
   shelvesetApply: "Apply shelveset", shelvesetDelete: "Delete shelveset", shelvesetList: "Shelvesets",
@@ -60,10 +59,10 @@ function list(value: unknown): string {
 }
 function target(name: string, args: Args): string {
   if (name === "tool_search") return list(args.toolNames) || scalar(args.query) || "Browse capabilities";
-  if (name === "diffRevisions") return `${scalar(args.leftRevision) || "..."} -> ${scalar(args.rightRevision) || "..."}`;
+  if (name === "diff" && args.mode === "revisions") return `${scalar(args.leftRevision) || "..."} -> ${scalar(args.rightRevision) || "..."}`;
   if (name === "mergeBranches" || name === "mergeToBranch") return `${scalar(args.source) || "..."} -> ${scalar(args.target) || "parent branch"}`;
-  if (name === "patch" || name === "diff") return [scalar(args.source), scalar(args.destination)].filter(Boolean).join(" -> ");
-  if (name === "diffFile") return [scalar(args.path), args.revision ? `vs ${scalar(args.revision)}` : "vs workspace base"].join(" ");
+  if (name === "patch") return [scalar(args.source), scalar(args.destination)].filter(Boolean).join(" -> ");
+  if (name === "diff" && args.mode === "file") return [scalar(args.path), args.revision ? `vs ${scalar(args.revision)}` : "vs workspace base"].join(" ");
   return scalar(args.branch) || scalar(args.source) || scalar(args.path) || list(args.paths) || scalar(args.shelveset)
     || list(args.ids) || scalar(args.id) || scalar(args.target) || scalar(args.nameLike) || scalar(args.titleLike)
     || (args.allPending === true ? "All pending files" : "");
@@ -73,7 +72,8 @@ export function renderPlasticCall(name: string, input: unknown, theme: RenderThe
   const args = record(input);
   const workdir = scalar(args.workdir) || context?.cwd || "";
   const workspace = name === "mergeBranches" ? "server" : workdir.replace(/[\\/]+$/, "").split(/[\\/]/).pop();
-  let text = theme.fg("toolTitle", theme.bold(`Plastic${separator}${titles[name] ?? name}`));
+  const title=name==="diff" ? args.mode==="file"?"File diff":args.mode==="revisions"?"Revision diff":args.mode==="workspace"?"Workspace diff":"Diff" : titles[name] ?? name;
+  let text = theme.fg("toolTitle", theme.bold(`Plastic${separator}${title}`));
   if (workspace && name !== "tool_search") text += theme.fg("dim", `  ${compact(workspace, 60)}`);
   if (args.preflight === true) text += theme.fg("warning", `${separator}preview`);
   const subtitle = target(name, args);
@@ -82,6 +82,8 @@ export function renderPlasticCall(name: string, input: unknown, theme: RenderThe
 }
 
 function payload(result: Result, raw: string): Record<string, unknown> {
+  const structured = record((result as Result & {structuredContent?:unknown}).structuredContent);
+  if (["shelveset-create","shelveset-apply","code-review-create","code-review-update"].includes(scalar(structured.action)) || structured.action === "patch" || structured.action === "diff" || structured.action === "merge-branches" || structured.action === "checkin" || structured.action === "branch-create" || structured.action === "switch-branch" || structured.action === "update" || structured.action === "add" || structured.action === "undo" || structured.action === "resolve-delete-change-conflict" || structured.action === "merge" || structured.action === "finalize-merge" || structured.action === "merge-to-branch" || structured.action === "branch-delete" || structured.action === "shelveset-delete" || structured.action === "code-review-delete") return structured;
   const rawResult = record(result.details).rawResult;
   if (rawResult !== null && typeof rawResult === "object") return record(rawResult);
   // Only decode the package's whole JSON envelope, never a JSON fragment in CLI or diff output.
@@ -109,33 +111,104 @@ function summarize(name: string, result: Result, raw: string, context?: Context)
   const notices = strings(envelope.warnings);
   const summary: Summary = { label: "Result returned", tone: "toolOutput", notices, rows: [] };
   const textLines = raw.split(/\r?\n/).filter(line => line.trim());
-  const preview = record(context?.args).preflight === true || action.endsWith("-preflight") || envelope.outcome === "preflight";
-  if (context?.isError) {
+  const preview = !["update", "add", "undo", "resolve-delete-change-conflict", "merge", "finalize-merge", "merge-to-branch", "branch-delete", "shelveset-delete", "code-review-delete", "patch","shelveset-create","shelveset-apply","code-review-create","code-review-update"].includes(action) && (record(context?.args).preflight === true || action.endsWith("-preflight") || envelope.outcome === "preflight");
+  if (context?.isError && !(name === "diff" && Array.isArray(data.outcomes)) && !(name === "mergeBranches" && action === "merge-branches") && !["checkin", "branch-create", "switch-branch", "update", "add", "undo", "resolve-delete-change-conflict", "merge", "finalize-merge", "merge-to-branch", "branch-delete", "shelveset-delete", "code-review-delete", "patch","shelveset-create","shelveset-apply","code-review-create","code-review-update"].includes(action)) {
     summary.label = "Failed";
     summary.tone = "error";
     summary.rows = textLines.slice(0, 3);
     return summary;
   }
-  if (preview) {
+  if (["shelveset-create","shelveset-apply","code-review-create","code-review-update"].includes(action)) {
+    summary.label = `Object write: ${scalar(envelope.outcome)}`;
+    summary.tone = envelope.ok === false ? "error" : "warning";
+    summary.rows = [`Attempt: ${scalar(record(data.attempt).state)}`, `Effect: ${scalar(data.effect)}`, `Emitted identity: ${scalar(record(data.observedCreatedIdentity).value) || "unobserved"}`];
+    if (envelope.ok === false) notices.unshift(scalar(record(envelope.error).message));
+    notices.push(envelope.outcome === "preflight" ? "Command-only preview; no conflict/state analysis." : "Applied items, requested review state, repository scope and rollback remain unverified.");
+  } else if (name === "patch" && action === "patch") {
+    summary.label = `Patch: ${scalar(envelope.outcome)}`;
+    summary.tone = envelope.ok === false ? "error" : "warning";
+    summary.rows = [`Effect: ${scalar(data.effect)}`, `Publication: ${scalar(data.publication)}`, `Cleanup: ${scalar(data.cleanup)}`, `Observed bytes: ${count(record(data.artifact).bytes) ?? "unknown"}`];
+    if (envelope.ok === false) notices.unshift(scalar(record(envelope.error).message));
+    notices.push("Generation only; workspace effects, move encoding and rollback unverified.");
+  } else if ((name === "shelvesetDelete" && action === "shelveset-delete") || (name === "codeReviewDelete" && action === "code-review-delete")) {
+    summary.label = `Object deletion: ${scalar(envelope.outcome)}`;
+    summary.tone = envelope.ok === false ? "error" : "warning";
+    summary.rows = [`Attempt: ${scalar(record(data.attempt).state)}`, `Effects: ${scalar(data.effect)}`];
+    if (envelope.ok === false) notices.unshift(scalar(record(envelope.error).message));
+    notices.push(envelope.outcome === "preflight" ? "Command-only preview; no existence/readiness analysis." : "Deleted identities, repository scope and rollback remain unverified.");
+  } else if (name === "branchDelete" && action === "branch-delete") {
+    summary.label = `Branch deletion: ${scalar(envelope.outcome)}`;
+    summary.tone = envelope.ok === false ? "error" : "warning";
+    summary.rows = [`Attempt: ${scalar(record(data.attempt).state)}`, `Effects: ${scalar(data.effect)}`, `Delete changesets requested: ${scalar(data.deleteChangesetsRequested)}`];
+    if (envelope.ok === false) notices.unshift(scalar(record(envelope.error).message));
+    notices.push(envelope.outcome === "preflight" ? "Command-only preview; no existence or readiness analysis." : "Deletion identity, history effects and repository scope remain unverified.");
+  } else if (name === "mergeToBranch" && action === "merge-to-branch") {
+    summary.label = `Closeout: ${scalar(envelope.outcome)}`;
+    summary.tone = envelope.ok === false ? "error" : envelope.outcome === "completed" ? "success" : "warning";
+    summary.rows = [`Effect: ${scalar(data.effect)}`, `Recorded stages: ${records(data.stages).length}`, `Created changeset: ${scalar(record(data.createdChangeset).id) || "unobserved"}`, `Target verification: ${scalar(data.targetVerification)}`];
+    if (envelope.ok === false) notices.unshift(scalar(record(envelope.error).message));
+    notices.push("Earlier child effects remain recorded. Source links, branch head, aliases, exclusive scope and rollback unverified; no automatic replay.");
+  } else if ((name === "merge" || name === "finalizeMerge") && (action === "merge" || action === "finalize-merge")) {
+    summary.label = `Workspace merge: ${scalar(envelope.outcome)}`;
+    summary.tone = envelope.ok === false ? "error" : "warning";
+    summary.rows = [`Applying command completed: ${String(data.commandCompleted)}`, `Checkin readiness: ${scalar(data.checkinReadiness)}`, `Effect: ${scalar(data.effect)}`];
+    if (envelope.ok === false) notices.unshift(scalar(record(envelope.error).message));
+    notices.push(envelope.outcome === "preflight" ? "Command-only preview; no readiness analysis." : "Conflict resolution, finalized metadata, preservation and complete scope remain unverified.");
+  } else if (name === "resolveDeleteChangeConflict" && action === "resolve-delete-change-conflict") {
+    summary.label = `Removal: ${scalar(envelope.outcome)}`;
+    summary.tone = envelope.ok === false ? "error" : "warning";
+    summary.rows = [`Attempt: ${scalar(record(data.attempt).state)}`, `Effect: ${scalar(data.effect)}`];
+    if (envelope.ok === false) notices.unshift(scalar(record(envelope.error).message));
+    notices.push(envelope.outcome === "preflight" ? "Command-only preview; no conflict or execution readiness analysis." : "Conflict resolution, preservation, pending state and affected scope remain unverified.");
+  } else if (preview) {
     const wouldRun = typeof data.wouldRun === "boolean" ? data.wouldRun : /^- Would run: no$/m.test(raw) ? false : /^- Would run: yes$/m.test(raw) ? true : undefined;
     summary.label = wouldRun === false ? "Preview: would not run" : wouldRun === true ? "Preview: would run" : "Preview returned";
     summary.tone = "warning";
     summary.rows = action ? [scalar(data.reason) || scalar(data.errorCode), scalar(data.strategy)].filter(Boolean) : textLines.filter(line => /^- (?:Reason|Strategy|Command):/.test(line));
+  } else if ((name === "update" && action === "update" || name === "add" && action === "add" || name === "undo" && action === "undo") && typeof envelope.outcome === "string") {
+    summary.label = `${name === "update" ? "Update" : name === "add" ? "Add" : "Undo"}: ${envelope.outcome}`;
+    summary.tone = envelope.ok === false ? "error" : "warning";
+    summary.rows = [`Attempt: ${scalar(record(data.attempt).state)}`, `Effect: ${scalar(data.effect)}`];
+    if (envelope.ok === false) notices.unshift(scalar(record(envelope.error).message));
+    notices.push(name === "update" ? "Workspace identity, changed items, preservation, cleanliness and merge readiness remain unverified." : name === "add" ? "Requested operands are not verified added items. Workspace identity, expanded scope and preservation remain unverified." : "Requested operands are not verified undone items. Workspace identity, restored content, expanded scope and preservation remain unverified.");
+  } else if (name === "switchBranch" && action === "switch-branch" && typeof envelope.outcome === "string") {
+    summary.label = `Switch: ${envelope.outcome}`;
+    summary.tone = envelope.ok === false ? "error" : envelope.outcome === "switched" ? "success" : "warning";
+    summary.rows = records(data.steps).map(step => `${scalar(step.name)}: ${scalar(step.effect)}`);
+    if (envelope.ok === false) notices.unshift(scalar(record(envelope.error).message));
+    notices.push(`Effect: ${scalar(data.effect)}. File preservation, alias equivalence and Xlink effects remain unverified.`);
+  } else if ((name === "checkin" && action === "checkin" || name === "branchCreate" && action === "branch-create") && typeof envelope.outcome === "string") {
+    summary.label = `${name === "checkin" ? "Checkin" : "Branch create"}: ${envelope.outcome}`;
+    summary.tone = envelope.ok === false ? "error" : name === "checkin" ? "success" : "warning";
+    const changeset = scalar(record(data.createdChangeset).id);
+    if (changeset) summary.label += `${separator}cs:${changeset}`;
+    summary.rows = records(data.steps).map(step => `${scalar(step.name)}: ${scalar(step.effect)}`);
+    if (envelope.ok === false) notices.unshift(scalar(record(envelope.error).message));
+    if (name === "branchCreate") notices.push("Created identity and repository effects unverified; no workspace switch requested.");
+    else {
+      notices.push("Scope exhaustion, branch head, alias equivalence, merge links and Xlink effects unverified.");
+      if (data.pendingAfter === null) notices.push("Pending after not verified.");
+      if (count(data.omittedReferences)) notices.unshift(`${count(data.omittedReferences)} references omitted.`);
+    }
   } else if (name === "mergeBranches" && typeof envelope.outcome === "string") {
     summary.label = `Server merge: ${envelope.outcome}`;
-    summary.tone = envelope.outcome === "completed" ? "success" : "warning";
+    summary.tone = envelope.ok === false ? "error" : envelope.outcome === "completed" || envelope.outcome === "analyzed" ? "success" : "warning";
+    if (data.mode === "analyze") notices.unshift("Read-only analysis; no applying merge requested.");
+    summary.rows = Array.isArray(data.conflictPaths) ? data.conflictPaths.map(path => scalar(path)) : [];
+    if (count(record(data.counts).conflictsOmitted)) notices.unshift(`${count(record(data.counts).conflictsOmitted)} conflicts omitted.`);
     const changeset = scalar(record(data.createdChangeset).id);
     if (changeset) summary.label += `${separator}cs:${changeset}`;
     if (data.mergeLinkIdentity === "unverified" || data.xlinkEffects === "unverified") notices.push("Merge-link identity and Xlink effects remain unverified.");
     if (data.effect === "uncertain" || data.effect === "not-proven") notices.unshift("Effects not proven; inspect server state before any retry.");
-    if (data.timedOut === true) notices.unshift("Command timed out; effects uncertain.");
-    if (data.aborted === true) notices.unshift("Command cancelled; effects uncertain.");
+    if (data.serverAliasEquivalence === "unverified") notices.push("Requested and emitted server names remain separate; alias equivalence is unverified.");
+    if (data.timedOut === true || record(data.attempt).timedOut === true) notices.unshift("Command timed out; effects uncertain.");
+    if (data.aborted === true || record(data.attempt).aborted === true) notices.unshift("Command cancelled; effects uncertain.");
   } else if (data.checkedIn === false || record(data.switchOutcome).kind === "canceled" || data.kind === "canceled" || data.strategy === "cancel-with-pending") {
     summary.label = data.checkedIn === false ? "Checkin not performed" : "Switch cancelled";
     summary.tone = "warning";
     const reason = scalar(record(data.switchOutcome).reason) || scalar(data.reason);
     if (reason) notices.unshift(reason);
-  } else if (envelope.ok === false) {
+  } else if (envelope.ok === false && !(name === "diff" && Array.isArray(data.outcomes))) {
     summary.label = "Operation not successful";
     summary.tone = "error";
   } else if (name === "status" && count(record(data.summary).totalPending) !== undefined) {
@@ -147,20 +220,24 @@ function summarize(name: string, result: Result, raw: string, context?: Context)
     summary.label = data.branch;
   } else if (name === "branchExists" && /^(true|false)$/.test(raw.trim())) {
     summary.label = raw.trim() === "true" ? "Branch found" : "Branch not found";
-  } else if ((name === "diffFile" || name === "diffRevisions") && typeof data.status === "string") {
+  } else if (name === "diff" && typeof data.status === "string") {
     summary.label = data.status === "unchanged" ? "No differences" : data.status === "binary-different" ? "Binary content differs" : data.status === "added-empty" ? "Added file is empty" : "Text differences";
     if (data.binary === true) notices.push("Binary comparison; no text hunks.");
-  } else if (name === "workspaceDiff" && Array.isArray(data.outcomes)) {
+  } else if (name === "diff" && Array.isArray(data.outcomes)) {
     const outcomes = records(data.outcomes);
+    const counts = record(data.counts);
     const unavailable = outcomes.filter(item => item.status === "unavailable");
     const skipped = outcomes.filter(item => item.status === "skipped-directory");
-    summary.label = `${outcomes.length} results${separator}${outcomes.filter(item => item.changed === true).length} changed${separator}${unavailable.length} unavailable`;
-    if (unavailable.length) summary.tone = "warning";
+    summary.label = `${outcomes.length} returned results${separator}${outcomes.filter(item => record(item.comparison).changed === true).length} changed${separator}${count(counts.failed) ?? unavailable.length} unavailable`;
+    if (unavailable.length || envelope.ok === false) summary.tone = "warning";
     if (skipped.length) notices.push(`${skipped.length} directories skipped.`);
-    summary.rows = [...unavailable, ...outcomes.filter(item => item.status !== "unavailable" && item.status !== "skipped-directory"), ...skipped].map(item => `${scalar(item.path)}: ${scalar(item.status)}${item.error ? ` - ${scalar(item.error)}` : ""}`);
-    if (outcomes.some(item => item.truncated === true)) notices.push("Some file diffs were truncated by the tool.");
-    if (count(data.omittedOutcomes)) notices.push(`${data.omittedOutcomes} outcomes omitted by the tool.`);
-    if (count(data.skippedByLimit)) notices.push(`${data.skippedByLimit} pending items skipped by the file limit.`);
+    summary.rows = [...unavailable, ...outcomes.filter(item => item.status !== "unavailable" && item.status !== "skipped-directory"), ...skipped].map(item => `${scalar(item.path)}: ${scalar(item.status)}${item.error ? ` - ${scalar(record(item.error).code)}` : ""}`);
+    if (outcomes.some(item => record(record(item.comparison).excerpt).truncated === true)) notices.push("Some file diffs were truncated by the tool.");
+    if (count(counts.omitted)) notices.push(`${counts.omitted} outcomes omitted by the tool.`);
+    if (count(counts.limited)) notices.push(`${counts.limited} pending items skipped by the file limit.`);
+    if (count(counts.unattempted)) notices.push(`${counts.unattempted} selected items not attempted.`);
+    if (count(data.excludedPrivate)) notices.push(`${data.excludedPrivate} private items excluded.`);
+    if (strings(data.unmatched).length) notices.push(`${strings(data.unmatched).length} selected paths had no pending match.`);
   } else if (name === "patch" && typeof envelope.status === "string") {
     summary.label = `Patch ${envelope.status}${count(envelope.bytes) !== undefined ? `${separator}${envelope.bytes} bytes` : ""}`;
     if (envelope.binaryLimited === true) notices.push("Binary content could not be fully represented.");
@@ -189,7 +266,7 @@ function summarize(name: string, result: Result, raw: string, context?: Context)
     notices.unshift(...urgent.map(line => line.replace(/^#+\s*/, "")));
     notices.push(...warnings);
   }
-  if (data.truncated === true || data.outputTruncated === true) notices.push("Output truncated by the tool.");
+  if (data.truncated === true || data.outputTruncated === true || record(data.excerpt).truncated === true) notices.push("Output truncated by the tool.");
   const limited = data.truncated === true || data.outputTruncated === true || envelope.truncated === true
     || Boolean(count(record(data.itemCount).omitted) || count(data.omittedOutcomes) || count(data.skippedByLimit))
     || records(data.outcomes).some(item => item.truncated === true);
@@ -234,8 +311,11 @@ export function renderPlasticResult(name: string, result: Result, options: Optio
     const envelope = payload(result, raw);
     const data = record(envelope.data);
     if (typeof data.diff === "string") section("Diff", evidence(data.diff, theme));
+    if (typeof record(data.excerpt).text === "string") section("Diff", evidence(scalar(record(data.excerpt).text), theme));
     for (const item of records(data.outcomes)) {
       if (typeof item.diff === "string") section(safe(scalar(item.path)), evidence(item.diff, theme));
+      const excerpt=record(record(item.comparison).excerpt);
+      if (typeof excerpt.text === "string") section(safe(scalar(item.path)), evidence(excerpt.text, theme));
     }
     if (name === "patch" && typeof envelope.content === "string") section("Patch", evidence(envelope.content, theme));
     // Keep original content, including JSON numeric lexemes and duplicate keys, as the evidence.

package/src/plastic-tool-loading.ts

@@ -14,11 +14,7 @@ export type PlasticSearchCatalogEntry = {
   guidance: readonly string[];
 };
 
-/**
- * Package-owned executable capability vocabulary. `plastic_diff` deliberately
- * remains outside this catalog: it is registered for compatibility, but is a
- * disabled alias rather than a safe executable diff capability.
- */
+/** Canonical executable capabilities; there are no compatibility diff tools. */
 export const PLASTIC_SEARCH_CATALOG: readonly PlasticSearchCatalogEntry[] = [
   { name: "plastic_status", aliases: ["status", "pending changes", "working changes", "what changed", "changed files", "list changes"], tags: ["workspace", "inspect", "changes"], guidance: ["Use machineReadable=true to list changed, added, moved, deleted, and private paths without invoking GUI-capable cm diff."] },
   { name: "plastic_update", aliases: ["update", "sync", "pull latest"], tags: ["workspace", "synchronize", "safe"], guidance: ["Review pending changes before updating a workspace."] },
@@ -27,13 +23,11 @@ export const PLASTIC_SEARCH_CATALOG: readonly PlasticSearchCatalogEntry[] = [
   { name: "plastic_undo", aliases: ["undo changes", "revert changes", "discard changes"], tags: ["changes", "mutation", "destructive"], guidance: ["Confirm the exact paths before discarding pending changes."] },
   { name: "plastic_resolveDeleteChangeConflict", aliases: ["resolve delete conflict", "deleted conflict"], tags: ["merge", "conflict", "resolution"], guidance: ["Inspect the conflict and choose whether files should remain on disk before resolving it."] },
   { name: "plastic_patch", aliases: ["patch", "generate patch", "review patch"], tags: ["diff", "patch", "export"], guidance: ["Inspect generated patches before sharing because they can include source, paths, or secrets."] },
-  { name: "plastic_diffFile", aliases: ["diff", "diff file", "file diff", "compare one file", "compare file"], tags: ["diff", "file", "workspace", "inspect"], guidance: ["Use only when change-boundary evidence is needed. Pass one exact workspace path, omit revision for its Plastic base, and keep maxChars small unless more output is intentional."] },
-  { name: "plastic_workspaceDiff", aliases: ["workspace diff", "pending review", "review pending changes", "review workspace changes", "diff pending files"], tags: ["diff", "workspace", "review", "inspect"], guidance: ["Use only for an intentional multi-file content review, not routine validation. Select exact paths or pass allPending=true explicitly; use plastic_status when only changed paths are needed."] },
-  { name: "plastic_diffRevisions", aliases: ["diff revisions", "compare revisions", "revision diff"], tags: ["diff", "revision", "inspect"], guidance: ["Use this only for two explicit file-qualified revision specifications."] },
+  { name: "plastic_diff", aliases: ["diff", "diff file", "compare file", "workspace diff", "pending review", "diff revisions", "compare revisions"], tags: ["diff", "file", "workspace", "revision", "inspect"], guidance: ["Require mode=file, revisions, or workspace. Use explicit paths or allPending=true for pending review; raw GUI cm diff remains blocked."] },
   { 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_mergeBranches", aliases: ["server merge", "workspace-free merge", "merge qualified branches", "server merge conflicts", "resolve server conflicts"], tags: ["merge", "branch", "server", "conflict", "resolutions", "mutation"], guidance: ["Require explicit same-repository/server qualified source and target. mode=analyze performs read-only remote conflict discovery without a message; apply requires a nonempty message and can submit a reviewed fileConflictsResolutionsFile. Keep resolution inputs immutable until completion. Preflight only renders the command and validates local inputs; 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."] },
@@ -51,9 +45,8 @@ export const PLASTIC_SEARCH_CATALOG: readonly PlasticSearchCatalogEntry[] = [
   { name: "plastic_workspaceList", aliases: ["list workspaces", "find workspace", "workspaces"], tags: ["workspace", "inspect", "query"], guidance: ["Inspect workspace paths and repository identity before using a workspace in a mutation."] },
 ] as const;
 
-export const PLASTIC_COMPATIBILITY_TOOL_NAMES = ["plastic_diff"] as const;
 export const PLASTIC_SEARCHABLE_TOOL_NAMES = new Set(PLASTIC_SEARCH_CATALOG.map((entry) => entry.name));
-export const PLASTIC_TOOL_NAMES = new Set([...PLASTIC_SEARCHABLE_TOOL_NAMES, ...PLASTIC_COMPATIBILITY_TOOL_NAMES]);
+export const PLASTIC_TOOL_NAMES = new Set(PLASTIC_SEARCHABLE_TOOL_NAMES);
 
 export type ToolSourceInfo = {
   path: string;
@@ -168,6 +161,8 @@ function safetyPriority(entry: PlasticSearchCatalogEntry): number {
 /** Search the executable catalog with deterministic scoring and safe bare-domain ordering. */
 export function searchPlasticTools(input: PlasticToolSearchInput, descriptions: ReadonlyMap<string, string> = new Map()): PlasticToolSearchMatch[] {
   const requestedNames = exactRequestedNames(input.toolNames);
+  const exactQuery = typeof input.query === "string" ? input.query.trim().toLowerCase() : "";
+  if (requestedNames.size === 0 && /^plastic_[a-z0-9]+$/.test(exactQuery) && !PLASTIC_SEARCH_CATALOG.some(entry => entry.name.toLowerCase() === exactQuery)) return [];
   const terms = typeof input.query === "string" ? tokenize(input.query) : [];
   const limit = normalizeLimit(input.limit, requestedNames);
   const domainTerms = terms.filter((term) => SEARCH_DOMAIN_TERMS.has(term));
@@ -231,5 +226,5 @@ export function getRestoredPlasticToolNames(branchEntries: readonly unknown[], e
       if (typeof name === "string" && effectiveToolNames.has(name)) restored.add(name);
     }
   }
-  return [...PLASTIC_COMPATIBILITY_TOOL_NAMES, ...PLASTIC_SEARCH_CATALOG.map((entry) => entry.name)].filter((name) => restored.has(name));
+  return PLASTIC_SEARCH_CATALOG.map((entry) => entry.name).filter((name) => restored.has(name));
 }

package/src/presentation/add-results.ts

@@ -0,0 +1,5 @@
+import type { AddReceipt } from "../domain/add-contract";
+export function presentAddReceipt(dto: AddReceipt): string {
+    return dto.ok ? `Add command completed for ${dto.data.requestedOperandCount} requested operands, not a verified added-item count. Workspace identity, added items, expanded scope and preservation remain unverified.` :
+        `Add ${dto.outcome}: ${dto.error.message} Effects: ${dto.data.effect}. Do not retry automatically.`;
+}

package/src/presentation/branch-create.ts

@@ -0,0 +1,7 @@
+import type { BranchCreateReceipt } from "../domain/branch-create-contract";
+export function presentBranchCreateReceipt(dto: BranchCreateReceipt): string {
+    const text = dto.ok
+        ? "Branch create command completed. Created branch identity, repository and effects are unverified; no workspace switch was requested."
+        : `Branch create ${dto.outcome}. ${dto.error.message} Effect: ${dto.data.effect}.`;
+    return text.length <= 24000 ? text : "Branch create evidence is unavailable; inspect structuredContent and do not retry automatically.";
+}

package/src/presentation/branch-delete-results.ts

@@ -0,0 +1,7 @@
+import type { BranchDeleteReceipt } from "../domain/branch-delete-contract";
+export function presentBranchDeleteReceipt(dto:BranchDeleteReceipt):string {
+ if(dto.data.outputFormatRequested==="json")return JSON.stringify(dto);
+ if(!dto.ok)return `Branch deletion ${dto.outcome}: ${dto.error.message} Effects: ${dto.data.effect}. Do not retry automatically.`;
+ if(dto.outcome==="preflight")return `Branch-delete command-only preview (not executed): ${JSON.stringify(dto.data.intendedArgv)}. No branch existence, permissions or deletion readiness analysis.`;
+ return "Branch-delete command completed. Deleted branch identity, changeset-history effects, repository/workspace scope and rollback remain unverified.";
+}

package/src/presentation/checkin-results.ts

@@ -0,0 +1,14 @@
+import type { CheckinReceipt } from "../domain/checkin-contract";
+export function presentCheckinReceipt(dto: CheckinReceipt, format: "text" | "json" = "text"): string {
+    const text = format === "json" ? JSON.stringify(dto) : [
+        `## Checkin ${dto.outcome}`,
+        `- Effect: ${dto.data.effect}`,
+        ...(dto.outcome === "preflight" ? [`- Would run: ${dto.data.wouldRun ? "yes" : "no"}`, `- Command argv: ${JSON.stringify(dto.data.command)}`] : []),
+        ...(dto.data.createdChangeset ? [`- Observed root changeset: cs:${dto.data.createdChangeset.id}@br:${dto.data.createdChangeset.branch}@${dto.data.createdChangeset.repository}@${dto.data.createdChangeset.server}`] : []),
+        `- Steps: ${dto.data.steps.map(s => `${s.name} (${s.effect})`).join(", ") || "none"}`,
+        `- Pending after: ${dto.data.pendingAfter ? dto.data.pendingAfter.totalPending : "not verified"}`,
+        "- Requested scope exhaustion, branch head, alias equivalence, merge links and Xlink effects: unverified",
+        ...(!dto.ok ? [dto.error.message] : []),
+    ].join("\n");
+    return Buffer.byteLength(text, "utf8") <= 24000 ? text : JSON.stringify({ action: dto.action, outcome: dto.outcome, ok: dto.ok, note: "Presentation omitted; inspect structuredContent for the bounded receipt." });
+}

package/src/presentation/closeout-results.ts

@@ -0,0 +1,2 @@
+import type { CloseoutReceipt } from "../domain/closeout-contract";
+export function presentCloseoutReceipt(dto:CloseoutReceipt,format?:"text"|"json"):string {if(format==="json")return JSON.stringify(dto);return [`## Merge To Branch ${dto.ok?dto.outcome==="preflight"?"Preview":"Receipt":"Paused"}`,`- Outcome: ${dto.outcome}; effect: ${dto.data.effect}`,`- Recorded stages: ${dto.data.stages.length}; target verification: ${dto.data.targetVerification}`,`- Source: ${dto.data.sourceBranch??"unobserved"}; target: ${dto.data.targetBranch??"unobserved"}`,`- Created changeset: ${dto.data.createdChangeset?`cs:${dto.data.createdChangeset.id}@br:${dto.data.createdChangeset.branch}@${dto.data.createdChangeset.repository}@${dto.data.createdChangeset.server}`:"unobserved"}`,`- Final pending count: ${dto.data.pendingAfter?.totalPending??"unobserved"}`,...(!dto.ok?[`- ${dto.error.message}`]:[]),"- Point-in-time evidence only; source links, branch head, aliases, exclusive scope and rollback are unverified. No automatic replay or compensation."].join("\n");}

package/src/presentation/diff-results.ts

@@ -0,0 +1,237 @@
+import { OutputFormat, TOOL_VERSION } from "./results";
+import { TextDiffResult } from "../diff/text";
+import { getCmVersion } from "../execution/cli-version";
+
+export const DIFF_RESPONSE_DEFAULT_MAX_CHARS = 8_000;
+
+export const DIFF_RESPONSE_MAX_CHARS = 20_000;
+
+export const DIFF_RESPONSE_MIN_CHARS = 500;
+
+export const DIFF_RESPONSE_TOTAL_MAX_CHARS = 24_000;
+
+export const normalizeDiffResponseMaxChars = (value: unknown): number =>
+{
+    if (typeof value !== "number" || !Number.isFinite(value))
+    {
+        return DIFF_RESPONSE_DEFAULT_MAX_CHARS;
+    }
+    return Math.min(DIFF_RESPONSE_MAX_CHARS, Math.max(DIFF_RESPONSE_MIN_CHARS, Math.trunc(value)));
+};
+
+export const formatTextDiff = async (
+    action: "diffFile" | "diffRevisions",
+    format: OutputFormat | undefined,
+    comparisonKind: string,
+    unboundedResult: TextDiffResult,
+    workdir: string | undefined,
+    comparisonMetadata: Record<string, unknown> = {},
+    maxChars?: number,
+): Promise<string> =>
+{
+    const result = boundTextDiffResult(unboundedResult, normalizeDiffResponseMaxChars(maxChars));
+    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 : (status === "added-empty" ? "Added file is empty; no text diff hunks." : "No differences."));
+    const data = {
+        comparisonKind,
+        ...comparisonMetadata,
+        backend: result.backend,
+        status,
+        changed: result.changed,
+        binary: result.binary,
+        truncated: result.truncated,
+        totalChars: result.totalChars,
+        diff: result.changed && !result.binary ? result.output : undefined,
+    };
+    const warnings = result.truncated ? ["Diff output was truncated; use a narrower file or generate a review patch for the complete result."] : undefined;
+    if (format === "json")
+    {
+        return toBoundedDiffStructuredResult(action, data, workdir, warnings);
+    }
+    return text;
+};
+
+export const boundTextDiffResult = (result: TextDiffResult, maxChars: number): TextDiffResult =>
+{
+    if (!result.output || result.output.length <= maxChars)
+    {
+        return result;
+    }
+
+    const suffix = `\n\n[Diff output truncated at the requested ${maxChars}-character response bound.]`;
+    return {
+        ...result,
+        output: suffix.length >= maxChars ? suffix.slice(0, maxChars) : `${result.output.slice(0, maxChars - suffix.length)}${suffix}`,
+        truncated: true,
+        totalChars: result.totalChars,
+    };
+};
+
+export const toBoundedDiffStructuredResult = async (
+    action: "diffFile" | "diffRevisions",
+    data: Record<string, unknown>,
+    workdir?: string,
+    warnings?: string[],
+): Promise<string> =>
+{
+    const wrap = (payload: Record<string, unknown>): string => `## ${action}\n\n\`\`\`json\n${JSON.stringify(payload, null, 2)}\n\`\`\``;
+    const basePayload = {
+        ok: true,
+        action,
+        toolVersion: TOOL_VERSION,
+        cliVersion: (await getCmVersion(workdir)).slice(0, 256),
+    };
+    const initial = wrap({ ...basePayload, data, ...(warnings?.length ? { warnings } : {}) });
+    if (initial.length <= DIFF_RESPONSE_TOTAL_MAX_CHARS)
+    {
+        return initial;
+    }
+
+    const originalDiff = typeof data.diff === "string" ? data.diff : "";
+    const responseWarning = `Diff content was further truncated after JSON escaping to keep the complete response within ${DIFF_RESPONSE_TOTAL_MAX_CHARS} characters.`;
+    const boundedWarnings = [...(warnings ?? []), responseWarning];
+    const suffix = `\n\n[Diff output truncated to keep the complete JSON response within ${DIFF_RESPONSE_TOTAL_MAX_CHARS} characters.]`;
+    const render = (prefixChars: number): string => wrap({
+        ...basePayload,
+        data: {
+            ...data,
+            truncated: true,
+            diff: `${originalDiff.slice(0, prefixChars)}${suffix}`,
+        },
+        warnings: boundedWarnings,
+    });
+
+    let low = 0;
+    let high = originalDiff.length;
+    let best = render(0);
+    while (low <= high)
+    {
+        const middle = Math.floor((low + high) / 2);
+        const candidate = render(middle);
+        if (candidate.length <= DIFF_RESPONSE_TOTAL_MAX_CHARS)
+        {
+            best = candidate;
+            low = middle + 1;
+        }
+        else
+        {
+            high = middle - 1;
+        }
+    }
+    return best;
+};
+
+export const WORKSPACE_DIFF_DEFAULT_MAX_FILES = 3;
+
+export const WORKSPACE_DIFF_MAX_FILES = 20;
+
+export const WORKSPACE_DIFF_MAX_PATHS = 20;
+
+export const WORKSPACE_DIFF_PATH_MAX_CHARS = 1_024;
+
+export const WORKSPACE_DIFF_DISPLAY_PATH_MAX_CHARS = 256;
+
+export const WORKSPACE_DIFF_ERROR_MAX_CHARS = 1_024;
+
+export const WORKSPACE_DIFF_DEFAULT_MAX_CHARS = 3_000;
+
+export const WORKSPACE_DIFF_PER_FILE_MAX_CHARS = 8_000;
+
+export const WORKSPACE_DIFF_MIN_CHARS = 500;
+// This is a response bound, not just a diff-body bound. Reserve space for
+// framing and an omission summary so both text and JSON remain useful.
+
+export const WORKSPACE_DIFF_TOTAL_MAX_CHARS = 20_000;
+
+export const WORKSPACE_DIFF_CONTENT_MAX_CHARS = 16_000;
+
+export const boundWorkspaceValue = (value: string, maxChars: number): string =>
+{
+    if (maxChars <= 0)
+    {
+        return "";
+    }
+    if (value.length <= maxChars)
+    {
+        return value;
+    }
+    const suffix = `… [truncated; original ${value.length} characters]`;
+    return suffix.length >= maxChars ? value.slice(0, maxChars) : `${value.slice(0, maxChars - suffix.length)}${suffix}`;
+};
+
+export const boundWorkspaceDiffResult = (result: TextDiffResult, maxChars: number): TextDiffResult =>
+{
+    if (result.output.length <= maxChars)
+    {
+        return result;
+    }
+    return { ...result, output: boundWorkspaceValue(result.output, maxChars), truncated: true };
+};
+
+export const workspacePathPreview = (paths: string[]): string[] => paths.map((path) => boundWorkspaceValue(path, WORKSPACE_DIFF_DISPLAY_PATH_MAX_CHARS));
+
+export const appendBoundedWorkspaceText = (prefix: string, sections: string[], omitted: number): string =>
+{
+    const omission = (count: number): string => `\n\n[${count} file outcome(s) omitted to keep this response within ${WORKSPACE_DIFF_TOTAL_MAX_CHARS} characters.]`;
+    let text = prefix;
+    let omittedCount = omitted;
+    for (let index = 0; index < sections.length; index += 1)
+    {
+        const candidate = `${text}\n\n${sections[index]}`;
+        if (candidate.length + omission(omittedCount + sections.length - index - 1).length > WORKSPACE_DIFF_TOTAL_MAX_CHARS)
+        {
+            omittedCount += sections.length - index;
+            break;
+        }
+        text = candidate;
+    }
+    return omittedCount > 0 ? `${text}${omission(omittedCount)}` : text;
+};
+
+export const formatWorkspaceDiffResult = async (
+    format: OutputFormat,
+    textPrefix: string,
+    textSections: string[],
+    data: Record<string, unknown>,
+    warnings: string[],
+    outcomes: Array<Record<string, unknown>>,
+    preOmittedOutcomes: number,
+    workdir?: string,
+): Promise<string> =>
+{
+    if (format !== "json")
+    {
+        return appendBoundedWorkspaceText(textPrefix, textSections, preOmittedOutcomes);
+    }
+
+    const cliVersion = boundWorkspaceValue(await getCmVersion(workdir), WORKSPACE_DIFF_DISPLAY_PATH_MAX_CHARS);
+    const wrap = (payload: Record<string, unknown>): string => `## workspaceDiff\n\n\`\`\`json\n${JSON.stringify(payload, null, 2)}\n\`\`\``;
+    const retained: Array<Record<string, unknown>> = [];
+    let omittedOutcomes = preOmittedOutcomes;
+    const payloadFor = (): Record<string, unknown> => ({
+        ok: true,
+        action: "workspaceDiff",
+        toolVersion: TOOL_VERSION,
+        cliVersion,
+        data: { ...data, outcomes: retained, omittedOutcomes },
+        ...(warnings.length > 0 ? { warnings } : {}),
+    });
+
+    for (let index = 0; index < outcomes.length; index += 1)
+    {
+        retained.push(outcomes[index]);
+        const remainingCount = outcomes.length - index - 1;
+        // Keep an omission field in the serialized payload before deciding to
+        // retain another result; JSON escaping can otherwise exceed the bound.
+        omittedOutcomes = preOmittedOutcomes + remainingCount;
+        if (wrap(payloadFor()).length > WORKSPACE_DIFF_TOTAL_MAX_CHARS)
+        {
+            retained.pop();
+            omittedOutcomes = preOmittedOutcomes + outcomes.length - index;
+            break;
+        }
+    }
+    return wrap(payloadFor());
+};

package/src/presentation/removal-results.ts

@@ -0,0 +1,7 @@
+import type { RemovalReceipt } from "../domain/removal-contract";
+export function presentRemovalReceipt(dto: RemovalReceipt): string {
+    if (dto.data.outputFormatRequested === "json") return `## resolve-delete-change-conflict\n\n\`\`\`json\n${JSON.stringify(dto, null, 2)}\n\`\`\``;
+    if (!dto.ok) return `Removal ${dto.outcome}: ${dto.error.message} Effects: ${dto.data.effect}. Do not retry automatically.`;
+    if (dto.outcome === "preflight") return `Removal command-only preview (not executed): ${JSON.stringify(dto.data.intendedArgv)}. Requested --nodisk: ${dto.data.keepOnDiskRequested}. No conflict or execution readiness analysis.`;
+    return `Remove command completed for ${dto.data.requestedOperandCount} requested operands, not a verified resolved-item count. Conflict resolution, disk preservation, pending state, workspace identity and affected scope remain unverified.`;
+}