[codex] Add workspace diff viewer plugin (#6071)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies.
> - Operators need to inspect what agents changed inside execution and
project workspaces.
> - The existing workspace detail views did not provide a first-party
rich diff surface for staged, unstaged, head, renamed, binary,
oversized, and untracked changes.
> - The plugin system is the intended extension point for optional rich
UI surfaces.
> - This pull request adds a workspace diff plugin plus host services
and shared contracts so Changes tabs can render workspace diffs through
plugin slots.
> - The diff-renderer dependency should stay owned by the plugin package
rather than the core UI app.
> - The dependency surface must stay aligned with repository PR policy,
including intentionally omitting `pnpm-lock.yaml` from the PR.
> - The benefit is a more reviewable workspace surface without
hard-coding the renderer into every page.

## What Changed

- Added `@paperclipai/plugin-workspace-diff`, including diff
normalization, plugin manifest/worker/UI entrypoints, and focused plugin
tests.
- Kept `@pierre/diffs` scoped to `@paperclipai/plugin-workspace-diff`;
removed the core UI lab diff-renderer surface and direct UI package
dependency.
- Added shared workspace diff types and validators, plus plugin SDK
surface for workspace diff host services.
- Added server workspace diff service support and route coverage for
execution/project workspace diff flows.
- Wired Execution Workspace and Project Workspace Changes tabs to load
the diff plugin, including loading/error fallback behavior.
- Added UI tests and fixtures for the Changes tabs and plugin bridge
behavior.
- Added the new plugin package manifest to the Docker deps stage so PR
policy can validate dependency coverage.
- Addressed review hardening around empty untracked patches, workspace
path exposure, project workspace read capability checks, and default
base refs.

## Verification

- `pnpm --filter @paperclipai/plugin-workspace-diff test`
- `pnpm exec vitest run
packages/shared/src/validators/workspace-diff.test.ts
server/src/__tests__/workspace-diff-service.test.ts
ui/src/pages/ProjectWorkspaceDetail.test.tsx
ui/src/pages/ExecutionWorkspaceDetail.test.tsx`
- `pnpm exec vitest run ui/src/plugins/bridge.test.ts
server/src/__tests__/workspace-runtime-routes-authz.test.ts`
- `pnpm --filter @paperclipai/shared typecheck`
- `pnpm --filter @paperclipai/plugin-workspace-diff typecheck`
- `pnpm --filter @paperclipai/server typecheck`
- `pnpm --filter @paperclipai/ui typecheck`
- `node ./scripts/check-docker-deps-stage.mjs`
- Browser screenshot captured from the local worktree dev server:
https://files.catbox.moe/ofdpsp.png
- Confirmed branch is rebased onto `public-gh/master`,
`.github/workflows/pr.yml` is not included in the PR diff,
`ui/package.json` is not included in the PR diff, and `pnpm-lock.yaml`
is not included in the PR diff.

## Risks

- Medium UI integration risk: the Changes tab depends on the plugin slot
and host diff service path.
- Medium dependency risk: this adds `@pierre/diffs` in the plugin
package, but `pnpm-lock.yaml` is intentionally omitted per packaging
instructions because repository automation manages lockfile updates.
- Current CI blocker: downstream frozen installs fail until the
repository policy path for new plugin package dependencies is chosen.
- Diff rendering edge cases are covered for common working-tree and head
diff states, but very large repositories may still expose performance
limits.
- No migrations are included.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex, GPT-5 class coding model, tool-enabled local execution
environment. Exact context window was not exposed by the runtime.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

packages/plugins/plugin-workspace-diff/tests/contracts.spec.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { workspaceDiffQuerySchema, workspaceDiffResponseSchema } from "../src/contracts.js";
+import { diffResponse } from "./fixtures.js";
+
+describe("workspace diff plugin contracts", () => {
+  it("normalizes query options from plugin data parameters", () => {
+    expect(workspaceDiffQuerySchema.parse({
+      view: "head",
+      baseRef: " main ",
+      includeUntracked: "false",
+      path: ["src/app.ts, README.md", "packages/shared/src/index.ts"],
+    })).toEqual({
+      view: "head",
+      baseRef: "main",
+      includeUntracked: false,
+      paths: ["src/app.ts", "README.md", "packages/shared/src/index.ts"],
+    });
+  });
+
+  it("validates the plugin-owned response shape", () => {
+    expect(workspaceDiffResponseSchema.parse(diffResponse())).toMatchObject({
+      workspaceId: "11111111-1111-4111-8111-111111111111",
+      stats: { fileCount: 1 },
+    });
+  });
+});

packages/plugins/plugin-workspace-diff/tests/diff-model.spec.ts

@@ -0,0 +1,193 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildFilePatch,
+  buildFilePatches,
+  diffSummary,
+  initialExpandedFileSet,
+  LONG_DIFF_LINE_THRESHOLD,
+  nextExpandedFileSet,
+  statusLabel,
+  toFileViewModels,
+} from "../src/diff-model.js";
+import { changedFile, diffResponse } from "./fixtures.js";
+
+describe("workspace diff UI model", () => {
+  it("summarizes changed files and line counts", () => {
+    const diff = diffResponse();
+
+    expect(diffSummary(diff)).toMatchObject({
+      changedLabel: "1 file",
+      lineLabel: "+1 / -1",
+      warningCount: 0,
+      truncated: false,
+    });
+    expect(toFileViewModels(diff)[0]).toMatchObject({
+      path: "src/app.ts",
+      status: "modified",
+      patchKinds: ["unstaged"],
+      lineCount: 7,
+      longDiff: false,
+    });
+  });
+
+  it("represents empty workspace diffs", () => {
+    const diff = diffResponse({ files: [] });
+
+    expect(toFileViewModels(diff)).toEqual([]);
+    expect(diffSummary(diff).changedLabel).toBe("0 files");
+  });
+
+  it("surfaces truncation and file warnings", () => {
+    const warning = { code: "patch_truncated" as const, message: "Patch was truncated.", path: "src/app.ts" };
+    const file = changedFile({
+      truncated: true,
+      warnings: [warning],
+      patches: [],
+    });
+    const diff = diffResponse({ files: [file], truncated: true, warnings: [warning] });
+
+    expect(buildFilePatch(file)).toBeNull();
+    expect(toFileViewModels(diff)[0]?.warnings).toEqual([warning]);
+    expect(diffSummary(diff)).toMatchObject({
+      warningCount: 1,
+      truncated: true,
+    });
+  });
+
+  it("does not duplicate aggregated patch warnings", () => {
+    const warning = { code: "patch_truncated" as const, message: "Patch was truncated.", path: "src/app.ts" };
+    const file = changedFile({
+      warnings: [warning],
+      patches: [
+        {
+          kind: "unstaged",
+          patch: null,
+          additions: 0,
+          deletions: 0,
+          binary: false,
+          oversized: false,
+          truncated: true,
+          warnings: [warning],
+        },
+      ],
+    });
+    const diff = diffResponse({ files: [file], warnings: [warning] });
+
+    expect(toFileViewModels(diff)[0]?.warnings).toEqual([warning]);
+    expect(diffSummary(diff).warningCount).toBe(1);
+  });
+
+  it("keeps staged and unstaged patches renderable as separate single-file diffs", () => {
+    const stagedPatch = [
+      "diff --git a/src/app.ts b/src/app.ts",
+      "index 1111111..2222222 100644",
+      "--- a/src/app.ts",
+      "+++ b/src/app.ts",
+      "@@ -1 +1 @@",
+      "-export const value = 1;",
+      "+export const value = 2;",
+      "",
+    ].join("\n");
+    const unstagedPatch = [
+      "diff --git a/src/app.ts b/src/app.ts",
+      "index 2222222..3333333 100644",
+      "--- a/src/app.ts",
+      "+++ b/src/app.ts",
+      "@@ -3 +3 @@",
+      "-export const label = 'old';",
+      "+export const label = 'new';",
+      "",
+    ].join("\n");
+    const file = changedFile({
+      staged: true,
+      unstaged: true,
+      patches: [
+        {
+          kind: "staged",
+          patch: stagedPatch,
+          additions: 1,
+          deletions: 1,
+          binary: false,
+          oversized: false,
+          truncated: false,
+          warnings: [],
+        },
+        {
+          kind: "unstaged",
+          patch: unstagedPatch,
+          additions: 1,
+          deletions: 1,
+          binary: false,
+          oversized: false,
+          truncated: false,
+          warnings: [],
+        },
+      ],
+    });
+
+    const patches = buildFilePatches(file);
+    const viewModel = toFileViewModels(diffResponse({ files: [file] }))[0];
+
+    expect(buildFilePatch(file)).toBe(stagedPatch.trimEnd());
+    expect(patches.map((patch) => patch.kind)).toEqual(["staged", "unstaged"]);
+    expect(patches.map((patch) => patch.patch?.match(/^diff --git/gm)?.length ?? 0)).toEqual([1, 1]);
+    expect(viewModel?.patches).toHaveLength(2);
+    expect(viewModel?.patchKinds).toEqual(["staged", "unstaged"]);
+  });
+
+  it("marks long text diffs so the UI can fold them by default", () => {
+    const longPatch = [
+      "diff --git a/src/large.ts b/src/large.ts",
+      "index 1111111..2222222 100644",
+      "--- a/src/large.ts",
+      "+++ b/src/large.ts",
+      "@@ -1,1 +1,1 @@",
+      ...Array.from({ length: LONG_DIFF_LINE_THRESHOLD }, (_, index) => `+export const value${index} = ${index};`),
+      "",
+    ].join("\n");
+    const files = toFileViewModels(diffResponse({
+      files: [
+        changedFile({ path: "src/small.ts" }),
+        changedFile({
+          path: "src/large.ts",
+          additions: LONG_DIFF_LINE_THRESHOLD,
+          deletions: 0,
+          patches: [
+            {
+              kind: "unstaged",
+              patch: longPatch,
+              additions: LONG_DIFF_LINE_THRESHOLD,
+              deletions: 0,
+              binary: false,
+              oversized: false,
+              truncated: false,
+              warnings: [],
+            },
+          ],
+        }),
+      ],
+    }));
+    const longFile = files.find((file) => file.path === "src/large.ts");
+    const defaultExpanded = initialExpandedFileSet(files);
+
+    expect(longFile?.lineCount).toBeGreaterThan(LONG_DIFF_LINE_THRESHOLD);
+    expect(longFile?.longDiff).toBe(true);
+    expect(defaultExpanded.has("src/small.ts")).toBe(true);
+    expect(defaultExpanded.has("src/large.ts")).toBe(false);
+  });
+
+  it("toggles expanded file state without mutating the current set", () => {
+    const current = new Set(["a.ts"]);
+    const collapsed = nextExpandedFileSet(current, "a.ts");
+    const expanded = nextExpandedFileSet(current, "b.ts");
+
+    expect(current.has("a.ts")).toBe(true);
+    expect(collapsed.has("a.ts")).toBe(false);
+    expect(expanded.has("b.ts")).toBe(true);
+  });
+
+  it("labels file statuses for the sidebar", () => {
+    expect(statusLabel("untracked")).toBe("Untracked");
+    expect(statusLabel("type_changed")).toBe("Type changed");
+  });
+});

packages/plugins/plugin-workspace-diff/tests/fixtures.ts

@@ -0,0 +1,78 @@
+import type { WorkspaceDiffFile, WorkspaceDiffResponse } from "../src/contracts.js";
+
+export function changedFile(overrides: Partial<WorkspaceDiffFile> = {}): WorkspaceDiffFile {
+  return {
+    path: "src/app.ts",
+    oldPath: null,
+    status: "modified",
+    staged: false,
+    unstaged: true,
+    untracked: false,
+    binary: false,
+    oversized: false,
+    truncated: false,
+    additions: 1,
+    deletions: 1,
+    sizeBytes: 120,
+    patches: [
+      {
+        kind: "unstaged",
+        patch: [
+          "diff --git a/src/app.ts b/src/app.ts",
+          "index 1111111..2222222 100644",
+          "--- a/src/app.ts",
+          "+++ b/src/app.ts",
+          "@@ -1 +1 @@",
+          "-export const value = 1;",
+          "+export const value = 2;",
+          "",
+        ].join("\n"),
+        additions: 1,
+        deletions: 1,
+        binary: false,
+        oversized: false,
+        truncated: false,
+        warnings: [],
+      },
+    ],
+    warnings: [],
+    ...overrides,
+  };
+}
+
+export function diffResponse(overrides: Partial<WorkspaceDiffResponse> = {}): WorkspaceDiffResponse {
+  const files = overrides.files ?? [changedFile()];
+  const additions = files.reduce((sum, file) => sum + file.additions, 0);
+  const deletions = files.reduce((sum, file) => sum + file.deletions, 0);
+  return {
+    workspaceId: "11111111-1111-4111-8111-111111111111",
+    companyId: "22222222-2222-4222-8222-222222222222",
+    view: "working-tree",
+    baseRef: null,
+    defaultBaseRef: null,
+    headSha: null,
+    includeUntracked: true,
+    paths: [],
+    files,
+    stats: {
+      fileCount: files.length,
+      stagedFileCount: files.filter((file) => file.staged).length,
+      unstagedFileCount: files.filter((file) => file.unstaged).length,
+      untrackedFileCount: files.filter((file) => file.untracked).length,
+      binaryFileCount: files.filter((file) => file.binary).length,
+      oversizedFileCount: files.filter((file) => file.oversized).length,
+      truncatedFileCount: files.filter((file) => file.truncated).length,
+      additions,
+      deletions,
+    },
+    warnings: [],
+    caps: {
+      maxFiles: 200,
+      maxFileBytes: 524288,
+      maxPatchBytes: 131072,
+      maxTotalPatchBytes: 1048576,
+    },
+    truncated: false,
+    ...overrides,
+  };
+}

packages/plugins/plugin-workspace-diff/tests/plugin.spec.ts

@@ -0,0 +1,238 @@
+import { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { afterEach, describe, expect, it } from "vitest";
+import { createTestHarness } from "@paperclipai/plugin-sdk/testing";
+import manifest from "../src/manifest.js";
+import plugin, { resolveDefaultBaseRef } from "../src/worker.js";
+
+const execFileAsync = promisify(execFile);
+const tempRoots: string[] = [];
+
+async function git(cwd: string, args: string[]) {
+  return execFileAsync("git", ["-C", cwd, ...args], { cwd });
+}
+
+async function createGitWorkspace() {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-workspace-diff-plugin-"));
+  tempRoots.push(root);
+  await fs.mkdir(path.join(root, "src"), { recursive: true });
+  await git(root, ["init"]);
+  await git(root, ["config", "user.email", "paperclip@example.com"]);
+  await git(root, ["config", "user.name", "Paperclip Test"]);
+  await fs.writeFile(path.join(root, "src/app.ts"), "export const value = 1;\n");
+  await git(root, ["add", "src/app.ts"]);
+  await git(root, ["commit", "-m", "initial"]);
+  await git(root, ["branch", "-M", "main"]);
+  return root;
+}
+
+describe("workspace diff plugin", () => {
+  afterEach(async () => {
+    await Promise.all(tempRoots.map((root) => fs.rm(root, { recursive: true, force: true })));
+    tempRoots.length = 0;
+  });
+
+  it("declares workspace Changes tabs and workspace read capabilities", () => {
+    expect(manifest.capabilities).toContain("ui.detailTab.register");
+    expect(manifest.capabilities).toContain("execution.workspaces.read");
+    expect(manifest.capabilities).toContain("project.workspaces.read");
+    expect(manifest.ui?.slots).toContainEqual(expect.objectContaining({
+      type: "detailTab",
+      displayName: "Changes",
+      entityTypes: ["execution_workspace", "project_workspace"],
+    }));
+  });
+
+  it("fetches changed execution workspace diffs from host metadata", async () => {
+    const root = await createGitWorkspace();
+    await fs.writeFile(path.join(root, "src/app.ts"), "export const value = 2;\n");
+    const harness = createTestHarness({ manifest });
+    harness.seed({
+      executionWorkspaces: [{
+        id: "workspace-1",
+        companyId: "company-1",
+        projectId: "project-1",
+        projectWorkspaceId: null,
+        path: root,
+        cwd: root,
+        repoUrl: null,
+        baseRef: "HEAD",
+        branchName: "main",
+        providerType: "git_worktree",
+        providerMetadata: null,
+      }],
+    });
+    await plugin.definition.setup(harness.ctx);
+
+    const result = await harness.getData("workspace-diff", {
+      workspaceId: "workspace-1",
+      companyId: "company-1",
+      view: "working-tree",
+      includeUntracked: false,
+      paths: ["src/app.ts"],
+    });
+
+    expect(result).toMatchObject({
+      stats: { fileCount: 1 },
+      files: [expect.objectContaining({ path: "src/app.ts" })],
+    });
+  });
+
+  it("returns an empty diff when the workspace has no changes", async () => {
+    const root = await createGitWorkspace();
+    const harness = createTestHarness({ manifest });
+    harness.seed({
+      executionWorkspaces: [{
+        id: "workspace-1",
+        companyId: "company-1",
+        projectId: "project-1",
+        projectWorkspaceId: null,
+        path: root,
+        cwd: root,
+        repoUrl: null,
+        baseRef: "HEAD",
+        branchName: "main",
+        providerType: "git_worktree",
+        providerMetadata: null,
+      }],
+    });
+    await plugin.definition.setup(harness.ctx);
+
+    await expect(harness.getData("workspace-diff", {
+      workspaceId: "workspace-1",
+      companyId: "company-1",
+    })).resolves.toMatchObject({ files: [], truncated: false });
+  });
+
+  it("fetches project workspace diffs from generic project workspace metadata", async () => {
+    const root = await createGitWorkspace();
+    await git(root, ["checkout", "-b", "feature"]);
+    await fs.writeFile(path.join(root, "src/app.ts"), "export const value = 3;\n");
+    await git(root, ["add", "src/app.ts"]);
+    await git(root, ["commit", "-m", "project workspace change"]);
+    const harness = createTestHarness({ manifest });
+    harness.ctx.projects.listWorkspaces = async (projectId, companyId) => {
+      expect(projectId).toBe("project-1");
+      expect(companyId).toBe("company-1");
+      return [{
+        id: "workspace-1",
+        projectId: "project-1",
+        name: "Primary",
+        path: root,
+        repoUrl: null,
+        repoRef: "feature",
+        defaultRef: "main",
+        isPrimary: true,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      }];
+    };
+    await plugin.definition.setup(harness.ctx);
+
+    const result = await harness.getData("workspace-diff", {
+      workspaceId: "workspace-1",
+      companyId: "company-1",
+      projectId: "project-1",
+      entityType: "project_workspace",
+      view: "head",
+      includeUntracked: false,
+    });
+
+    expect(result).toMatchObject({
+      baseRef: "main",
+      defaultBaseRef: "main",
+      stats: { fileCount: 1 },
+      files: [expect.objectContaining({ path: "src/app.ts" })],
+    });
+  });
+
+  it("resolves the default base ref from workspace and project workspace metadata", () => {
+    expect(resolveDefaultBaseRef({
+      workspaceBaseRef: " release/main ",
+      projectWorkspaceDefaultRef: "origin/main",
+      projectWorkspaceRepoRef: "feature",
+    })).toBe("release/main");
+    expect(resolveDefaultBaseRef({
+      workspaceBaseRef: null,
+      projectWorkspaceDefaultRef: " origin/main ",
+      projectWorkspaceRepoRef: "feature",
+    })).toBe("origin/main");
+    expect(resolveDefaultBaseRef({
+      workspaceBaseRef: "",
+      projectWorkspaceDefaultRef: null,
+      projectWorkspaceRepoRef: " feature ",
+    })).toBe("feature");
+    expect(resolveDefaultBaseRef({
+      workspaceBaseRef: "",
+      projectWorkspaceDefaultRef: null,
+      projectWorkspaceRepoRef: "",
+    })).toBeNull();
+  });
+
+  it("uses project workspace default refs for execution workspace head diffs", async () => {
+    const root = await createGitWorkspace();
+    await git(root, ["checkout", "-b", "feature"]);
+    await fs.writeFile(path.join(root, "src/app.ts"), "export const value = 4;\n");
+    await git(root, ["add", "src/app.ts"]);
+    await git(root, ["commit", "-m", "feature change"]);
+    const harness = createTestHarness({ manifest });
+    harness.seed({
+      executionWorkspaces: [{
+        id: "workspace-1",
+        companyId: "company-1",
+        projectId: "project-1",
+        projectWorkspaceId: "project-workspace-1",
+        path: root,
+        cwd: root,
+        repoUrl: null,
+        baseRef: null,
+        branchName: "feature",
+        providerType: "git_worktree",
+        providerMetadata: null,
+      }],
+    });
+    harness.ctx.projects.listWorkspaces = async (projectId, companyId) => {
+      expect(projectId).toBe("project-1");
+      expect(companyId).toBe("company-1");
+      return [{
+        id: "project-workspace-1",
+        projectId: "project-1",
+        name: "Primary",
+        path: root,
+        repoUrl: null,
+        repoRef: "feature",
+        defaultRef: "main",
+        isPrimary: true,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      }];
+    };
+    await plugin.definition.setup(harness.ctx);
+
+    const result = await harness.getData("workspace-diff", {
+      workspaceId: "workspace-1",
+      companyId: "company-1",
+      view: "head",
+      includeUntracked: false,
+    });
+
+    expect(result).toMatchObject({
+      baseRef: "main",
+      defaultBaseRef: "main",
+      stats: { fileCount: 1 },
+      files: [expect.objectContaining({ path: "src/app.ts" })],
+    });
+  });
+
+  it("returns a clear bridge error when required context is missing", async () => {
+    const harness = createTestHarness({ manifest });
+    await plugin.definition.setup(harness.ctx);
+
+    await expect(harness.getData("workspace-diff", {
+      workspaceId: "workspace-1",
+    })).rejects.toThrow("workspaceId and companyId are required");
+  });
+});

packages/plugins/plugin-workspace-diff/tests/ui-error-state.spec.ts

@@ -0,0 +1,20 @@
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { ErrorState } from "../src/ui/index.js";
+
+describe("workspace diff error state", () => {
+  it("keeps bridge error details out of the primary headline", () => {
+    const rawError = "Execution workspace not found";
+    const html = renderToStaticMarkup(createElement(ErrorState, {
+      message: rawError,
+      onRetry: () => undefined,
+    }));
+
+    expect(html).toContain("Unable to load workspace changes.");
+    expect(html).toContain("Retry");
+    expect(html).toContain("Troubleshooting details");
+    expect(html).not.toContain(`font-medium text-foreground">${rawError}`);
+    expect(html.indexOf(rawError)).toBeGreaterThan(html.indexOf("Troubleshooting details"));
+  });
+});

packages/plugins/plugin-workspace-diff/tests/workspace-diff.spec.ts

@@ -0,0 +1,200 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { afterEach, describe, expect, it } from "vitest";
+import type { PluginExecutionWorkspaceMetadata } from "@paperclipai/plugin-sdk";
+import type { WorkspaceDiffQueryOptions } from "../src/contracts.js";
+import { WORKSPACE_DIFF_CAPS, workspaceDiffService } from "../src/workspace-diff.js";
+
+const execFileAsync = promisify(execFile);
+const tempDirs = new Set<string>();
+
+async function runGit(cwd: string, args: string[]) {
+  await execFileAsync("git", ["-C", cwd, ...args], { cwd });
+}
+
+async function createTempRepo() {
+  const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-plugin-workspace-diff-"));
+  tempDirs.add(repoRoot);
+  await runGit(repoRoot, ["init"]);
+  await runGit(repoRoot, ["config", "user.name", "Paperclip Test"]);
+  await runGit(repoRoot, ["config", "user.email", "test@paperclip.local"]);
+  await fs.writeFile(path.join(repoRoot, "tracked-staged.txt"), "alpha\n", "utf8");
+  await fs.writeFile(path.join(repoRoot, "tracked-unstaged.txt"), "bravo\n", "utf8");
+  await fs.writeFile(path.join(repoRoot, "delete-me.txt"), "charlie\n", "utf8");
+  await fs.writeFile(path.join(repoRoot, "rename-me.txt"), "delta\n", "utf8");
+  await fs.writeFile(path.join(repoRoot, "binary.bin"), Buffer.from([0, 1, 2, 3]));
+  await runGit(repoRoot, ["add", "."]);
+  await runGit(repoRoot, ["commit", "-m", "Initial commit"]);
+  await runGit(repoRoot, ["branch", "-M", "main"]);
+  return repoRoot;
+}
+
+function createWorkspace(cwd: string | null, overrides: Partial<PluginExecutionWorkspaceMetadata> = {}): PluginExecutionWorkspaceMetadata {
+  return {
+    id: randomUUID(),
+    companyId: randomUUID(),
+    projectId: randomUUID(),
+    projectWorkspaceId: null,
+    path: cwd,
+    cwd,
+    repoUrl: null,
+    baseRef: null,
+    branchName: "feature",
+    providerType: "git_worktree",
+    providerMetadata: null,
+    ...overrides,
+  };
+}
+
+function workingTreeQuery(overrides: Partial<WorkspaceDiffQueryOptions> = {}): WorkspaceDiffQueryOptions {
+  return {
+    view: "working-tree",
+    baseRef: null,
+    includeUntracked: true,
+    paths: [],
+    ...overrides,
+  };
+}
+
+afterEach(async () => {
+  for (const dir of tempDirs) {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+  tempDirs.clear();
+});
+
+describe("plugin workspace diff service", () => {
+  it("returns staged, unstaged, renamed, deleted, untracked, binary, and oversized working-tree changes", async () => {
+    const repoRoot = await createTempRepo();
+    await fs.writeFile(path.join(repoRoot, "tracked-staged.txt"), "alpha\nstaged\n", "utf8");
+    await runGit(repoRoot, ["add", "tracked-staged.txt"]);
+    await fs.writeFile(path.join(repoRoot, "tracked-unstaged.txt"), "bravo\nunstaged\n", "utf8");
+    await runGit(repoRoot, ["mv", "rename-me.txt", "renamed.txt"]);
+    await fs.rm(path.join(repoRoot, "delete-me.txt"));
+    await fs.writeFile(path.join(repoRoot, "binary.bin"), Buffer.from([0, 1, 2, 3, 4, 5]));
+    await fs.writeFile(path.join(repoRoot, "untracked.txt"), "brand new\n", "utf8");
+    await fs.writeFile(path.join(repoRoot, "empty-untracked.txt"), "", "utf8");
+    await fs.writeFile(path.join(repoRoot, "oversized.txt"), "x".repeat(WORKSPACE_DIFF_CAPS.maxFileBytes + 1), "utf8");
+
+    const diff = await workspaceDiffService().getDiff(createWorkspace(repoRoot), workingTreeQuery());
+    const byPath = new Map(diff.files.map((file) => [file.path, file]));
+
+    expect(diff.view).toBe("working-tree");
+    expect(byPath.get("tracked-staged.txt")).toMatchObject({ staged: true, unstaged: false, status: "modified", additions: 1 });
+    expect(byPath.get("tracked-staged.txt")?.patches.map((patch) => patch.kind)).toEqual(["staged"]);
+    expect(byPath.get("tracked-unstaged.txt")).toMatchObject({ staged: false, unstaged: true, status: "modified", additions: 1 });
+    expect(byPath.get("renamed.txt")).toMatchObject({ oldPath: "rename-me.txt", staged: true, status: "renamed" });
+    expect(byPath.get("delete-me.txt")).toMatchObject({ unstaged: true, status: "deleted", deletions: 1 });
+    expect(byPath.get("untracked.txt")).toMatchObject({ untracked: true, status: "untracked", additions: 1 });
+    expect(byPath.get("untracked.txt")?.patches[0]?.patch).toContain("+brand new");
+    expect(byPath.get("empty-untracked.txt")?.patches[0]?.patch).toBe([
+      "diff --git a/empty-untracked.txt b/empty-untracked.txt",
+      "new file mode 100644",
+      "--- /dev/null",
+      "+++ b/empty-untracked.txt",
+      "",
+    ].join("\n"));
+    expect(byPath.get("binary.bin")).toMatchObject({ binary: true, unstaged: true });
+    expect(byPath.get("oversized.txt")).toMatchObject({ oversized: true, untracked: true });
+    expect(diff.warnings.map((item) => item.code)).toEqual(expect.arrayContaining(["binary_file", "file_oversized"]));
+  }, 20_000);
+
+  it("returns head diffs against the requested base ref", async () => {
+    const repoRoot = await createTempRepo();
+    await runGit(repoRoot, ["checkout", "-b", "feature"]);
+    await fs.writeFile(path.join(repoRoot, "tracked-staged.txt"), "alpha\ncommitted\n", "utf8");
+    await runGit(repoRoot, ["add", "tracked-staged.txt"]);
+    await runGit(repoRoot, ["commit", "-m", "Feature change"]);
+
+    const diff = await workspaceDiffService().getDiff(
+      createWorkspace(repoRoot, { baseRef: "main" }),
+      workingTreeQuery({ view: "head", includeUntracked: false }),
+    );
+
+    expect(diff.baseRef).toBe("main");
+    expect(diff.files).toHaveLength(1);
+    expect(diff.files[0]).toMatchObject({
+      path: "tracked-staged.txt",
+      staged: false,
+      unstaged: false,
+      untracked: false,
+      additions: 1,
+      deletions: 0,
+    });
+    expect(diff.files[0]?.patches.map((patch) => patch.kind)).toEqual(["head"]);
+  }, 20_000);
+
+  it("filters changed files by relative workspace paths", async () => {
+    const repoRoot = await createTempRepo();
+    await fs.writeFile(path.join(repoRoot, "tracked-staged.txt"), "alpha\none\n", "utf8");
+    await fs.writeFile(path.join(repoRoot, "tracked-unstaged.txt"), "bravo\ntwo\n", "utf8");
+
+    const diff = await workspaceDiffService().getDiff(
+      createWorkspace(repoRoot),
+      workingTreeQuery({ paths: ["tracked-staged.txt"] }),
+    );
+
+    expect(diff.paths).toEqual(["tracked-staged.txt"]);
+    expect(diff.files.map((file) => file.path)).toEqual(["tracked-staged.txt"]);
+  }, 20_000);
+
+  it("applies output caps to large workspace responses", async () => {
+    const repoRoot = await createTempRepo();
+    for (let index = 0; index < WORKSPACE_DIFF_CAPS.maxFiles + 1; index += 1) {
+      await fs.writeFile(path.join(repoRoot, `untracked-${String(index).padStart(3, "0")}.txt`), "", "utf8");
+    }
+
+    const diff = await workspaceDiffService().getDiff(createWorkspace(repoRoot), workingTreeQuery());
+
+    expect(diff.files).toHaveLength(WORKSPACE_DIFF_CAPS.maxFiles);
+    expect(diff.truncated).toBe(true);
+    expect(diff.warnings).toContainEqual(expect.objectContaining({ code: "file_count_truncated" }));
+  }, 20_000);
+
+  it("does not follow untracked symlinks outside the repo", async () => {
+    const repoRoot = await createTempRepo();
+    const outsideDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-plugin-workspace-diff-secret-"));
+    tempDirs.add(outsideDir);
+    const secretContent = "external secret should not appear\n";
+    const secretPath = path.join(outsideDir, "secret.txt");
+    await fs.writeFile(secretPath, secretContent, "utf8");
+    await fs.symlink(secretPath, path.join(repoRoot, "leak.txt"));
+
+    const diff = await workspaceDiffService().getDiff(createWorkspace(repoRoot), workingTreeQuery());
+    const leak = diff.files.find((file) => file.path === "leak.txt");
+    const serialized = JSON.stringify(diff);
+
+    expect(leak).toMatchObject({ untracked: true, status: "untracked", additions: 0, sizeBytes: null });
+    expect(leak?.patches[0]).toMatchObject({
+      kind: "untracked",
+      patch: null,
+      warnings: [expect.objectContaining({ code: "symlink_target_outside_workspace" })],
+    });
+    expect(diff.warnings).toContainEqual(expect.objectContaining({
+      code: "symlink_target_outside_workspace",
+      path: "leak.txt",
+    }));
+    expect(serialized).not.toContain(secretContent.trim());
+  }, 20_000);
+
+  it("surfaces missing cwd, non-git, invalid base refs, and unsafe path filters as plugin errors", async () => {
+    const svc = workspaceDiffService();
+    await expect(svc.getDiff(createWorkspace(null), workingTreeQuery()))
+      .rejects.toMatchObject({ status: 422, details: { code: "missing_cwd" } });
+
+    const nonGitDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-plugin-workspace-diff-non-git-"));
+    tempDirs.add(nonGitDir);
+    await expect(svc.getDiff(createWorkspace(nonGitDir), workingTreeQuery()))
+      .rejects.toMatchObject({ status: 422, details: { code: "non_git_workspace" } });
+
+    const repoRoot = await createTempRepo();
+    await expect(svc.getDiff(createWorkspace(repoRoot), workingTreeQuery({ paths: ["../secret"] })))
+      .rejects.toMatchObject({ status: 422, details: { code: "path_filter_invalid" } });
+    await expect(svc.getDiff(createWorkspace(repoRoot), workingTreeQuery({ view: "head", baseRef: "missing-ref" })))
+      .rejects.toMatchObject({ status: 422, details: { code: "base_ref_invalid" } });
+  }, 20_000);
+});