@bevel-software/platform-core-backend 0.1.0

package/src/modules/diff/__tests__/diff.routes.rejectPathsLocked.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { IDiffService } from '../diff.interface.js';
+import { workspaceIdForBranch } from '../../workspace/workspace.service.js';
+import { WorkflowValidationError } from '../../workflow/workflow.errors.js';
+import { rejectPathsLocked } from '../diff.routes.js';
+
+/**
+ * `rejectPathsLocked` — the BATCH reject. All paths go through ONE
+ * `LockingFilesystem.writeFiles` cycle: every lock acquired before the first
+ * disk mutation, baselines restored / agent-added files deleted, then a single
+ * `commitChanges` and lock release. Fail-closed: contention or a commit error
+ * aborts with nothing committed.
+ */
+
+const USER: AuthUser = { id: 'user-1', email: 'alice@example.com', name: 'Alice' };
+const BRANCH = 'alice/revert-test';
+const WORKSPACE_ID = workspaceIdForBranch(BRANCH);
+
+interface Harness {
+  workflow: IWorkflowService;
+  diff: IDiffService;
+  calls: string[];
+  workspaceDir: string;
+}
+
+async function makeHarness(overrides: {
+  /** Per-path acquire outcome. Default: every path acquires cleanly. */
+  acquire?: (relPath: string) => { acquired: boolean; lock: { holderName: string } };
+  /** Throw from commitChanges to simulate a commit failure. */
+  commit?: () => void;
+} = {}): Promise<Harness> {
+  const calls: string[] = [];
+  const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-reject-'));
+  // Baseline-carrying file (backup exists → revert = write baseline bytes)
+  // and an agent-added file (no backup → revert = delete).
+  await fs.mkdir(path.join(workspaceDir, 'knowledge-base'), { recursive: true });
+  await fs.writeFile(path.join(workspaceDir, 'knowledge-base/a.md'), 'agent version\n');
+  await fs.writeFile(path.join(workspaceDir, 'knowledge-base/added.md'), 'agent-added\n');
+
+  const acquireLock = vi.fn(async (_ws: string, _branch: string, relPath: string) => {
+    const result = overrides.acquire
+      ? overrides.acquire(relPath)
+      : { acquired: true, lock: { holderName: 'Alice' } };
+    calls.push(`acquire:${relPath}:${result.acquired}`);
+    return result;
+  });
+  const releaseLockNoCommit = vi.fn(async (_ws: string, _branch: string, relPath: string) => {
+    calls.push(`releaseNoCommit:${relPath}`);
+  });
+  const commitChanges = vi.fn(async (_ws: string, _user: AuthUser, summary: string) => {
+    calls.push(`commit:${summary}`);
+    overrides.commit?.();
+    return { sha: 'abc', summary } as never;
+  });
+  const workflow = { acquireLock, releaseLockNoCommit, commitChanges } as unknown as IWorkflowService;
+
+  const revertPlan = vi.fn(async (_ws: string, paths: string[]) => ({
+    workspaceDir,
+    writes: paths
+      .filter((p) => p.endsWith('a.md'))
+      .map((p) => ({ path: p, content: Buffer.from('baseline\n') })),
+    deletes: paths.filter((p) => p.endsWith('added.md')),
+  }));
+  const diff = { revertPlan } as unknown as IDiffService;
+  return { workflow, diff, calls, workspaceDir };
+}
+
+describe('rejectPathsLocked', () => {
+  let workspaceDir: string | undefined;
+  beforeEach(() => {
+    workspaceDir = undefined;
+  });
+  afterEach(async () => {
+    if (workspaceDir) await fs.rm(workspaceDir, { recursive: true, force: true });
+  });
+
+  it('acquires EVERY lock before mutating, restores + deletes, then commits ONCE and releases', async () => {
+    const h = await makeHarness();
+    workspaceDir = h.workspaceDir;
+
+    await rejectPathsLocked(h.workflow, h.diff, WORKSPACE_ID, USER, [
+      'knowledge-base/a.md',
+      'knowledge-base/added.md',
+    ]);
+
+    // All locks first (sorted), ONE commit, then per-path release (no per-file commit).
+    expect(h.calls).toEqual([
+      'acquire:knowledge-base/a.md:true',
+      'acquire:knowledge-base/added.md:true',
+      'commit:Revert agent changes (2 files)',
+      'releaseNoCommit:knowledge-base/a.md',
+      'releaseNoCommit:knowledge-base/added.md',
+    ]);
+    // Disk: baseline restored, agent-added file gone.
+    expect(await fs.readFile(path.join(h.workspaceDir, 'knowledge-base/a.md'), 'utf-8')).toBe('baseline\n');
+    await expect(fs.access(path.join(h.workspaceDir, 'knowledge-base/added.md'))).rejects.toThrow();
+  });
+
+  it('is a no-op for an empty path list', async () => {
+    const h = await makeHarness();
+    workspaceDir = h.workspaceDir;
+    await expect(
+      rejectPathsLocked(h.workflow, h.diff, WORKSPACE_ID, USER, []),
+    ).resolves.toBeUndefined();
+    expect(h.calls).toEqual([]);
+  });
+
+  it('fails CLOSED on a contended lock: nothing mutated, nothing committed', async () => {
+    const h = await makeHarness({
+      acquire: (relPath) =>
+        relPath.endsWith('added.md')
+          ? { acquired: false, lock: { holderName: 'Bob' } }
+          : { acquired: true, lock: { holderName: 'Alice' } },
+    });
+    workspaceDir = h.workspaceDir;
+
+    await expect(
+      rejectPathsLocked(h.workflow, h.diff, WORKSPACE_ID, USER, [
+        'knowledge-base/a.md',
+        'knowledge-base/added.md',
+      ]),
+    ).rejects.toBeInstanceOf(WorkflowValidationError);
+
+    // No commit landed and the disk is untouched — the batch is atomic.
+    expect(h.calls.some((c) => c.startsWith('commit:'))).toBe(false);
+    expect(await fs.readFile(path.join(h.workspaceDir, 'knowledge-base/a.md'), 'utf-8')).toBe('agent version\n');
+    await expect(fs.access(path.join(h.workspaceDir, 'knowledge-base/added.md'))).resolves.toBeUndefined();
+  }, 15_000);
+
+  it('surfaces a commit failure as a WorkflowValidationError and releases without committing', async () => {
+    const h = await makeHarness({
+      commit: () => {
+        throw new Error('push rejected');
+      },
+    });
+    workspaceDir = h.workspaceDir;
+
+    await expect(
+      rejectPathsLocked(h.workflow, h.diff, WORKSPACE_ID, USER, [
+        'knowledge-base/a.md',
+      ]),
+    ).rejects.toBeInstanceOf(WorkflowValidationError);
+    // Locks were dropped via the no-commit path after the failure.
+    expect(h.calls.filter((c) => c.startsWith('releaseNoCommit:'))).toHaveLength(1);
+  });
+});

package/src/modules/diff/__tests__/diff.service.seed-atomicity.test.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { WorkspaceService, workspaceIdForBranch } from '../../workspace/workspace.service.js';
+import { WorkspaceMutex } from '../../workflow/git/mutex.js';
+import { DiffService } from '../diff.service.js';
+
+/**
+ * Atomic-seed regression suite.
+ *
+ * Bug we're guarding against (reproduced once in production): two users
+ * switch to a fresh, not-yet-cloned branch concurrently. One of them sees
+ * EVERY cloned file as an `added` pending change.
+ *
+ * Root cause: the original `ensureSeededUnlocked` did `mkdir(backupDir)`
+ * THEN `copyDiffableTree(...)`. If the copy threw mid-stream (any I/O
+ * hiccup, EACCES on one file, the process restarted, …) `backupDir`
+ * already existed but was empty. The next call's `fs.access(backupDir)`
+ * succeeded → skipped seeding → `listPendingUnlocked` saw "workspace has
+ * files, backup is empty" and produced phantom `added` entries for every
+ * cloned file.
+ *
+ * Fix: stage into `<backupDir>.seed-<rand>`, then `fs.rename` to commit.
+ * Either the fully-seeded backup appears at its canonical path, or
+ * nothing does and the next caller retries from scratch. Same pattern
+ * applies to `reseedUnlocked` (branch-switch hook).
+ */
+
+const TEST_BRANCH = 'seed-test-branch';
+
+interface Fixture {
+  workspacesRoot: string;
+  backupsRoot: string;
+  workspaceDir: string;
+  repoDir: string;
+  workspaceId: string;
+  workspaceService: WorkspaceService;
+  diffService: DiffService;
+}
+
+async function mkTmpRoot(prefix: string): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), prefix));
+}
+
+async function setup(): Promise<Fixture> {
+  const workspacesRoot = await mkTmpRoot('bevel-seed-ws-');
+  const backupsRoot = await mkTmpRoot('bevel-seed-backup-');
+  const workspaceId = workspaceIdForBranch(TEST_BRANCH);
+  const workspaceDir = path.join(workspacesRoot, workspaceId);
+  const repoDir = path.join(workspaceDir, 'knowledge-base');
+  await fs.mkdir(path.join(repoDir, '.git'), { recursive: true });
+  const workspaceService = new WorkspaceService(
+    workspacesRoot,
+    'https://github.com/Bevel-Software/knowledge-base.git',
+    'knowledge-base',
+  );
+  const mutex = new WorkspaceMutex();
+  const diffService = new DiffService(
+    workspaceService,
+    mutex,
+    workspacesRoot,
+    backupsRoot,
+    'knowledge-base',
+  );
+  workspaceService.setDiffService(diffService);
+  return { workspacesRoot, backupsRoot, workspaceDir, repoDir, workspaceId, workspaceService, diffService };
+}
+
+async function teardown(fx: Fixture): Promise<void> {
+  await fs.rm(fx.workspacesRoot, { recursive: true, force: true });
+  await fs.rm(fx.backupsRoot, { recursive: true, force: true });
+}
+
+async function listDirEntries(dir: string): Promise<string[]> {
+  try {
+    return await fs.readdir(dir);
+  } catch {
+    return [];
+  }
+}
+
+describe('DiffService — atomic seed (production regression suite)', () => {
+  let fx: Fixture;
+  beforeEach(async () => { fx = await setup(); });
+  afterEach(async () => { await teardown(fx); });
+
+  it('a failed seed leaves NO backupDir behind — the next call retries from scratch', async () => {
+    // Stub `fs.copyFile` so the inner copy throws partway through. The
+    // seed must then clean up its staging dir AND propagate the error
+    // without leaving a phantom backup root. Otherwise the next seed
+    // would no-op on the empty backupDir and report every file as
+    // `added`.
+    await fs.writeFile(path.join(fx.repoDir, 'a.md'), 'a\n', 'utf-8');
+    await fs.writeFile(path.join(fx.repoDir, 'b.md'), 'b\n', 'utf-8');
+
+    const copySpy = vi.spyOn(fs, 'copyFile').mockRejectedValueOnce(new Error('disk full'));
+    await expect(fx.diffService.currentSession(fx.workspaceId)).rejects.toThrow(/disk full/);
+    copySpy.mockRestore();
+
+    // The CANONICAL backupDir must not exist.
+    const backupDir = path.join(fx.backupsRoot, fx.workspaceId);
+    await expect(fs.access(backupDir)).rejects.toThrow();
+
+    // And no staging dirs left behind (the production symptom of the
+    // old bug was the directory shell sitting there empty).
+    const siblings = await listDirEntries(fx.backupsRoot);
+    expect(siblings).toEqual([]);
+
+    // A follow-up call with the failure cleared seeds cleanly and
+    // reports no pending changes.
+    const session = await fx.diffService.currentSession(fx.workspaceId);
+    expect(session).toBeNull();
+    expect(await fs.readFile(path.join(backupDir, 'knowledge-base', 'a.md'), 'utf-8')).toBe('a\n');
+  });
+
+  it('two concurrent seeds against the same workspace produce a single backup with no phantom pending', async () => {
+    // Mutex-serialised in practice, but we exercise the concurrency
+    // anyway so a future refactor that drops the mutex still has to
+    // keep the seed atomic. Both callers should observe `session === null`
+    // (workspace == backup); neither should see phantom `added` entries.
+    await fs.writeFile(path.join(fx.repoDir, 'foo.md'), 'foo\n', 'utf-8');
+    await fs.writeFile(path.join(fx.repoDir, 'bar.md'), 'bar\n', 'utf-8');
+
+    const [s1, s2] = await Promise.all([
+      fx.diffService.currentSession(fx.workspaceId),
+      fx.diffService.currentSession(fx.workspaceId),
+    ]);
+
+    expect(s1).toBeNull();
+    expect(s2).toBeNull();
+
+    // Backup is fully populated.
+    const backupRepo = path.join(fx.backupsRoot, fx.workspaceId, 'knowledge-base');
+    expect(await fs.readFile(path.join(backupRepo, 'foo.md'), 'utf-8')).toBe('foo\n');
+    expect(await fs.readFile(path.join(backupRepo, 'bar.md'), 'utf-8')).toBe('bar\n');
+
+    // No stray staging dirs.
+    const entries = await listDirEntries(fx.backupsRoot);
+    expect(entries).toEqual([fx.workspaceId]);
+  });
+
+  it('reseed (branch-switch hook) leaves the previous backup intact when the new copy fails', async () => {
+    // The branch-switch reseed wipes the existing backup and replaces it
+    // with a fresh copy of the new branch's working tree. If the copy
+    // fails mid-stream, we must NOT vaporise the old backup — the user
+    // would otherwise see every file on the OLD branch flip to pending.
+    await fs.writeFile(path.join(fx.repoDir, 'a.md'), 'before\n', 'utf-8');
+    // Seed the initial backup.
+    await fx.diffService.currentSession(fx.workspaceId);
+    const backupFile = path.join(fx.backupsRoot, fx.workspaceId, 'knowledge-base', 'a.md');
+    expect(await fs.readFile(backupFile, 'utf-8')).toBe('before\n');
+
+    // Disk advances (e.g. branch checkout swapped the bytes), then reseed.
+    await fs.writeFile(path.join(fx.repoDir, 'a.md'), 'after\n', 'utf-8');
+    const copySpy = vi.spyOn(fs, 'copyFile').mockRejectedValueOnce(new Error('disk full'));
+    await expect(fx.diffService.resetBackup(fx.workspaceId)).rejects.toThrow(/disk full/);
+    copySpy.mockRestore();
+
+    // The OLD backup is still there. `listPendingUnlocked` sees `after`
+    // on disk vs `before` in backup → one modified entry (correct
+    // behavior because the new bytes haven't been promoted yet).
+    expect(await fs.readFile(backupFile, 'utf-8')).toBe('before\n');
+    const session = await fx.diffService.currentSession(fx.workspaceId);
+    expect(session?.changes.length).toBe(1);
+    expect(session!.changes[0]).toMatchObject({
+      path: 'knowledge-base/a.md',
+      kind: 'modified',
+    });
+  });
+
+  it('reseed succeeds: old backup vaporised, new backup matches new disk state, session is clean', async () => {
+    await fs.writeFile(path.join(fx.repoDir, 'a.md'), 'v1\n', 'utf-8');
+    await fx.diffService.currentSession(fx.workspaceId);
+    // Branch switched (simulated): disk now has different bytes.
+    await fs.writeFile(path.join(fx.repoDir, 'a.md'), 'v2\n', 'utf-8');
+    await fx.diffService.resetBackup(fx.workspaceId);
+
+    // Backup advanced; session reports no drift.
+    const backupFile = path.join(fx.backupsRoot, fx.workspaceId, 'knowledge-base', 'a.md');
+    expect(await fs.readFile(backupFile, 'utf-8')).toBe('v2\n');
+    expect(await fx.diffService.currentSession(fx.workspaceId)).toBeNull();
+  });
+});

package/src/modules/diff/__tests__/diff.service.test.ts

@@ -0,0 +1,202 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { WorkspaceService, workspaceIdForBranch } from '../../workspace/workspace.service.js';
+import { WorkspaceMutex } from '../../workflow/git/mutex.js';
+import { DiffService } from '../diff.service.js';
+
+async function mkTmpRoot(prefix: string): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), prefix));
+}
+
+// Workspace-per-branch (PLAN §3) — the test fixture uses a fake branch
+// `diff-test-branch`. The workspace id is `encodeURIComponent(branch)`
+// and the on-disk path is `<workspacesRoot>/<id>/<kbDirName>/`. We
+// pre-seed the inner `.git` so `WorkspaceService.resolveWorkspaceDir`
+// accepts the path without falling back to the clone-from-origin
+// bootstrap that the unit suite can't perform.
+const TEST_BRANCH = 'diff-test-branch';
+
+interface Fixture {
+  workspacesRoot: string;
+  backupsRoot: string;
+  workspaceDir: string;
+  repoDir: string;
+  workspaceId: string;
+  workspaceService: WorkspaceService;
+  diffService: DiffService;
+}
+
+async function setup(): Promise<Fixture> {
+  const workspacesRoot = await mkTmpRoot('bevel-diff-ws-');
+  const backupsRoot = await mkTmpRoot('bevel-diff-backup-');
+  const workspaceId = workspaceIdForBranch(TEST_BRANCH);
+  const workspaceDir = path.join(workspacesRoot, workspaceId);
+  const repoDir = path.join(workspaceDir, 'knowledge-base');
+  // Inner `.git` dir is the marker `resolveWorkspaceDir` looks for.
+  await fs.mkdir(path.join(repoDir, '.git'), { recursive: true });
+  const workspaceService = new WorkspaceService(
+    workspacesRoot,
+    'https://github.com/Bevel-Software/knowledge-base.git',
+    'knowledge-base',
+  );
+  const mutex = new WorkspaceMutex();
+  const diffService = new DiffService(
+    workspaceService,
+    mutex,
+    workspacesRoot,
+    backupsRoot,
+    'knowledge-base',
+  );
+  workspaceService.setDiffService(diffService);
+  return { workspacesRoot, backupsRoot, workspaceDir, repoDir, workspaceId, workspaceService, diffService };
+}
+
+async function teardown(fx: Fixture): Promise<void> {
+  await fs.rm(fx.workspacesRoot, { recursive: true, force: true });
+  await fs.rm(fx.backupsRoot, { recursive: true, force: true });
+}
+
+describe('DiffService', () => {
+  let fx: Fixture;
+  beforeEach(async () => { fx = await setup(); });
+  afterEach(async () => { await teardown(fx); });
+
+  it('seeds the backup folder lazily on first session read and reports no drift on a clean tree', async () => {
+    await fs.writeFile(path.join(fx.repoDir, 'foo.md'), '# Hello\n', 'utf-8');
+    const session = await fx.diffService.currentSession(fx.workspaceId);
+    // Nothing pending — disk == backup after seed.
+    expect(session).toBeNull();
+    // Backup file was written.
+    const backupPath = path.join(fx.backupsRoot, fx.workspaceId, 'knowledge-base', 'foo.md');
+    expect(await fs.readFile(backupPath, 'utf-8')).toBe('# Hello\n');
+  });
+
+  it('surfaces an agent-created untracked file as added (the juju.md regression)', async () => {
+    // First session call seeds with no diffable files.
+    await fx.diffService.currentSession(fx.workspaceId);
+    // Agent writes a new file directly to disk (bypassing WorkspaceService).
+    await fs.writeFile(path.join(fx.repoDir, 'juju.md'), '# new\n', 'utf-8');
+    const session = await fx.diffService.currentSession(fx.workspaceId);
+    expect(session?.changes.length).toBe(1);
+    expect(session!.changes[0]).toMatchObject({
+      path: 'knowledge-base/juju.md',
+      kind: 'added',
+      isBinary: false,
+    });
+  });
+
+  it('user-saved edit through WorkspaceService advances the backup so it does NOT show as pending', async () => {
+    await fs.writeFile(path.join(fx.repoDir, 'foo.md'), 'before\n', 'utf-8');
+    await fx.diffService.currentSession(fx.workspaceId); // seed
+    // User edit goes through WorkspaceService → triggers diffService.syncFromDisk.
+    await fx.workspaceService.writeFile(fx.workspaceId, 'knowledge-base/foo.md', 'after\n');
+    const session = await fx.diffService.currentSession(fx.workspaceId);
+    expect(session).toBeNull(); // backup advanced; no drift
+  });
+
+  it('detects a modified file (agent edit on top of seeded backup)', async () => {
+    await fs.writeFile(path.join(fx.repoDir, 'foo.md'), 'before\n', 'utf-8');
+    await fx.diffService.currentSession(fx.workspaceId); // seed
+    // Agent edits via shell — disk only.
+    await fs.writeFile(path.join(fx.repoDir, 'foo.md'), 'after\n', 'utf-8');
+    const session = await fx.diffService.currentSession(fx.workspaceId);
+    expect(session?.changes[0]).toMatchObject({
+      path: 'knowledge-base/foo.md',
+      kind: 'modified',
+      linesAdded: 1,
+      linesRemoved: 1,
+    });
+  });
+
+  it('acceptOne promotes disk → backup so the next session is clean', async () => {
+    await fs.writeFile(path.join(fx.repoDir, 'foo.md'), 'v1\n', 'utf-8');
+    await fx.diffService.currentSession(fx.workspaceId);
+    await fs.writeFile(path.join(fx.repoDir, 'foo.md'), 'v2\n', 'utf-8');
+    expect((await fx.diffService.currentSession(fx.workspaceId))?.changes.length).toBe(1);
+    await fx.diffService.acceptOne(fx.workspaceId, 'knowledge-base/foo.md');
+    expect(await fx.diffService.currentSession(fx.workspaceId)).toBeNull();
+  });
+
+  it('acceptAll with an allow-list accepts only those paths in ONE batch; the rest stay pending', async () => {
+    // The accept route passes the caller's READABLE paths — a restricted node
+    // must stay pending. One service call covers the whole batch (looping
+    // acceptOne per path re-walks the workspace per file, O(changes × files)).
+    await fs.writeFile(path.join(fx.repoDir, 'a.md'), 'v1\n', 'utf-8');
+    await fs.writeFile(path.join(fx.repoDir, 'b.md'), 'v1\n', 'utf-8');
+    await fx.diffService.currentSession(fx.workspaceId); // seed
+    await fs.writeFile(path.join(fx.repoDir, 'a.md'), 'v2\n', 'utf-8');
+    await fs.writeFile(path.join(fx.repoDir, 'b.md'), 'v2\n', 'utf-8');
+    expect((await fx.diffService.currentSession(fx.workspaceId))?.changes.length).toBe(2);
+    await fx.diffService.acceptAll(fx.workspaceId, ['knowledge-base/a.md']);
+    const session = await fx.diffService.currentSession(fx.workspaceId);
+    expect(session?.changes.map((c) => c.path)).toEqual(['knowledge-base/b.md']);
+  });
+
+  it('acceptAll without an allow-list accepts everything', async () => {
+    await fs.writeFile(path.join(fx.repoDir, 'a.md'), 'v1\n', 'utf-8');
+    await fx.diffService.currentSession(fx.workspaceId); // seed
+    await fs.writeFile(path.join(fx.repoDir, 'a.md'), 'v2\n', 'utf-8');
+    await fx.diffService.acceptAll(fx.workspaceId);
+    expect(await fx.diffService.currentSession(fx.workspaceId)).toBeNull();
+  });
+
+  it('rejectOne restores disk ← backup', async () => {
+    await fs.writeFile(path.join(fx.repoDir, 'foo.md'), 'v1\n', 'utf-8');
+    await fx.diffService.currentSession(fx.workspaceId);
+    await fs.writeFile(path.join(fx.repoDir, 'foo.md'), 'v2\n', 'utf-8');
+    await fx.diffService.rejectOne(fx.workspaceId, 'knowledge-base/foo.md');
+    expect(await fs.readFile(path.join(fx.repoDir, 'foo.md'), 'utf-8')).toBe('v1\n');
+  });
+
+  it('rejectOne on an agent-created file removes it from disk', async () => {
+    await fx.diffService.currentSession(fx.workspaceId); // seed (empty)
+    await fs.writeFile(path.join(fx.repoDir, 'created.md'), 'agent\n', 'utf-8');
+    await fx.diffService.rejectOne(fx.workspaceId, 'knowledge-base/created.md');
+    await expect(fs.access(path.join(fx.repoDir, 'created.md'))).rejects.toThrow();
+  });
+
+  it('non-diffable extensions never enter the pending list', async () => {
+    await fs.writeFile(path.join(fx.repoDir, 'image.png'), Buffer.from([0xff, 0xd8, 0xff]));
+    await fx.diffService.currentSession(fx.workspaceId);
+    // Agent writes another binary.
+    await fs.writeFile(path.join(fx.repoDir, 'other.png'), Buffer.from([0x89, 0x50, 0x4e]));
+    expect(await fx.diffService.currentSession(fx.workspaceId)).toBeNull();
+  });
+
+  it('resetBackup wipes + reseeds (branch-switch hook): pending agent change disappears', async () => {
+    await fs.writeFile(path.join(fx.repoDir, 'foo.md'), 'v1\n', 'utf-8');
+    await fx.diffService.currentSession(fx.workspaceId);
+    await fs.writeFile(path.join(fx.repoDir, 'foo.md'), 'v2\n', 'utf-8');
+    expect((await fx.diffService.currentSession(fx.workspaceId))?.changes.length).toBe(1);
+    await fx.diffService.resetBackup(fx.workspaceId);
+    expect(await fx.diffService.currentSession(fx.workspaceId)).toBeNull();
+  });
+
+  it('rejects path-traversal attempts (must use a diffable extension to even reach the path check)', async () => {
+    await fs.writeFile(path.join(fx.repoDir, 'foo.md'), 'x', 'utf-8');
+    await fx.diffService.currentSession(fx.workspaceId);
+    await expect(
+      fx.diffService.acceptOne(fx.workspaceId, '../../../etc/passwd.md'),
+    ).rejects.toThrow(/Path traversal/);
+  });
+
+  it('reports kind=deleted when the user deletes a file via WorkspaceService — backup drops, no phantom', async () => {
+    await fs.writeFile(path.join(fx.repoDir, 'foo.md'), 'x', 'utf-8');
+    await fx.diffService.currentSession(fx.workspaceId); // seeds backup with foo.md
+    await fx.workspaceService.deleteFile(fx.workspaceId, 'knowledge-base/foo.md');
+    expect(await fx.diffService.currentSession(fx.workspaceId)).toBeNull();
+  });
+
+  it('agent-deleted file (disk-rm without WorkspaceService) shows as kind=deleted', async () => {
+    await fs.writeFile(path.join(fx.repoDir, 'foo.md'), 'x\n', 'utf-8');
+    await fx.diffService.currentSession(fx.workspaceId); // seed
+    await fs.rm(path.join(fx.repoDir, 'foo.md'));
+    const session = await fx.diffService.currentSession(fx.workspaceId);
+    expect(session?.changes[0]).toMatchObject({
+      path: 'knowledge-base/foo.md',
+      kind: 'deleted',
+    });
+  });
+});

package/src/modules/diff/diff-paths.ts

@@ -0,0 +1,9 @@
+import path from 'node:path';
+
+export function assertWithinDirectory(absolutePath: string, dir: string): void {
+  const resolved = path.resolve(absolutePath);
+  const root = path.resolve(dir);
+  if (!resolved.startsWith(root + path.sep) && resolved !== root) {
+    throw new Error('Path traversal detected');
+  }
+}

package/src/modules/diff/diff.config.ts

@@ -0,0 +1,12 @@
+/**
+ * File extensions that participate in diff review.
+ * Only these extensions get backup copies under <backupsRoot>/<userId>/...
+ * and surface in the pending-changes list.
+ */
+export const DIFFABLE_EXTENSIONS: ReadonlySet<string> = new Set(['.md']);
+
+export function isDiffable(filePath: string): boolean {
+  const dot = filePath.lastIndexOf('.');
+  if (dot < 0) return false;
+  return DIFFABLE_EXTENSIONS.has(filePath.slice(dot).toLowerCase());
+}

package/src/modules/diff/diff.interface.ts

@@ -0,0 +1,78 @@
+import type { FileDiffPayload, ReviewSession } from '@bevel-software/platform-shared';
+
+/**
+ * Shape of the diff service. Backups live in a sibling root that mirrors the
+ * workspaces layout: each user/repo has `<backupsRoot>/<userId>/<repoName>/...`
+ * holding the "last user-confirmed state" of every diffable file. Drift between
+ * disk and backup is the pending-change set.
+ *
+ * Triggers that update the backup:
+ *   - First-time mount (lazy via `currentSession`) seeds from disk.
+ *   - User write/delete/rename through WorkspaceService → `syncFromDisk` /
+ *     `markUserDeleted`.
+ *   - User accept/reject of pending changes.
+ *
+ * Under the per-branch workspace model each branch has its own clone +
+ * its own backup folder, both seeded at bootstrap, so the legacy
+ * "branch switch wipes + reseeds the backup" trigger is gone. `resetBackup`
+ * + `resetBackupUnlocked` are still on the interface as primitives but
+ * have **no production callers** today — kept for potential future
+ * mutex-holding use cases.
+ *
+ * Agent edits, agent shell commits, and `git pull/merge/fetch/commit/push`
+ * leave the backup alone — the resulting drift is what the user reviews.
+ */
+export interface IDiffService {
+  /** Wipe the backup folder and reseed from the current working tree. */
+  resetBackup(workspaceId: string): Promise<void>;
+
+  /**
+   * Same as `resetBackup` but assumes the caller is already holding the
+   * workspace mutex (via `WorkspaceMutex.run`). Originally the post-switch
+   * backup-reseed hook for `GitService.switchBranch`; that caller is gone
+   * with the per-branch workspace model (each branch has its own workspace
+   * + its own backup, seeded at bootstrap), so this currently has no
+   * production callers — kept in the interface as a primitive for future
+   * mutex-holding callers that need a backup reset.
+   */
+  resetBackupUnlocked(workspaceId: string): Promise<void>;
+
+  /** Pending changes for the current branch, or null when none. */
+  currentSession(workspaceId: string): Promise<ReviewSession | null>;
+
+  /** Diff payload (baseline + current) for one path. */
+  fileDiff(workspaceId: string, relativePath: string): Promise<FileDiffPayload>;
+
+  /** Promote disk → backup for `relativePath`. Handles file or directory. */
+  syncFromDisk(workspaceId: string, relativePath: string): Promise<void>;
+
+  /** Drop backup entry for `relativePath` (file or dir, recursive). */
+  markUserDeleted(workspaceId: string, relativePath: string): Promise<void>;
+
+  /** Accept one pending path: backup ← disk (or drop backup if disk-gone). */
+  acceptOne(workspaceId: string, relativePath: string): Promise<ReviewSession | null>;
+
+  /** Reject one pending path: disk ← backup (or rm disk if backup-gone). */
+  rejectOne(workspaceId: string, relativePath: string): Promise<ReviewSession | null>;
+
+  /**
+   * Compute the batch revert plan for `paths` WITHOUT mutating anything: each
+   * diffable path resolves to either a write of its pre-agent baseline bytes
+   * (backup exists) or a delete (agent-added file, no backup). Also returns
+   * the workspace dir so the caller can run the plan through a
+   * `LockingFilesystem.writeFiles` batch — one lock sweep, one commit + push.
+   * Non-diffable paths are skipped.
+   */
+  revertPlan(
+    workspaceId: string,
+    paths: string[],
+  ): Promise<{ workspaceDir: string; writes: { path: string; content: Buffer }[]; deletes: string[] }>;
+
+  /**
+   * Accept every pending path in ONE batch (single mutex hold, single
+   * pending-list walk). `paths` optionally restricts the batch to an
+   * allow-list — the accept route passes the caller's readable paths so
+   * restricted nodes stay pending.
+   */
+  acceptAll(workspaceId: string, paths?: string[]): Promise<void>;
+}