@bevel-software/platform-core-backend 0.22.0 → 0.23.0

package/src/modules/workflow/file-lock.service.ts

@@ -305,6 +305,37 @@ export class FileLockService {
     return rowToFileLock(row);
   }
 
+  /**
+   * Drop every lock held on `branch`, whoever holds it and whichever
+   * workspace it sits in, and answer how many rows went.
+   *
+   * The one caller is a change request being closed because the
+   * knowledge-base repository was REPLACED: the branch the lock names belongs
+   * to a repository this deployment no longer has, so the holder can neither
+   * publish their bytes nor release the lock themselves — and the row would
+   * otherwise sit there refusing the path to everyone until its TTL ran out
+   * on every heartbeat a still-connected client keeps sending.
+   *
+   * Expired rows go too: they are already nobody's lock, and leaving them for
+   * the lazy sweep would only make this answer harder to read.
+   *
+   * Deliberately NOT a release in the ordinary sense — nothing is committed
+   * and nothing is enqueued. The bytes belonged to a repository that is gone.
+   *
+   * What an ORDINARY release already enqueued is a different matter, and not
+   * this method's to fix: a release queues the bytes and only then drops its
+   * lock, so rows can be waiting for a branch whose locks this deletes. The
+   * caller takes those out of the worker's reach in the same breath — see
+   * `PendingCommitsService.markNeedsAttentionOnBranch`.
+   */
+  async releaseAllOnBranch(branch: string): Promise<number> {
+    const gone = await this.db
+      .delete(fileLocks)
+      .where(eq(fileLocks.branch, branch))
+      .returning({ path: fileLocks.path });
+    return gone.length;
+  }
+
   /**
    * Is ANY unexpired lock held anywhere in this workspace? Feeds the git
    * status sanity check: a held lock means a mutation is mid-flight — the

package/src/modules/workflow/git/__tests__/git.service.fileBytesAtCommit.test.ts

@@ -0,0 +1,260 @@
+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 { testKbContext } from '../../../../__tests__/kb-context.js';
+import { GitService } from '../git.service.js';
+import {
+  VersionNotOnBranchError,
+  VERSION_NOT_ON_BRANCH_MESSAGE,
+  WorkflowValidationError,
+} from '../../../../shared/domain-errors.js';
+import { GitRunError, assertOneSpecPerLine } from '../../../../shared/git.contract.js';
+import { runGit, gitOut, stubWorkflowHooks, stubWorkspaceService } from './git-test-helpers.js';
+
+/**
+ * A past version has to come back BYTE FOR BYTE, and only for saves on the
+ * branch being viewed.
+ *
+ * `readFileAtRef` decodes git's stdout as UTF-8, which is why a binary could
+ * not be served through it at all: every byte sequence that is not valid UTF-8
+ * comes back as U+FFFD, so a PNG downloaded from history would not open. The
+ * suite pins the round trip on bytes that would not survive that (everything
+ * from 0x00 to 0xff, NUL included), the two sides of a save, and the branch
+ * rule that decides who may ask at all.
+ */
+
+/** Every byte value, so any decode-and-re-encode step is visible as a failure. */
+const ALL_BYTES = Buffer.from(Array.from({ length: 256 }, (_, i) => i));
+const PNG_HEADER = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const V1 = Buffer.concat([PNG_HEADER, ALL_BYTES, Buffer.from('v1')]);
+const V2 = Buffer.concat([PNG_HEADER, ALL_BYTES.subarray(0, 128), Buffer.from('v2\0tail')]);
+
+describe('GitService.fileBytesAtCommit', () => {
+  let root: string;
+  let repo: string;
+  let svc: GitService;
+  const workspaceId = 'target-company-state';
+  /** The save that ADDED logo.png (V1), the save that REPLACED it (V2). */
+  let addSha: string;
+  let replaceSha: string;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-bytes-at-ref-'));
+    const workspaceDir = path.join(root, workspaceId);
+    repo = path.join(workspaceDir, 'knowledge-base');
+    await fs.mkdir(repo, { recursive: true });
+    await runGit(root, ['init', '-b', 'target-company-state', repo]);
+    await runGit(repo, ['config', 'user.email', 'workspace@bevel.test']);
+    await runGit(repo, ['config', 'user.name', 'bevel Workspace']);
+
+    await fs.writeFile(path.join(repo, 'logo.png'), V1);
+    await fs.mkdir(path.join(repo, 'docs'));
+    await fs.writeFile(path.join(repo, 'docs', 'child.md'), 'child\n');
+    await runGit(repo, ['add', '.']);
+    await runGit(repo, ['commit', '-m', 'add logo']);
+    addSha = await gitOut(repo, ['rev-parse', 'HEAD']);
+
+    await fs.writeFile(path.join(repo, 'logo.png'), V2);
+    await runGit(repo, ['add', '.']);
+    await runGit(repo, ['commit', '-m', 'replace logo']);
+    replaceSha = await gitOut(repo, ['rev-parse', 'HEAD']);
+
+    svc = new GitService(
+      stubWorkspaceService({ [workspaceId]: workspaceDir }),
+      stubWorkflowHooks(),
+      testKbContext(),
+    );
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+  });
+
+  it('returns the exact bytes of each save, on both sides of it', async () => {
+    const atAdd = await svc.fileBytesAtCommit(workspaceId, 'knowledge-base/logo.png', addSha, 'after');
+    expect(atAdd).not.toBeNull();
+    expect(atAdd!.bytes.equals(V1)).toBe(true);
+    expect(atAdd!.blobId).toMatch(/^[0-9a-f]{40}$/);
+
+    const atReplace = await svc.fileBytesAtCommit(
+      workspaceId,
+      'knowledge-base/logo.png',
+      replaceSha,
+      'after',
+    );
+    expect(atReplace!.bytes.equals(V2)).toBe(true);
+
+    // The `before` side of the replacing save IS the original upload — which
+    // is what makes "download the version this save replaced" possible.
+    const before = await svc.fileBytesAtCommit(
+      workspaceId,
+      'knowledge-base/logo.png',
+      replaceSha,
+      'before',
+    );
+    expect(before!.bytes.equals(V1)).toBe(true);
+    // Different content, therefore a different ETag: the blob id IS the hash.
+    expect(atReplace!.blobId).not.toBe(before!.blobId);
+  });
+
+  it('accepts the repo-relative spelling of the path too', async () => {
+    const at = await svc.fileBytesAtCommit(workspaceId, 'logo.png', addSha, 'after');
+    expect(at!.bytes.equals(V1)).toBe(true);
+  });
+
+  it('serves the version just before the save that DELETED the file', async () => {
+    await fs.rm(path.join(repo, 'logo.png'));
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'remove logo']);
+    const delSha = await gitOut(repo, ['rev-parse', 'HEAD']);
+
+    // Nothing at the path after the save…
+    expect(
+      await svc.fileBytesAtCommit(workspaceId, 'knowledge-base/logo.png', delSha, 'after'),
+    ).toBeNull();
+    // …and the bytes as they were just before it.
+    const before = await svc.fileBytesAtCommit(
+      workspaceId,
+      'knowledge-base/logo.png',
+      delSha,
+      'before',
+    );
+    expect(before!.bytes.equals(V2)).toBe(true);
+  });
+
+  it('returns null for a path the save did not have', async () => {
+    expect(
+      await svc.fileBytesAtCommit(workspaceId, 'knowledge-base/never.png', addSha, 'after'),
+    ).toBeNull();
+    // The root commit has no parent, so it has no `before` side either.
+    expect(
+      await svc.fileBytesAtCommit(workspaceId, 'knowledge-base/logo.png', addSha, 'before'),
+    ).toBeNull();
+  });
+
+  it('refuses a directory at the ref — history is served per file', async () => {
+    await expect(
+      svc.fileBytesAtCommit(workspaceId, 'knowledge-base/docs', addSha, 'after'),
+    ).rejects.toThrow(/history is served per file/);
+  });
+
+  it('refuses a path carrying a LINE BREAK, which git would read as two object names', async () => {
+    // `cat-file --batch` takes one `<ref>:<path>` spec per LINE. Before the
+    // path validator refused control characters, `docs/child.md\nzzz` reached
+    // it as two specs: git answered about `docs/child.md` and those bytes came
+    // back as this path's — under the access gates of a name that exists
+    // nowhere, so the file's own rules were never the ones consulted. Verified
+    // against real git here, not a stub: the call must fail, and nothing of
+    // `child.md` may come back under the longer name.
+    for (const injected of [
+      'knowledge-base/docs/child.md\nzzz',
+      'knowledge-base/docs/child.md\rzzz',
+      'knowledge-base/docs/child.md\nknowledge-base/logo.png',
+    ]) {
+      // Both the TYPE and the sentence. Two different validators are called
+      // `assertValidRelativePath` — the shared one in
+      // `packages/shared/src/workspace/filename.ts`, which throws a plain
+      // `Error('Invalid path: …')`, and the kb-fs one in
+      // `modules/kb-fs/branch-name.ts`, which throws `WorkflowValidationError`
+      // (status 400). `GitService` imports the kb-fs one, and the 400 is what
+      // makes the route answer 400 rather than 500, so the type is asserted
+      // here deliberately and the message pins which of the two ran.
+      await expect(
+        svc.fileBytesAtCommit(workspaceId, injected, addSha, 'after'),
+      ).rejects.toThrow(WorkflowValidationError);
+      await expect(
+        svc.fileBytesAtCommit(workspaceId, injected, addSha, 'after'),
+      ).rejects.toThrow(/control character/);
+      await expect(
+        svc.fileBytesAtCommit(workspaceId, injected, addSha, 'after'),
+      ).rejects.toMatchObject({ status: 400 });
+    }
+    // The refusal is the PATH's, decided before the sha is resolved or the
+    // workspace's git turn is taken — so a caller cannot reach git with one.
+    await expect(
+      svc.fileBytesAtCommit(workspaceId, 'knowledge-base/docs/child.md\nzzz', 'HEAD', 'after'),
+    ).rejects.toThrow(/control character/);
+  });
+
+  it('fences the batch protocol itself against a spec that is not one line', () => {
+    // The fence under `blobAtRef` and under the access resolver's batch read,
+    // for a spec assembled from somewhere the path validator does not cover.
+    expect(() => assertOneSpecPerLine([`${addSha}:logo.png`])).not.toThrow();
+    expect(() => assertOneSpecPerLine([`${addSha}:docs/child.md\nzzz`])).toThrow(/line break/);
+    expect(() => assertOneSpecPerLine(['a:b', 'c:d\re'])).toThrow(/line break/);
+  });
+
+  it('refuses a sha that is not a sha', async () => {
+    await expect(
+      svc.fileBytesAtCommit(workspaceId, 'knowledge-base/logo.png', 'HEAD', 'after'),
+    ).rejects.toThrow(WorkflowValidationError);
+  });
+
+  it('refuses a save that is not in this branch\'s history, and a made-up one, alike', async () => {
+    // A save that exists — on another branch this workspace is not viewing.
+    await runGit(repo, ['checkout', '-b', 'someone-else']);
+    await fs.writeFile(path.join(repo, 'logo.png'), Buffer.from('elsewhere'));
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'elsewhere']);
+    const otherSha = await gitOut(repo, ['rev-parse', 'HEAD']);
+    await runGit(repo, ['checkout', 'target-company-state']);
+
+    for (const sha of [otherSha, 'a'.repeat(40)]) {
+      const read = svc.fileBytesAtCommit(workspaceId, 'knowledge-base/logo.png', sha, 'after');
+      await expect(read).rejects.toThrow(VersionNotOnBranchError);
+      await expect(read).rejects.toThrow(VERSION_NOT_ON_BRANCH_MESSAGE);
+    }
+
+    // …and every save the panel LISTS is accepted, which is the other half of
+    // the rule: `logForFile` walks HEAD, so anything it returns is an ancestor.
+    // Asserted through the read itself rather than a boolean helper, so what is
+    // pinned is the thing the route calls.
+    for (const listed of await svc.logForFile(workspaceId, 'knowledge-base/logo.png')) {
+      await expect(
+        svc.fileBytesAtCommit(workspaceId, 'knowledge-base/logo.png', listed.sha, 'after'),
+      ).resolves.not.toBeNull();
+    }
+  });
+
+  it('propagates a repository failure rather than calling it a version off the branch', async () => {
+    // An UNBORN HEAD: the sha resolves perfectly well and git's complaint is
+    // about the other argument ('ambiguous argument HEAD'). Folded into
+    // `VersionNotOnBranchError` it would tell a reader the save they can see
+    // listed is not in their history — a broken workspace dressed up as an
+    // answer about access, and one 'Try again' can never get past.
+    await runGit(repo, ['checkout', '--orphan', 'nothing-committed-yet']);
+    const err: unknown = await svc
+      .fileBytesAtCommit(workspaceId, 'knowledge-base/logo.png', addSha, 'after')
+      .catch((e: unknown) => e);
+    // `GitRunError` specifically, not just `Error`: the route reads the error's
+    // TYPE to decide its status, so a future re-wrap into
+    // `WorkflowValidationError` would turn this into a 400 about the caller's
+    // request rather than the logged 500 a broken repository earns, and a bare
+    // `toBeInstanceOf(Error)` would not notice.
+    expect(err).toBeInstanceOf(GitRunError);
+    expect(err).not.toBeInstanceOf(VersionNotOnBranchError);
+  });
+
+  it('applies the same branch rule to the existing text-history reads', async () => {
+    await runGit(repo, ['checkout', '-b', 'someone-else']);
+    await fs.writeFile(path.join(repo, 'logo.png'), Buffer.from('elsewhere'));
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'elsewhere']);
+    const otherSha = await gitOut(repo, ['rev-parse', 'HEAD']);
+    await runGit(repo, ['checkout', 'target-company-state']);
+
+    // Otherwise the bytes route's rule could simply be read around: the patch
+    // and the full before/after text are past versions too.
+    await expect(
+      svc.diffFileAtCommit(workspaceId, 'knowledge-base/logo.png', otherSha),
+    ).rejects.toThrow(VERSION_NOT_ON_BRANCH_MESSAGE);
+    await expect(
+      svc.fileContentsAtCommit(workspaceId, 'knowledge-base/logo.png', otherSha),
+    ).rejects.toThrow(VERSION_NOT_ON_BRANCH_MESSAGE);
+    // The on-branch saves still work.
+    expect(await svc.diffFileAtCommit(workspaceId, 'knowledge-base/logo.png', replaceSha)).toContain(
+      'logo.png',
+    );
+  });
+});

package/src/modules/workflow/git/git.service.ts

@@ -35,10 +35,12 @@ import {
   ProtectedBranchError,
   PullRebaseConflictError,
   RemoteBranchGoneError,
+  VersionNotOnBranchError,
   isMissingRemoteBranchFailure,
 } from '../../../shared/domain-errors.js';
 import {
   GitRunError,
+  assertOneSpecPerLine,
   isGitTimeout,
   redactGitToken,
   type GitCredentials,
@@ -2331,6 +2333,10 @@ export class GitService implements IGitService {
     const repoRelativePath = this.stripRepoPrefix(relativePath);
     return this.mutex.run(workspaceId, async () => {
       const cwd = await this.repoDir(workspaceId);
+      // Branch-scoped, like the bytes route: a patch is a past version too,
+      // and leaving this route open would let a sha refused there be read
+      // here instead.
+      await this.assertOnBranchHistory(cwd, sha);
       // BOTH sides: at a commit that DELETES a directory the path is absent
       // at `sha` but a tree at `sha^` — and the diff of that deletion is
       // every child's content, exactly what the per-file gate never checked.
@@ -2382,6 +2388,10 @@ export class GitService implements IGitService {
     const repoRelativePath = this.stripRepoPrefix(relativePath);
     return this.mutex.run(workspaceId, async () => {
       const cwd = await this.repoDir(workspaceId);
+      // Same branch rule as the patch and the bytes: this route serves the
+      // FULL text of both sides, so it is the most generous of the three and
+      // the least safe one to leave ungated.
+      await this.assertOnBranchHistory(cwd, sha);
       await this.assertNotTreeAtRef(cwd, sha, repoRelativePath, relativePath);
       await this.assertNotTreeAtRef(cwd, `${sha}^`, repoRelativePath, relativePath);
       const current = await this.readFileAtRef(workspaceId, sha, repoRelativePath);
@@ -3269,6 +3279,143 @@ export class GitService implements IGitService {
     }
   }
 
+  /**
+   * A repo-relative file's BYTES at an arbitrary git ref — the binary sibling
+   * of {@link readFileAtRef}, with the blob's object id alongside them.
+   *
+   * `readFileAtRef` decodes stdout as UTF-8, which for a PNG or a PDF is not a
+   * lossless round trip: every byte sequence that is not valid UTF-8 comes
+   * back as U+FFFD and the file is ruined. A past version has to be delivered
+   * byte for byte, so this reads through `cat-file --batch`, whose framing is
+   * in BYTES (`<oid> <type> <size>\n<size bytes>\n`) rather than characters.
+   *
+   * One invocation, and absence is a PROTOCOL answer (`<spec> missing`) rather
+   * than a parsed error message — which also covers `<sha>^` of a root commit,
+   * where there is no "before" side at all. `null` therefore means exactly
+   * "nothing is at that path on that side".
+   *
+   * The `oid` is the content's own hash, so it is what the HTTP route uses as
+   * an ETag: cheaper than hashing the body again, and stable for a version
+   * that by definition can never change.
+   */
+  private async blobAtRef(
+    cwd: string,
+    ref: string,
+    repoRelativePath: string,
+  ): Promise<{ bytes: Buffer; blobId: string } | null> {
+    // The spec has to be ONE line: the path is refused a control character
+    // twice over before it gets here (at the route's normaliser and again at
+    // `assertValidRelativePath`), and this is the fence at the protocol —
+    // `--batch` would otherwise read `<sha>:Docs/x.md\nzzz` as two object
+    // names and answer about the first, under the gates of the second.
+    const spec = `${ref}:${repoRelativePath}`;
+    assertOneSpecPerLine([spec]);
+    const { stdout } = await this.gitBytes(cwd, ['cat-file', '--batch'], {
+      input: `${spec}\n`,
+    });
+    const nl = stdout.indexOf(0x0a);
+    if (nl < 0) throw new Error('unexpected end of git cat-file output');
+    // The spec may itself contain spaces (a KB file routinely does), hence the
+    // endsWith checks rather than a split — same protocol reading as the
+    // access resolver's `catFileBatch`.
+    const header = stdout.subarray(0, nl).toString('utf-8');
+    if (header.endsWith(' missing') || header.endsWith(' ambiguous')) return null;
+    const [blobId, type, rawSize] = header.split(' ');
+    // A tree here would be the per-file gate bypassed, and `assertNotTreeAtRef`
+    // is what refuses it before this runs; anything else non-blob (a tag, a
+    // commit) is not a file either. Nothing to serve in either case.
+    if (type !== 'blob' || blobId === undefined) return null;
+    const size = Number(rawSize);
+    if (!Number.isSafeInteger(size) || size < 0) {
+      throw new Error(`unexpected git cat-file header: ${header}`);
+    }
+    return { bytes: stdout.subarray(nl + 1, nl + 1 + size), blobId };
+  }
+
+  /**
+   * Refuse a sha that is not in the history of the branch this workspace has
+   * checked out.
+   *
+   * A file's past is served per BRANCH: the history panel lists what `git log`
+   * on this workspace's own branch touched, and every read of a past save has
+   * to stay inside that list. Without this, a sha lifted from another branch —
+   * or from a change request nobody approved — would be readable through the
+   * workspace of a branch whose history never contained it, which is the
+   * access rules of the viewed branch bypassed by a query parameter.
+   *
+   * `merge-base --is-ancestor` is the exact question, and a commit is its own
+   * ancestor, so the branch head passes. Exit 1 is git's answer for "resolved,
+   * and not an ancestor". An unresolvable object name — a made-up id — gets
+   * the SAME refusal on purpose (see {@link VersionNotOnBranchError}), but only
+   * when git's complaint NAMES that id; every other failure propagates, a
+   * broken repository included. A guard that fails open on its own errors is
+   * not a guard, and one that reports them as a refusal is worse than no
+   * message at all.
+   */
+  private async assertOnBranchHistory(cwd: string, sha: string): Promise<void> {
+    try {
+      await this.git(cwd, ['merge-base', '--is-ancestor', sha, 'HEAD']);
+    } catch (err) {
+      if (err instanceof GitRunError && !err.timedOut) {
+        if (err.exitCode === 1) throw new VersionNotOnBranchError();
+        const stderr = err.stderr ?? err.message;
+        if (
+          // The complaint has to be about THE SHA WE ASKED FOR. `HEAD` is the
+          // other argument, and git spells its own failures the same way: a
+          // repository with no commits answers "ambiguous argument 'HEAD'",
+          // which is a broken workspace, not a version off the branch.
+          // Refusing it as "not in this file's history" would hide an
+          // infrastructure failure behind a sentence about access.
+          stderr.toLowerCase().includes(sha.toLowerCase()) &&
+          // git's wording for "I cannot resolve that" varies by subcommand and
+          // by version — `merge-base` says "Not a valid commit name", others
+          // "not a valid object name" / "unknown revision" — so every spelling
+          // that means the same thing is listed rather than one guessed at.
+          /not a valid (object|commit) name|no such commit|bad object|unknown revision|malformed object name|ambiguous argument/i.test(
+            stderr,
+          )
+        ) {
+          throw new VersionNotOnBranchError();
+        }
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * One file's BYTES at a save, exactly as they were — the `after` side of
+   * `sha`, or the `before` side (`<sha>^`) for the save that deleted it.
+   *
+   * Every guard the text history surfaces apply, in the same order: the sha is
+   * a sha, the save is on this branch, and the pathspec is not a directory at
+   * that ref (a per-file gate upstream authorized one path, and a tree read
+   * would hand over every child). `null` means the file was not there on the
+   * side asked for.
+   *
+   * Runs inside the workspace's git turn — one turn for the whole read, so the
+   * ancestry check and the bytes it authorizes cannot be separated by another
+   * caller's checkout.
+   */
+  async fileBytesAtCommit(
+    workspaceId: string,
+    relativePath: string,
+    sha: string,
+    side: 'after' | 'before',
+  ): Promise<{ bytes: Buffer; blobId: string } | null> {
+    assertValidRelativePath(relativePath);
+    if (!/^[a-f0-9]{7,40}$/i.test(sha)) {
+      throw new WorkflowValidationError('invalid commit sha');
+    }
+    const repoRelativePath = this.stripRepoPrefix(relativePath);
+    return this.mutex.run(workspaceId, async () => {
+      const cwd = await this.repoDir(workspaceId);
+      await this.assertOnBranchHistory(cwd, sha);
+      const ref = side === 'before' ? `${sha}^` : sha;
+      await this.assertNotTreeAtRef(cwd, ref, repoRelativePath, relativePath);
+      return this.blobAtRef(cwd, ref, repoRelativePath);
+    });
+  }
+
   /**
    * The commits on `ref` that touched `repoRelativePath`, newest first, at
    * most `limit` of them. What a skill's `version` is looked up through: each
@@ -3377,6 +3524,27 @@ export class GitService implements IGitService {
       env: { GIT_LITERAL_PATHSPECS: '1', ...opts?.env },
     });
   }
+
+  /**
+   * {@link git}, with stdout as raw BYTES.
+   *
+   * A sibling rather than an `encoding` option on `git()` itself: every other
+   * caller in this service reads text, and the two return types (`string` vs
+   * `Buffer`) are not interchangeable at any call site. Same
+   * `GIT_LITERAL_PATHSPECS` and same runner deadline — the only difference is
+   * that the bytes are not decoded.
+   */
+  private gitBytes(
+    cwd: string,
+    args: string[],
+    opts?: Omit<GitRunOptions, 'encoding'>,
+  ): Promise<GitRunResult<Buffer>> {
+    return this.gitRunner.run(cwd, args, {
+      ...opts,
+      encoding: 'buffer',
+      env: { GIT_LITERAL_PATHSPECS: '1', ...opts?.env },
+    });
+  }
 }
 
 /** Map a git status letter (`git diff --name-status`) to the DTO's `PrFileStatus`. */

package/src/modules/workflow/pending-commits.service.ts

@@ -34,7 +34,7 @@
  *                                                    (status='needs_attention')
  */
 
-import { and, eq, inArray, isNull, min, or, sql } from 'drizzle-orm';
+import { and, eq, inArray, isNull, min, or, sql, type SQL } from 'drizzle-orm';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('pending-commits');
@@ -384,6 +384,64 @@ export class PendingCommitsService {
       .where(eq(pendingCommits.id, id));
   }
 
+  /**
+   * Take every commit still queued for `branch` out of the worker's reach and
+   * onto the admin surface, and answer how many moved.
+   *
+   * The one caller is the knowledge-base repository being REPLACED. A release
+   * ENQUEUES the bytes and only then drops its lock, so the moment the locks
+   * on a branch are dropped there may be rows already waiting — bytes that
+   * were written against a working copy of the repository that is gone. Left
+   * `pending`, the worker would pick them up after the re-clone and commit
+   * them onto a same-named branch of a DIFFERENT repository: someone else's
+   * file, overwritten by a change nobody made to it.
+   *
+   * `needs_attention`, not deleted — the same rule as everything else about a
+   * replacement. The bytes are still in the row, the reason is on it, and they
+   * show up on the pending-commit admin surface for a person to decide about.
+   * `running` rows go too: the worker checks the row back in when it finishes,
+   * and a row it is mid-flight with is exactly one whose destination just
+   * changed under it.
+   */
+  async markNeedsAttentionOnBranch(branch: string, error: string): Promise<number> {
+    return this.escalateQueued(eq(pendingCommits.branch, branch), error);
+  }
+
+  /** Every commit still queued that `which` selects goes to a person, with the reason. Answers how many. */
+  private async escalateQueued(which: SQL, error: string): Promise<number> {
+    const moved = await this.db
+      .update(pendingCommits)
+      .set({
+        status: 'needs_attention',
+        lastError: error,
+        lastAttemptedAt: new Date(),
+      })
+      .where(and(which, inArray(pendingCommits.status, ['pending', 'running'])))
+      .returning({ id: pendingCommits.id });
+    return moved.length;
+  }
+
+  /**
+   * The same, for every commit still queued against ONE WORKING COPY, and
+   * answer how many moved.
+   *
+   * The caller is the startup phase setting a working copy aside: a clone of
+   * a repository the configured one shares no history with. Whatever was
+   * queued for it was written against that clone, on any branch, the default
+   * one included, and the directory the worker would write to is now a fresh
+   * clone of another repository. Closing change requests covers the branches
+   * of the requests that were closed and nothing else, which is why this is
+   * keyed on the working copy: it is the thing that was replaced.
+   *
+   * A working copy that was only pointed at a new address (the same
+   * repository, moved) keeps its queue, and is never passed here.
+   */
+  async markNeedsAttentionInWorkspace(workspaceId: string, error: string): Promise<number> {
+    // The canonical form `enqueue` stores (see `canonicalWorkspaceId`), so the
+    // caller's spelling of the id cannot make this match nothing.
+    return this.escalateQueued(eq(pendingCommits.workspaceId, canonicalWorkspaceId(workspaceId)), error);
+  }
+
   /**
    * When the oldest commit still waiting to land was queued, or null when
    * nothing waits — the readiness answer's one number. `pending` and