@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/src/modules/database/core-schema.ts

@@ -147,6 +147,16 @@ export const changeRequests = pgTable('change_requests', {
   authorName: text('author_name').notNull(),
   state: text('state').notNull().default('open'), // 'open' | 'merged' | 'closed'
   mergedSha: text('merged_sha'),
+  // The last apply attempt that did not land (null when none, or once a gate
+  // input it depended on changed). Persisted rather than only pushed to the
+  // clicker so every viewer of the still-open request — its author first —
+  // sees the refusal.
+  applyFailureReason: text('apply_failure_reason'),
+  applyFailureConflicts: boolean('apply_failure_conflicts'),
+  applyFailedAt: timestamp('apply_failed_at'),
+  applyFailedByName: text('apply_failed_by_name'),
+  /** What refused the last apply: 'gate' (approvals), 'conflicts' (git), 'error' (anything else). */
+  applyFailureKind: text('apply_failure_kind'),
   createdAt: timestamp('created_at').defaultNow().notNull(),
   updatedAt: timestamp('updated_at'),
   closedAt: timestamp('closed_at'),
@@ -183,9 +193,24 @@ export const externalApiKeys = pgTable('api_tokens', {
   userId: uuid('user_id').notNull().references(() => users.id),
   tokenHash: text('token_hash').notNull().unique(),
   label: text('label').notNull(),
+  /**
+   * What the key was minted as: `key` by hand, or a flow's own kind (a
+   * Claude link). The one fact that tells such keys apart — the label is
+   * free text the person may edit or imitate.
+   */
+  kind: text('kind').default('key').notNull(),
   createdAt: timestamp('created_at').defaultNow().notNull(),
   lastUsedAt: timestamp('last_used_at'),
   revokedAt: timestamp('revoked_at'),
+  /**
+   * Who ended the key — `owner` (the person disconnected it themselves) or
+   * `admin` (an admin revoked it from the deployment overview). Null while
+   * the key is live, and on rows revoked before this column existed, which
+   * the UI reads as the owner's own doing. The owner's page uses it to say
+   * "revoked by an admin" rather than "disconnected", so nobody tries to
+   * reconnect a key that was taken from them.
+   */
+  revokedBy: text('revoked_by'),
 }, (t) => ({
   byUser: index('api_tokens_by_user').on(t.userId),
 }));
@@ -490,3 +515,155 @@ export const deploymentSettings = pgTable('deployment_settings', {
   updatedBy: uuid('updated_by').references(() => users.id, { onDelete: 'set null' }),
   updatedAt: timestamp('updated_at').defaultNow().notNull(),
 });
+
+/**
+ * What this deployment presents to claude.ai as a "GitHub Enterprise Server"
+ * so that Cowork and claude.ai can add the per-user marketplace: the app id,
+ * client id and secrets an Owner pastes into Claude's admin settings. ONE row,
+ * generated on first use, replaced whole on rotate. Secrets are sealed with
+ * the secrets key, as stored settings are — see
+ * `marketplace/github-facade/github-facade-credentials.service.ts`.
+ */
+export const githubFacadeIdentity = pgTable('github_facade_identity', {
+  id: text('id').primaryKey(),
+  appId: text('app_id').notNull(),
+  clientId: text('client_id').notNull(),
+  /** Sealed. */
+  clientSecret: text('client_secret').notNull(),
+  /** Sealed. */
+  webhookSecret: text('webhook_secret').notNull(),
+  /** Sealed — PKCS#1 PEM. */
+  privateKeyPem: text('private_key_pem').notNull(),
+  publicKeyPem: text('public_key_pem').notNull(),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  rotatedAt: timestamp('rotated_at'),
+  /**
+   * When an admin said the deployment is registered with their Claude
+   * organization; null while it is not. Nothing on the Claude side reports
+   * this back, so an admin states it. Not sealed: it is the one fact about
+   * this row every signed-in person may read.
+   */
+  registeredAt: timestamp('registered_at'),
+});
+
+/**
+ * One-time codes the Claude connect flow issues on the consent page and
+ * Anthropic's backend exchanges seconds later — in the database so the
+ * replica that issued a code and the replica asked to exchange it agree.
+ *
+ * Keyed by the PERSON: "one live code per person" is the table's own rule,
+ * not a cleanup's. Issuing upserts their row — the newest code overwrites
+ * the last in one statement — so the table holds at most one row per user,
+ * for as long as the user exists (the row goes with them), and nothing ever
+ * has to sweep it. The client id is data the exchange checks, not part of
+ * the key: the bridge has one client, and a rotated client id must not leave
+ * a dead row behind under the old one. The code's hash is the unique lookup
+ * an exchange uses, spent by a conditional update. See
+ * `marketplace/github-facade/github-facade-codes.store.ts`.
+ */
+export const githubFacadeCodes = pgTable('github_facade_codes', {
+  userId: uuid('user_id').primaryKey().references(() => users.id, { onDelete: 'cascade' }),
+  clientId: text('client_id').notNull(),
+  codeHash: text('code_hash').notNull().unique(),
+  redirectUri: text('redirect_uri').notNull(),
+  expiresAt: timestamp('expires_at').notNull(),
+  consumedAt: timestamp('consumed_at'),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+});
+
+/**
+ * Join requests as the platform RECORDS them, distinct from the change
+ * request that eventually carries one.
+ *
+ * A join request used to be nothing but a change request: the endpoint did
+ * the branch, the clone, the grant commit, the push and the change request
+ * before it answered, so the row and the answer were the same event. The
+ * first request from a person is a full clone, which is many seconds on a
+ * real repository, and the click looked like a freeze. The record is what
+ * lets the click be answered first: the route writes a row and returns, and
+ * the git work runs after, against the row.
+ *
+ * Which makes the row the durable statement "this person asked", and the
+ * only one — the change request is a CONSEQUENCE of it, recorded back here
+ * as `change_request_number` once it exists. That is the whole reason this
+ * is a table and not a queue in memory: a process that dies between the
+ * answer and the push must leave the ask behind, and the boot sweep re-runs
+ * every row still `pending`.
+ *
+ *   pending   asked, and the git work has not finished (or has not started)
+ *   opened    the change request exists; its number is here
+ *   failed    the git work refused, and `failure_reason` says what it said
+ *
+ * `(requester_email, plugin_key)` is UNIQUE, which is what makes two tabs and
+ * two clicks one request: the second ask upserts the same row. A `failed` row
+ * is revived to `pending` by the next ask rather than replaced, so a retry
+ * continues the recorded request instead of opening a second one.
+ *
+ * `plugin_key` is the plugin's primary FOLDER below the plugins root — the
+ * same key the join BRANCH is cut from, so a record and its branch cannot
+ * drift, and renaming the plugin's identity (which moves no folder) orphans
+ * no record.
+ */
+export const pluginJoinRequests = pgTable('plugin_join_requests', {
+  id: uuid('id').defaultRandom().primaryKey(),
+  requesterEmail: text('requester_email').notNull(), // lowercased at insert
+  /** Denormalised for the commit/change-request authorship, like `file_locks.holder_name`. */
+  requesterName: text('requester_name').notNull(),
+  pluginKey: text('plugin_key').notNull(),
+  status: text('status').notNull().default('pending'),
+  /** What the git work said when it refused — shown to the requester verbatim. */
+  failureReason: text('failure_reason'),
+  changeRequestNumber: integer('change_request_number'),
+  /**
+   * When a process took this row's git work, and the whole of the mutual
+   * exclusion over it.
+   *
+   * A redeploy runs two processes for as long as the changeover takes, and
+   * both sweep. Their single-flight maps are per-process, so without this
+   * they would clone, commit and push the same branch against the same shared
+   * workspace at the same time. Claiming is one conditional UPDATE — the row
+   * is taken only if nobody holds it — so the loser simply does not run.
+   *
+   * A CLAIM EXPIRES, because a process can die holding one and the request
+   * would otherwise be owed forever. The window has to exceed the longest
+   * honest attempt, which is a first-ever request's full clone; past it, the
+   * next sweep or click takes the row over. A row that was never claimed at
+   * all — recorded a moment before the process died — is claimable at once,
+   * which is the common restart case.
+   */
+  claimedAt: timestamp('claimed_at'),
+  /**
+   * WHICH claim `claimed_at` is the liveness of — a fencing token, fresh on
+   * every claim.
+   *
+   * A timestamp alone says a row is held; it cannot say by whom. So a worker
+   * that misses the stale window — a long GC pause, a host that froze, a
+   * network partition that outlived three beats — carries on believing it
+   * holds the row that somebody else has since taken, and its `markOpened`
+   * or `markFailed`, addressed by id alone, lands on the NEW attempt: the
+   * second worker's run is settled by the first worker's outcome, or a row
+   * mid-flight is stamped `failed` under it. Two change requests for one
+   * request is the same race a step earlier.
+   *
+   * Every write that decides or holds the row therefore names the token it
+   * believes it holds, and matches nothing if the token has moved on. A
+   * superseded worker's writes become no-ops rather than corruption, and it
+   * learns it was superseded from its next beat returning false — which is
+   * also how it learns the row was DELETED out from under it, the shape
+   * account erasure takes.
+   */
+  claimToken: uuid('claim_token'),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  updatedAt: timestamp('updated_at').defaultNow().notNull(),
+}, (t) => ({
+  // One request per person per plugin — the DB's rule, not a caller's. Also
+  // the index the plugin listing's by-requester read is served from.
+  requesterPluginUnq: uniqueIndex('plugin_join_requests_requester_plugin_unq')
+    .on(t.requesterEmail, t.pluginKey),
+  // The boot sweep: every row still `pending`, without a full scan.
+  byStatus: index('plugin_join_requests_by_status').on(t.status),
+  statusCheck: check(
+    'plugin_join_requests_status',
+    sql`${t.status} IN ('pending', 'opened', 'failed')`,
+  ),
+}));

package/src/modules/database/migrate.ts

@@ -1,5 +1,9 @@
 import { migrate } from 'drizzle-orm/node-postgres/migrator';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('database');
 import type { Database } from './connection.js';
+import { AdvisoryLock, withAdvisoryLock } from './advisory-lock.js';
 
 /*
  * ── Per-tier migration folders ──────────────────────────────────────────────
@@ -22,13 +26,25 @@ import type { Database } from './connection.js';
  * Note: drizzle-orm's node-postgres `migrate()` accepts `migrationsTable` (and
  * `migrationsSchema`) in the installed version (0.45.x) — see
  * `drizzle-orm/migrator.d.ts` (`MigrationConfig`).
+ *
+ * BOTH RUNNERS TAKE AN ADVISORY LOCK. Drizzle's migrator takes none of its own:
+ * it reads the newest applied migration, then opens a transaction and applies
+ * everything newer — so two processes booting at once read the same watermark
+ * and both apply. The idempotence described above covers a RE-run, which is a
+ * different thing from a CONCURRENT one, and it only covers the init migration
+ * anyway; 0002 onward are plain DDL, where the second process fails on an
+ * already-applied `ALTER TABLE` and crash-loops. Two processes booting at once
+ * is not hypothetical here — it is every redeploy, for as long as the outgoing
+ * container takes to exit. See `advisory-lock.ts` for the mechanism.
  */
 
 /** Apply the CORE migration history from `folder`, tracked in `__drizzle_migrations_core`. */
 export async function runCoreMigrations(db: Database, folder: string): Promise<void> {
-  console.log('Running core database migrations...');
-  await migrate(db, { migrationsFolder: folder, migrationsTable: '__drizzle_migrations_core' });
-  console.log('Core migrations complete.');
+  await withAdvisoryLock(db, AdvisoryLock.Migrations, async () => {
+    log.info('Running core database migrations...');
+    await migrate(db, { migrationsFolder: folder, migrationsTable: '__drizzle_migrations_core' });
+    log.info('Core migrations complete.');
+  });
 }
 
 /**
@@ -37,7 +53,12 @@ export async function runCoreMigrations(db: Database, folder: string): Promise<v
  * enterprise tables FK into core tables.
  */
 export async function runEnterpriseMigrations(db: Database, folder: string): Promise<void> {
-  console.log('Running enterprise database migrations...');
-  await migrate(db, { migrationsFolder: folder, migrationsTable: '__drizzle_migrations_enterprise' });
-  console.log('Enterprise migrations complete.');
+  await withAdvisoryLock(db, AdvisoryLock.Migrations, async () => {
+    log.info('Running enterprise database migrations...');
+    await migrate(db, {
+      migrationsFolder: folder,
+      migrationsTable: '__drizzle_migrations_enterprise',
+    });
+    log.info('Enterprise migrations complete.');
+  });
 }

package/src/modules/declared-variables/declared-variables.routes.ts

@@ -1,4 +1,7 @@
 import express, { type Request, type RequestHandler } from 'express';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('declared-variables');
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
 import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.js';
 import type { ISecretsVaultService } from '../secrets-vault/secrets-vault.contract.js';
@@ -136,13 +139,13 @@ export function createDeclaredVariableRoutes(
         key: utcpNamespacedKey(manual.name, v.name),
       }));
       const { values, missing } = await resolveAll(who.userId, entries);
-      console.info(
-        `[declared-variables] local tool "${manual.path}" resolved for user=${who.userId}: ` +
+      log.info(
+        `local tool "${manual.path}" resolved for user=${who.userId}: ` +
           `provided=[${Object.keys(values).join(',')}] missing=[${missing.join(',')}]`,
       );
       res.set('Cache-Control', 'no-store').json({ name: manual.name, variables: values, missing });
     } catch (err) {
-      console.error('[declared-variables] local tool resolve failed:', err instanceof Error ? err.message : err);
+      log.error('local tool resolve failed:', { err });
       res.status(500).json({ error: 'Failed to resolve variables' });
     }
   });

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

@@ -1,4 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { NodeFs } from '../../kb-fs/node-fs.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
@@ -55,6 +56,7 @@ async function setup(): Promise<Fixture> {
     workspacesRoot,
     'https://github.com/Bevel-Software/knowledge-base.git',
     'knowledge-base',
+    new NodeFs(),
   );
   const mutex = new WorkspaceMutex();
   const diffService = new DiffService(
@@ -63,6 +65,7 @@ async function setup(): Promise<Fixture> {
     workspacesRoot,
     backupsRoot,
     'knowledge-base',
+    new NodeFs(),
   );
   workspaceService.setDiffService(diffService);
   return { workspacesRoot, backupsRoot, workspaceDir, repoDir, workspaceId, workspaceService, diffService };

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

@@ -1,4 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { NodeFs } from '../../kb-fs/node-fs.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
@@ -41,6 +42,7 @@ async function setup(): Promise<Fixture> {
     workspacesRoot,
     'https://github.com/Bevel-Software/knowledge-base.git',
     'knowledge-base',
+    new NodeFs(),
   );
   const mutex = new WorkspaceMutex();
   const diffService = new DiffService(
@@ -49,6 +51,7 @@ async function setup(): Promise<Fixture> {
     workspacesRoot,
     backupsRoot,
     'knowledge-base',
+    new NodeFs(),
   );
   workspaceService.setDiffService(diffService);
   return { workspacesRoot, backupsRoot, workspaceDir, repoDir, workspaceId, workspaceService, diffService };

package/src/modules/diff/diff.routes.ts

@@ -5,6 +5,7 @@ import type { AuthService } from '../auth/auth.service.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { canReadWorkspacePath, toKbRelative, resolveReadableMap } from '../access-model/kb-read-filter.js';
 import { WorkflowDomainError, WorkflowValidationError } from '../../shared/domain-errors.js';
+import { domainErrorBody } from '../../shared/http-errors.js';
 import { LockingFilesystem } from '../kb-fs/locking-filesystem.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
 import '../auth/auth.middleware.js';
@@ -13,10 +14,7 @@ function toHttpError(
   err: unknown,
 ): { status: number; body: Record<string, unknown> } {
   if (err instanceof WorkflowDomainError) {
-    return {
-      status: err.status,
-      body: { error: err.message, ...(err.payload ?? {}) },
-    };
+    return { status: err.status, body: domainErrorBody(err) };
   }
   const message = err instanceof Error ? err.message : 'Unknown error';
   return { status: 500, body: { error: message } };

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

@@ -4,9 +4,10 @@ import type { FileDiffPayload, PendingChange, ReviewSession, ChangeKind } from '
 import type { IDiffService } from './diff.interface.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type { WorkspaceMutex } from '../kb-fs/mutex.js';
-import { BevelIgnoreStack } from '../workspace/bevel-ignore.js';
+import { isAbsence, type ITreeWalker, type TreeWalkOptions } from '../../shared/fs.contract.js';
 import { isDiffable } from './diff.config.js';
-import { assertWithinDirectory } from './diff-paths.js';
+import { assertWithinDirectory } from '../../shared/path-containment.js';
+import { assertNotGitInternals, hasGitInternalsSegment } from '../../shared/git-internals.js';
 import { countLineChanges } from './line-diff.js';
 
 /**
@@ -21,6 +22,7 @@ export class DiffService implements IDiffService {
     private readonly workspacesRoot: string,
     private readonly backupsRoot: string,
     private readonly kbDirName: string,
+    private readonly disk: ITreeWalker,
   ) {}
 
   // ── public API ──────────────────────────────────────────────────────────
@@ -39,11 +41,15 @@ export class DiffService implements IDiffService {
 
   async fileDiff(workspaceId: string, relativePath: string): Promise<FileDiffPayload> {
     return this.mutex.run(workspaceId, async () => {
+      // Resolved — and so judged, git folder and containment, links followed
+      // — BEFORE the ledger is seeded: the seed copies the whole tree, which
+      // a refused request must not set in motion, and a seed that failed
+      // would otherwise mask the refusal. The pair needs no ledger to resolve.
+      const { fileAbs, backupAbs } = await this.resolvePair(workspaceId, relativePath);
       // Seed the backup ledger if this is the first call on a fresh workspace
       // — otherwise every untouched file would surface as `kind: 'added'`
       // because the backup side is empty.
       await this.ensureSeededUnlocked(workspaceId);
-      const { fileAbs, backupAbs } = await this.resolvePair(workspaceId, relativePath);
       const [diskBuf, backupBuf] = await Promise.all([
         fs.readFile(fileAbs).catch(() => null),
         fs.readFile(backupAbs).catch(() => null),
@@ -149,8 +155,10 @@ export class DiffService implements IDiffService {
       const writes: { path: string; content: Buffer }[] = [];
       const deletes: string[] = [];
       for (const rel of paths) {
-        if (!isDiffable(rel)) continue;
+        // Resolved BEFORE the diffable test, like accept and reject: the git
+        // folder is refused for every path the caller names.
         const { backupAbs } = await this.resolvePair(workspaceId, rel);
+        if (!isDiffable(rel)) continue;
         try {
           // Backup exists → the revert is a write of the pre-agent baseline
           // bytes (Buffer: pending changes can be binary).
@@ -160,8 +168,7 @@ export class DiffService implements IDiffService {
           // discards it". Any other read failure (EACCES, EMFILE, …) must
           // abort the plan — misclassifying it as no-backup would DELETE a
           // file whose baseline we merely failed to read.
-          const code = (err as NodeJS.ErrnoException | null)?.code;
-          if (code !== 'ENOENT') throw err;
+          if (!isAbsence(err)) throw err;
           deletes.push(rel);
         }
       }
@@ -188,8 +195,8 @@ export class DiffService implements IDiffService {
     const workspaceDir = await this.workspaceService.getWorkspacePath(workspaceId);
     const backupDir = await this.getBackupDir(workspaceId);
     const candidates = new Set<string>();
-    await walkDiffable(workspaceDir, workspaceDir, candidates);
-    await walkAll(backupDir, backupDir, candidates);
+    await walkDiffable(this.disk, workspaceDir, candidates);
+    await walkAll(this.disk, backupDir, candidates);
     const pending: PendingChange[] = [];
     for (const rel of candidates) {
       const change = await computePending(workspaceDir, backupDir, rel);
@@ -263,8 +270,7 @@ export class DiffService implements IDiffService {
       try {
         await fs.rename(backupDir, oldBackupTrash);
       } catch (err) {
-        const code = (err as NodeJS.ErrnoException | null)?.code;
-        if (code !== 'ENOENT') throw err; // no existing backup is fine
+        if (!isAbsence(err)) throw err; // no existing backup is fine
       }
       await fs.rename(stagingDir, backupDir);
       await fs.rm(oldBackupTrash, { recursive: true, force: true }).catch(() => undefined);
@@ -283,8 +289,10 @@ export class DiffService implements IDiffService {
   }
 
   private async acceptOneUnlocked(workspaceId: string, relativePath: string): Promise<void> {
-    if (!isDiffable(relativePath)) return;
+    // Resolved BEFORE the diffable test, so the git folder is refused for
+    // every path rather than left to the fact that nothing in it is markdown.
     const { fileAbs, backupAbs } = await this.resolvePair(workspaceId, relativePath);
+    if (!isDiffable(relativePath)) return;
     let diskExists = true;
     try {
       await fs.access(fileAbs);
@@ -301,8 +309,9 @@ export class DiffService implements IDiffService {
   }
 
   private async rejectOneUnlocked(workspaceId: string, relativePath: string): Promise<void> {
-    if (!isDiffable(relativePath)) return;
+    // Resolved first, like `acceptOneUnlocked` — same reason.
     const { fileAbs, backupAbs } = await this.resolvePair(workspaceId, relativePath);
+    if (!isDiffable(relativePath)) return;
     let backupExists = true;
     try {
       await fs.access(backupAbs);
@@ -337,37 +346,29 @@ export class DiffService implements IDiffService {
     const backupDir = await this.getBackupDir(workspaceId);
     const fileAbs = path.resolve(workspaceDir, relativePath);
     const backupAbs = path.resolve(backupDir, relativePath);
+    // Every review operation resolves its pair here — the file diff, accept,
+    // reject, the ledger sync — so the git folder is refused for all of them
+    // in one place, links into it included. FIRST, so a path into the folder
+    // gets the one sanitized refusal rather than a containment error.
+    await assertNotGitInternals(workspaceDir, relativePath, fileAbs);
     assertWithinDirectory(fileAbs, workspaceDir);
     assertWithinDirectory(backupAbs, backupDir);
     return { workspaceDir, backupDir, fileAbs, backupAbs };
   }
 
-  private async copyDiffableTree(
-    workspaceDir: string,
-    backupDir: string,
-    currentDir: string,
-    parentIgnore: BevelIgnoreStack = BevelIgnoreStack.empty(),
-  ): Promise<void> {
-    let entries;
-    try {
-      entries = await fs.readdir(currentDir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    const ignoreStack = await parentIgnore.extendedWith(currentDir);
-    for (const entry of entries) {
-      if (entry.name === '.git' || entry.name === '.workspace.json') continue;
-      const srcPath = path.join(currentDir, entry.name);
-      if (ignoreStack.isIgnored(srcPath, entry.isDirectory())) continue;
-      const rel = path.relative(workspaceDir, srcPath);
-      const dstPath = path.join(backupDir, rel);
-      if (entry.isDirectory()) {
-        await this.copyDiffableTree(workspaceDir, backupDir, srcPath, ignoreStack);
-      } else if (entry.isFile() && isDiffable(entry.name)) {
-        await fs.mkdir(path.dirname(dstPath), { recursive: true });
-        await fs.copyFile(srcPath, dstPath);
-      }
-    }
+  /** Mirror every diffable file under `currentDir` into `backupDir`, at the same path relative to `workspaceDir`. */
+  private async copyDiffableTree(workspaceDir: string, backupDir: string, currentDir: string): Promise<void> {
+    await this.disk.walk(currentDir, diffableWalk(), [
+      {
+        async onFile(dir, name) {
+          if (!isDiffable(name)) return;
+          const srcPath = path.join(currentDir, dir, name);
+          const dstPath = path.join(backupDir, path.relative(workspaceDir, srcPath));
+          await fs.mkdir(path.dirname(dstPath), { recursive: true });
+          await fs.copyFile(srcPath, dstPath);
+        },
+      },
+    ]);
   }
 
   /**
@@ -409,49 +410,44 @@ function looksBinary(buf: Buffer): boolean {
   return sample.indexOf(0) !== -1;
 }
 
-async function walkDiffable(
-  root: string,
-  dir: string,
-  out: Set<string>,
-  parentIgnore: BevelIgnoreStack = BevelIgnoreStack.empty(),
-): Promise<void> {
-  let entries;
-  try {
-    entries = await fs.readdir(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  const ignoreStack = await parentIgnore.extendedWith(dir);
-  for (const entry of entries) {
-    if (entry.name === '.git' || entry.name === '.workspace.json') continue;
-    const abs = path.join(dir, entry.name);
-    if (ignoreStack.isIgnored(abs, entry.isDirectory())) continue;
-    if (entry.isDirectory()) {
-      await walkDiffable(root, abs, out, ignoreStack);
-    } else if (entry.isFile() && isDiffable(entry.name)) {
-      out.add(path.relative(root, abs).replace(/\\/g, '/'));
-    }
-  }
+/**
+ * The walk of a workspace the diff ledger mirrors: no git internals, no
+ * workspace marker, `.bevelignore` honoured on the way down, and a folder
+ * that cannot be listed is left out — the ledger shows what it can.
+ */
+function diffableWalk(): TreeWalkOptions {
+  return { skip: (e) => hasGitInternalsSegment(e.name) || e.name === '.workspace.json', ignore: true };
 }
 
-async function walkAll(root: string, dir: string, out: Set<string>): Promise<void> {
-  let entries;
-  try {
-    entries = await fs.readdir(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    const abs = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      await walkAll(root, abs, out);
-    } else if (entry.isFile()) {
-      // Strip the .tmp suffix from in-flight atomic writes so a crashed write
-      // doesn't surface as a phantom "modified" entry on the next list call.
-      if (entry.name.endsWith('.tmp')) continue;
-      out.add(path.relative(root, abs).replace(/\\/g, '/'));
-    }
-  }
+/** Every diffable file under `root`, as `/`-separated paths relative to it. */
+async function walkDiffable(disk: ITreeWalker, root: string, out: Set<string>): Promise<void> {
+  await disk.walk(root, diffableWalk(), [
+    {
+      onFile(dir, name) {
+        if (isDiffable(name)) out.add(dir ? `${dir}/${name}` : name);
+      },
+    },
+  ]);
+}
+
+/**
+ * Every file under the backup `root`, as `/`-separated paths relative to it.
+ * The git folder is skipped here as well as on the workspace side: a ledger
+ * seeded before this rule existed can still hold `.git`/`.GIT` entries, and
+ * listing one would pair it with the workspace path and read the folder back
+ * out through the review session.
+ */
+async function walkAll(disk: ITreeWalker, root: string, out: Set<string>): Promise<void> {
+  await disk.walk(root, { skip: (e) => hasGitInternalsSegment(e.name) }, [
+    {
+      onFile(dir, name) {
+        // Strip the .tmp suffix from in-flight atomic writes so a crashed write
+        // doesn't surface as a phantom "modified" entry on the next list call.
+        if (name.endsWith('.tmp')) return;
+        out.add(dir ? `${dir}/${name}` : name);
+      },
+    },
+  ]);
 }
 
 async function computePending(