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

package/src/modules/tool-auth/tool-auth.middleware.ts

@@ -4,6 +4,7 @@ import { logger } from '../../shared/logging.js';
 const log = logger('tools');
 import type { IExternalApiKeyService } from './external-api-key.interface.js';
 import type { AuthService } from '../auth/auth.service.js';
+import { ACCOUNT_DEACTIVATED_MESSAGE, AuthBackendError } from '../auth/account-admission.js';
 import { InternalTokenService } from './internal-token.service.js';
 import { INVALID_CONNECTION_KEY_CHALLENGE, INVALID_CONNECTION_KEY_MESSAGE } from './connection-key-rejection.js';
 
@@ -79,10 +80,10 @@ export const requireInternalSource: RequestHandler = (req, res, next) => {
 
 /**
  * Mirror of `requireInternalSource` for surfaces that must admit ONLY external
- * callers. `start_session` mints a fresh chat thread as the caller's
- * ontology-session id; an internal (in-process agent) token already carries
- * its run's `sessionId`, so letting it mint a new thread mid-run would
- * silently reset the one-ontology-per-conversation boundary.
+ * callers. `start_session` mints a fresh chat thread as the caller's session
+ * id; an internal (in-process agent) token already carries its run's
+ * `sessionId`, so letting it mint a new thread mid-run would silently split
+ * one conversation in two.
  *
  * "External" is decided by the VERIFIER, not by which credential shape
  * authenticated: a `bevel_…` connection key resolves external, and so does an
@@ -122,6 +123,15 @@ export type VerifyResult =
 export function createTokenVerifier(
   externalApiKeyService: IExternalApiKeyService,
   internalTokenService: InternalTokenService,
+  /**
+   * Whether the account an internal token was minted for is still on. An
+   * internal token carries only a user id and lives up to an hour (longer
+   * for the MCP loopback), so without this a switched-off account's running
+   * agent would keep working until it expired. Connection keys need no
+   * second look: their lookup reads the account. Every deployment passes
+   * it; absent, internal tokens are judged on their signature alone.
+   */
+  accounts?: Pick<AuthService, 'isActive'>,
 ): (token: string | undefined) => Promise<VerifyResult> {
   const missing = { ok: false as const, status: 401, message: 'A connection key or internal token is required' };
   return async (token) => {
@@ -136,6 +146,9 @@ export function createTokenVerifier(
     if (internalTokenService.looksLikeInternalToken(token)) {
       const claim = internalTokenService.verify(token);
       if (!claim) return { ok: false, status: 401, message: 'Invalid or expired internal token' };
+      if (accounts && !(await accounts.isActive(claim.userId))) {
+        return { ok: false, status: 401, message: ACCOUNT_DEACTIVATED_MESSAGE };
+      }
       return claim.externalProxy
         ? {
             ok: true,
@@ -170,8 +183,9 @@ export function createTokenVerifier(
 export function createToolAuthMiddleware(
   externalApiKeyService: IExternalApiKeyService,
   internalTokenService: InternalTokenService,
+  accounts?: Pick<AuthService, 'isActive'>,
 ): RequestHandler {
-  const verify = createTokenVerifier(externalApiKeyService, internalTokenService);
+  const verify = createTokenVerifier(externalApiKeyService, internalTokenService, accounts);
   return async (req: Request, res: Response, next: NextFunction) => {
     const header = req.headers.authorization;
     if (!header || !header.toLowerCase().startsWith('bearer ')) {
@@ -210,9 +224,9 @@ export function createToolAuthMiddleware(
 export function createManualAuthMiddleware(
   externalApiKeyService: IExternalApiKeyService,
   internalTokenService: InternalTokenService,
-  authService: AuthService,
+  authService: Pick<AuthService, 'isActive' | 'resolveSession'>,
 ): RequestHandler {
-  const verify = createTokenVerifier(externalApiKeyService, internalTokenService);
+  const verify = createTokenVerifier(externalApiKeyService, internalTokenService, authService);
   return async (req: Request, res: Response, next: NextFunction) => {
     const header = req.headers.authorization;
     if (!header || !header.toLowerCase().startsWith('bearer ')) {
@@ -241,13 +255,22 @@ export function createManualAuthMiddleware(
     }
 
     // Otherwise treat the bearer as a browser session JWT.
+    let userId: string;
     try {
-      const { userId } = authService.verifyToken(token);
-      req.toolAuth = { source: 'session', userId, scope: 'write' };
-      next();
-    } catch {
+      ({ userId } = await authService.resolveSession(token));
+    } catch (err) {
+      // The account could not be looked up: an outage, not a verdict on the
+      // session, and a 401 would sign a valid caller out over it.
+      if (err instanceof AuthBackendError) {
+        log.error('session account lookup failed:', { err: err.cause });
+        res.status(500).json({ error: 'Authentication backend unavailable' });
+        return;
+      }
       res.setHeader('WWW-Authenticate', WWW_AUTH);
       res.status(401).json({ error: 'Invalid or expired token' });
+      return;
     }
+    req.toolAuth = { source: 'session', userId, scope: 'write' };
+    next();
   };
 }

package/src/modules/tool-helpers/__tests__/agent-roles-write.test.ts

@@ -12,6 +12,7 @@ import { createToolHandlerFactory } from '../tool-handler.js';
 import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
 import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
 import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
 import { SpillStore } from '../../workspace/spill-store.js';
 import { DocExtractService } from '../../workspace/file-readers/doc-extract.service.js';
 import { NEW_ROLE_GUIDANCE } from '../../access-model/roles-yaml-guard.js';
@@ -68,13 +69,14 @@ async function start(): Promise<string> {
     canOwner: async () => true,
     canWriteBatchAtRef: async () => null,
     canReadBatch: async (_w: string, _u: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
+    // The `after` half of a move's or copy's preview — allowing everything, like the gates above.
+    previewAccessAfterRelocation: async () => ({ read: true, write: true, download: true, owner: true }),
   } as never;
   registerWorkspaceTools(registry, router, toolAuth, createToolHandlerFactory(resolve), new SpillStore(path.join(os.tmpdir(), 'bevel-test-spills')), new DocExtractService(docCache), allowAll, testKbContext({ kbDirName: KB }), {
-    service: {} as never,
-    enabled: false, // ontology boundary not under test here
-    kb: testKbContext({ kbDirName: KB }),
+    // No hook registered: the agent-access gate refuses nothing here.
     recoveryBotEmail: 'recovery-bot@bevel.local',
     hooks: new WorkflowHooks(),
+    notes: new ToolDescriptionNotes(),
   }, new RoutineWritePolicyService(), {} as never);
   const app = express();
   app.use(express.json());

package/src/modules/tool-helpers/__tests__/phase4-tools.test.ts

@@ -10,6 +10,7 @@ import { createManualRoutes } from '../../tool-registry/manual.routes.js';
 import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
 import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
 import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
 import { SpillStore } from '../../workspace/spill-store.js';
 import { DocExtractService } from '../../workspace/file-readers/doc-extract.service.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
@@ -65,11 +66,10 @@ async function start(): Promise<string> {
   // and their web_search / submit_feedback / cite_kb_node cases — moved to
   // the enterprise repo with their modules; core registers only core tools.
   registerWorkspaceTools(registry, router, toolAuth, th, new SpillStore('/tmp/bevel-test-spills'), new DocExtractService('/tmp/bevel-test-doc-extract'), accessControl, testKbContext(), {
-    service: {} as never,
-    enabled: false, // ontology boundary not under test here
-    kb: testKbContext(),
+    // No hook registered: the agent-access gate refuses nothing here.
     recoveryBotEmail: 'recovery-bot@bevel.local',
     hooks: new WorkflowHooks(),
+    notes: new ToolDescriptionNotes(),
   }, new RoutineWritePolicyService(), {} as never /* sessionSink — start_session not exercised here */);
   router.use(createManualRoutes(registry, toolAuth));
 

package/src/modules/tool-helpers/__tests__/validate-token.test.ts

@@ -18,7 +18,11 @@ const externalApiKeyService = {
   verifyAndLoadToken: async (t: string) =>
     t === 'bevel_ok' ? { user: { id: 'u-ext', email: 'e@x', name: 'Ext' }, tokenId: 'tk-1' } : null,
 } as never;
-const authService = { getUserById: async (id: string) => ({ id, email: 'e@x', name: 'N' }) } as never;
+// Every account is on except `u-off`, which an admin switched off.
+const authService = {
+  getUserById: async (id: string) => ({ id, email: 'e@x', name: 'N' }),
+  isActive: async (id: string) => id !== 'u-off',
+} as never;
 
 let tempDir = '';
 const workspaceService = {
@@ -66,6 +70,12 @@ describe('validateToken (tool-author SDK entry)', () => {
     expect((await fs.readFile('a.md')).toString()).toBe('hi');
   });
 
+  it('throws a 401 ToolError for a valid internal token whose account was switched off', async () => {
+    const err = await validateToken(internalToken.mint({ userId: 'u-off' })).catch((e) => e);
+    expect(hasHttpStatus(err) && err.status).toBe(401);
+    expect((err as Error).message).toContain('switched off');
+  });
+
   it('throws a 401 ToolError on a bad token and an empty token', async () => {
     for (const bad of ['garbage', 'bevel_nope', '', undefined]) {
       const err = await validateToken(bad as string).catch((e) => e);

package/src/modules/tool-helpers/tool-handler.ts

@@ -6,6 +6,7 @@ import { hasHttpStatus, ToolError, type ToolHandler } from './tool.contract.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 import type { ResolveToolContext } from './tool-context.js';
+import { alwaysWritable, READ_ONLY_CODE, refuseWriteTool, type IWriteAccess } from '../write-access/write-access.js';
 import '../tool-auth/tool-auth.middleware.js'; // Express Request.toolAuth augmentation
 
 function isAsyncIterable(v: unknown): v is AsyncIterable<unknown> {
@@ -29,7 +30,7 @@ export interface ToolHandlerOptions {
  * The handler receives `req.body` as the flat args (UTCP's `body_field` already
  * delivered the inner body as the request body).
  */
-export function createToolHandlerFactory(resolve: ResolveToolContext) {
+export function createToolHandlerFactory(resolve: ResolveToolContext, writeAccess: IWriteAccess = alwaysWritable) {
   return function toolHandler(handler: ToolHandler, opts: ToolHandlerOptions = {}) {
     return async (req: Request, res: Response): Promise<void> => {
       const auth = req.toolAuth;
@@ -41,10 +42,29 @@ export function createToolHandlerFactory(resolve: ResolveToolContext) {
         res.status(403).json({ error: 'This tool requires write access.' });
         return;
       }
+      // Before anything is awaited: a client that goes away during the
+      // write-access check below must still abort the call.
+      //
+      // Asked of the RESPONSE. The request closes as soon as its body has
+      // been read, with the client still there and waiting, so its `close`
+      // says nothing about the client; the response closes when it has been
+      // sent or the connection is gone, and `writableEnded` tells the two
+      // apart.
       const abort = new AbortController();
-      req.on('close', () => {
+      res.on('close', () => {
         if (!res.writableEnded) abort.abort();
       });
+      // The tool layer's half of the read-only gate: the HTTP gate lets every
+      // tool call through, since only here is a write tool told from a read.
+      if (opts.write) {
+        const refusal = await refuseWriteTool(writeAccess);
+        if (refusal !== null) {
+          res.status(403).json({ error: refusal, code: READ_ONLY_CODE });
+          return;
+        }
+        // The client left while the verdict was awaited: nobody to answer.
+        if (abort.signal.aborted) return;
+      }
       const body: unknown = req.body;
       if (body !== undefined && body !== null && (typeof body !== 'object' || Array.isArray(body))) {
         res.status(400).json({ error: 'Request body must be a JSON object.' });
@@ -53,8 +73,8 @@ export function createToolHandlerFactory(resolve: ResolveToolContext) {
       const args = (body ?? {}) as Record<string, unknown>;
       // `sessionId` rides the tool body like `branch` does: the external MCP
       // proxy injects it (ask-tool continuity convention) and the in-process
-      // agent passes its thread id. Surfaced on the context so the ontology
-      // gate can scope to one run without each handler re-reading args.
+      // agent passes its thread id. Surfaced on the context so the
+      // agent-access gate can name the run without each handler re-reading args.
       const sessionId = typeof args.sessionId === 'string' && args.sessionId.length > 0
         ? args.sessionId
         : undefined;

package/src/modules/tool-helpers/tool.contract.ts

@@ -34,8 +34,9 @@ export interface ToolContext {
    * The agent run / conversation id this call belongs to (the agent thread id).
    * Supplied as a `sessionId` field on the tool's input body — the external MCP
    * proxy injects it via the `ask`-tool continuity convention, and the
-   * in-process agent passes its thread id. Used to scope the ontology-session
-   * boundary to one run. Absent for non-agent or unthreaded calls.
+   * in-process agent passes its thread id. Handed to the agent-access hooks,
+   * which is how a deployment scopes a rule to one conversation. Absent for
+   * non-agent or unthreaded calls.
    */
   sessionId?: string;
   /**

package/src/modules/tool-helpers/validate-token.ts

@@ -35,7 +35,7 @@ export type ValidateToken = (
 ) => Promise<ToolContext>;
 
 export function createToolValidator(deps: ToolValidatorDeps): ValidateToken {
-  const verify = createTokenVerifier(deps.externalApiKeyService, deps.internalTokenService);
+  const verify = createTokenVerifier(deps.externalApiKeyService, deps.internalTokenService, deps.authService);
   const resolve = createToolContextResolver(deps);
   return async (token, signal) => {
     let result;

package/src/modules/workflow/__tests__/pending-commits.repository-replaced.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { SQL } from 'drizzle-orm';
+import { PgDialect } from 'drizzle-orm/pg-core';
+import { PendingCommitsService } from '../pending-commits.service.js';
+import type { Database } from '../../database/connection.js';
+
+/**
+ * Commits still queued for a branch when the knowledge-base repository is
+ * 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 — written
+ * against a working copy of the repository that is gone. Left `pending`, the
+ * worker picks them up after the re-clone and commits them onto a same-named
+ * branch of a DIFFERENT repository: somebody else's file, overwritten by a
+ * change nobody made to it.
+ *
+ * So they are escalated, never dropped: the bytes stay in the row, the reason
+ * is on it, and a person decides.
+ */
+function makeFakeDb(moved: Array<{ id: string }>) {
+  const sets: Record<string, unknown>[] = [];
+  const db = {
+    update: vi.fn(() => ({
+      set: (values: Record<string, unknown>) => {
+        sets.push(values);
+        return { where: () => ({ returning: async () => moved }) };
+      },
+    })),
+    // Queued bytes are never thrown away over this.
+    delete: () => {
+      throw new Error('a queued commit must never be deleted');
+    },
+  } as unknown as Database;
+  return { db, sets };
+}
+
+describe('PendingCommitsService.markNeedsAttentionOnBranch', () => {
+  it('escalates every queued commit on the branch, with the reason, and answers how many', async () => {
+    const { db, sets } = makeFakeDb([{ id: 'a' }, { id: 'b' }]);
+    const svc = new PendingCommitsService(db);
+
+    await expect(
+      svc.markNeedsAttentionOnBranch('alice/draft', 'The repository was replaced.'),
+    ).resolves.toBe(2);
+
+    expect(sets).toHaveLength(1);
+    // `needs_attention` is the status the admin surface reads — the row is out
+    // of the worker's reach and in front of a person.
+    expect(sets[0]?.status).toBe('needs_attention');
+    expect(sets[0]?.lastError).toBe('The repository was replaced.');
+    expect(sets[0]?.lastAttemptedAt).toBeInstanceOf(Date);
+  });
+
+  it('answers zero when nothing was queued for that branch', async () => {
+    const { db } = makeFakeDb([]);
+    const svc = new PendingCommitsService(db);
+    await expect(svc.markNeedsAttentionOnBranch('quiet/branch', 'whatever')).resolves.toBe(0);
+  });
+});
+
+/**
+ * The same, keyed on the WORKING COPY that was set aside. Closing change
+ * requests covers their branches and nothing else; a commit queued on the
+ * default branch was written against the repository that was left all the
+ * same, and the path it names is about to hold a clone of another one.
+ */
+describe('PendingCommitsService.markNeedsAttentionInWorkspace', () => {
+  it('escalates every queued commit for the working copy, with the reason, and answers how many', async () => {
+    const { db, sets } = makeFakeDb([{ id: 'a' }, { id: 'b' }, { id: 'c' }]);
+    const svc = new PendingCommitsService(db);
+
+    await expect(svc.markNeedsAttentionInWorkspace('main', 'The repository was replaced.')).resolves.toBe(3);
+
+    expect(sets).toHaveLength(1);
+    expect(sets[0]?.status).toBe('needs_attention');
+    expect(sets[0]?.lastError).toBe('The repository was replaced.');
+    expect(sets[0]?.lastAttemptedAt).toBeInstanceOf(Date);
+  });
+
+  /**
+   * Rows are stored under the encoded id, whichever spelling the caller
+   * enqueued with. The predicate is rendered and read, since the stub does
+   * not evaluate it: the id it compares must be the stored spelling, and it
+   * must match only the two statuses a worker could still write, `pending`
+   * and `running`.
+   */
+  it('looks for the working copy under the id the queue stores, and only for commits still queued', async () => {
+    const wheres: SQL[] = [];
+    const db = {
+      update: () => ({
+        set: () => ({
+          where: (predicate: SQL) => {
+            wheres.push(predicate);
+            return { returning: async () => [] };
+          },
+        }),
+      }),
+    } as unknown as Database;
+    await new PendingCommitsService(db).markNeedsAttentionInWorkspace('alice/feature', 'whatever');
+
+    const { sql: text, params } = new PgDialect().sqlToQuery(wheres[0]!);
+    expect(text).toContain('"workspace_id" =');
+    expect(params).toEqual(['alice%2Ffeature', 'pending', 'running']);
+  });
+
+  it('answers zero when nothing was queued for it', async () => {
+    const { db } = makeFakeDb([]);
+    await expect(new PendingCommitsService(db).markNeedsAttentionInWorkspace('main', 'whatever')).resolves.toBe(0);
+  });
+});

package/src/modules/workflow/__tests__/workflow.routes.history-read-gate.test.ts

@@ -8,6 +8,10 @@ import type { AuthService } from '../../auth/auth.service.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { WorkflowEventBus } from '../event-bus.js';
 import { createWorkflowRoutes } from '../workflow.routes.js';
+import {
+  VersionNotOnBranchError,
+  VERSION_NOT_ON_BRANCH_MESSAGE,
+} from '../../../shared/domain-errors.js';
 
 // A file's history is its content with a time axis: the same default-deny
 // read model that hides a file must hide its commit list, its diffs, and its
@@ -129,6 +133,27 @@ describe('history routes enforce the read model', () => {
     expect((await get(`/compare-file?from=a&to=b&path=${OPEN}`)).status).toBe(403);
   });
 
+  it.each([
+    ['/show-file?sha=abc1234&path=%s', 'showFileAtChange'],
+    ['/file-at-change?sha=abc1234&path=%s', 'fileAtChange'],
+  ] as const)(
+    '%s: a save off this branch is refused with the history message',
+    async (route, method) => {
+      // The service raises it (the git layer knows the branch); the route has
+      // to pass the typed refusal through with its own status and sentence,
+      // because a reader who is told "not found" about a file that is plainly
+      // there learns the wrong thing. The bytes route carries the same rule,
+      // so neither can be read around through the other.
+      h = await makeHarness();
+      h.workflow[method].mockRejectedValueOnce(new VersionNotOnBranchError());
+      const res = await get(route.replace('%s', OPEN));
+      expect(res.status).toBe(404);
+      expect(((await res.json()) as { error: string }).error).toBe(
+        VERSION_NOT_ON_BRANCH_MESSAGE,
+      );
+    },
+  );
+
   it('an access-model error fails closed, not open', async () => {
     h = await makeHarness();
     h.canRead.mockRejectedValueOnce(new Error('access tree unreadable'));

package/src/modules/workflow/__tests__/workflow.service.repository-replaced.test.ts

@@ -0,0 +1,249 @@
+import { describe, it, expect, vi } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+import type { GitService } from '../git/git.service.js';
+import type { PullRequestService } from '../git/pull-request.service.js';
+import type { IReviewWorkflowService } from '../review-workflow/review-workflow.interface.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { FileLockService } from '../file-lock.service.js';
+import type { PendingCommitsService } from '../pending-commits.service.js';
+import type { Database } from '../../database/connection.js';
+import { WorkflowService } from '../workflow.service.js';
+import { openChangeGate } from '../../../__tests__/open-change-gate.js';
+
+/**
+ * The CLOSE half of the admin's choice when the knowledge-base repository is
+ * replaced: the requests point at branches that are not in the new
+ * repository, so they are closed — with a reason, releasing the locks held on
+ * those branches and taking any commit still queued for them off the worker,
+ * and without deleting a single row.
+ */
+
+interface ClosedRow {
+  number: number;
+  sourceBranch: string;
+}
+
+/**
+ * DB stub shaped like the real close: ONE `update … where state = 'open'
+ * returning` per pass, answering with the rows that pass actually closed.
+ *
+ * `passes` is therefore what the statement RETURNS, pass by pass — which is
+ * how a request already closed by a merge or a withdrawal is expressed (it is
+ * simply not in the returned set) and how a request opened BETWEEN passes is
+ * expressed (it turns up in a later one). A pass past the end answers nothing,
+ * which is what stops the loop.
+ */
+function makeDb(passes: ClosedRow[][], sets: Record<string, unknown>[], openCount: number) {
+  let pass = 0;
+  const db = {
+    // The count is a SQL aggregate: one row, one integer.
+    select: () => ({ from: () => ({ where: async () => [{ open: openCount }] }) }),
+    update: () => ({
+      set: (values: Record<string, unknown>) => {
+        sets.push(values);
+        return { where: () => ({ returning: async () => passes[pass++] ?? [] }) };
+      },
+    }),
+    // Nothing here may ever delete a change request.
+    delete: () => {
+      throw new Error('a change request must never be deleted');
+    },
+  };
+  return db as unknown as Database;
+}
+
+function makeService(passes: ClosedRow[][], openCount = passes.flat().length) {
+  const sets: Record<string, unknown>[] = [];
+  const unlocked: string[] = [];
+  const dequeued: string[] = [];
+  const invalidated: number[] = [];
+  const emitted: unknown[] = [];
+  const fileLocks = {
+    releaseAllOnBranch: vi.fn(async (branch: string) => {
+      unlocked.push(branch);
+      return 2;
+    }),
+  } as unknown as FileLockService;
+  const pendingCommits = {
+    markNeedsAttentionOnBranch: vi.fn(async (branch: string) => {
+      dequeued.push(branch);
+      return 1;
+    }),
+  } as unknown as PendingCommitsService;
+  const prs = {
+    invalidateDetailCache: vi.fn((n: number) => invalidated.push(n)),
+  } as unknown as PullRequestService;
+  const svc = new WorkflowService(
+    makeDb(passes, sets, openCount),
+    {} as GitService,
+    prs,
+    {} as IReviewWorkflowService,
+    {} as WorkspaceService,
+    {} as IAccessControl,
+    fileLocks,
+    pendingCommits,
+    testKbContext(),
+    openChangeGate(),
+  );
+  (svc as unknown as { events?: { emit(e: unknown): void } }).events = {
+    emit: (e: unknown) => emitted.push(e),
+  };
+  return { svc, sets, unlocked, dequeued, invalidated, emitted, fileLocks, pendingCommits };
+}
+
+describe('closeOpenChangeRequestsAsRepositoryReplaced', () => {
+  it('closes every open request with the reason, and deletes nothing', async () => {
+    const { svc, sets, invalidated, emitted } = makeService([
+      [
+        { number: 7, sourceBranch: 'alice/draft' },
+        { number: 9, sourceBranch: 'bob/draft' },
+      ],
+    ]);
+
+    await expect(svc.closeOpenChangeRequestsAsRepositoryReplaced()).resolves.toBe(2);
+
+    // ONE statement closed both: a read-then-write loop would have missed any
+    // request opened while it ran.
+    expect(sets).toHaveLength(2); // the closing pass, then the pass that found nothing
+    expect(sets[0]?.state).toBe('closed');
+    // The reason outlives the admin who chose it — that is the whole point
+    // of a column rather than a log line.
+    expect(sets[0]?.closedReason).toBe('repository-replaced');
+    expect(sets[0]?.closedAt).toBeInstanceOf(Date);
+    expect(invalidated).toEqual([7, 9]);
+    expect(emitted).toEqual([
+      { kind: 'change-request-rejected', number: 7 },
+      { kind: 'change-request-rejected', number: 9 },
+    ]);
+  });
+
+  it('closes a request opened while it was closing the others', async () => {
+    // The deployment is still live — the address has not been saved yet — so
+    // `POST /change-requests` is still being served. The first pass closed two;
+    // #11 arrived after it and is closed by the next one.
+    const { svc, invalidated } = makeService([
+      [
+        { number: 7, sourceBranch: 'alice/draft' },
+        { number: 9, sourceBranch: 'bob/draft' },
+      ],
+      [{ number: 11, sourceBranch: 'carol/draft' }],
+    ]);
+
+    await expect(svc.closeOpenChangeRequestsAsRepositoryReplaced()).resolves.toBe(3);
+    expect(invalidated).toEqual([7, 9, 11]);
+  });
+
+  it('gives up after a bounded number of passes rather than holding the save open', async () => {
+    // A client opening requests in a loop must not be able to keep the save
+    // from ever returning. What survives the last pass was opened after the
+    // repository was replaced, and the deleted-branch sweep owns it.
+    const endless = Array.from({ length: 50 }, (_, i) => [
+      { number: i + 1, sourceBranch: `writer-${i}/draft` },
+    ]);
+    const { svc } = makeService(endless, 50);
+    const closed = await svc.closeOpenChangeRequestsAsRepositoryReplaced();
+    expect(closed).toBeGreaterThan(0);
+    expect(closed).toBeLessThan(50);
+  });
+
+  it('skips a request a merge or a withdrawal closed first', async () => {
+    // The guard is the statement's own `where state = 'open'`: #9 was closed by
+    // somebody else between the count and this call, so it is not in the
+    // returned set — and nothing is done on its behalf.
+    const { svc, unlocked, dequeued, invalidated, emitted } = makeService(
+      [[{ number: 7, sourceBranch: 'alice/draft' }]],
+      2,
+    );
+
+    await expect(svc.closeOpenChangeRequestsAsRepositoryReplaced()).resolves.toBe(1);
+
+    expect(unlocked).toEqual(['alice/draft']);
+    expect(dequeued).toEqual(['alice/draft']);
+    expect(invalidated).toEqual([7]);
+    expect(emitted).toEqual([{ kind: 'change-request-rejected', number: 7 }]);
+  });
+
+  it('releases the file locks held on the branches it closes', async () => {
+    const { svc, unlocked } = makeService([
+      [
+        { number: 7, sourceBranch: 'alice/draft' },
+        { number: 9, sourceBranch: 'bob/draft' },
+      ],
+    ]);
+
+    await svc.closeOpenChangeRequestsAsRepositoryReplaced();
+
+    // Nobody can publish those bytes or release the lock by finishing: the
+    // branch belongs to a repository this deployment no longer has.
+    expect(unlocked).toEqual(['alice/draft', 'bob/draft']);
+  });
+
+  it('takes the commits already queued for those branches off the worker', async () => {
+    const { svc, dequeued, pendingCommits } = makeService([
+      [{ number: 7, sourceBranch: 'alice/draft' }],
+    ]);
+
+    await svc.closeOpenChangeRequestsAsRepositoryReplaced();
+
+    // A release ENQUEUES the bytes and only then drops its lock, so dropping
+    // the locks can leave rows waiting. Left pending, the worker would commit
+    // them onto a same-named branch of a different repository after the
+    // re-clone.
+    expect(dequeued).toEqual(['alice/draft']);
+    expect(vi.mocked(pendingCommits.markNeedsAttentionOnBranch).mock.calls[0]?.[1]).toMatch(
+      /repository was replaced/,
+    );
+  });
+
+  it('still closes the requests when a lock release fails', async () => {
+    const { svc, fileLocks } = makeService([[{ number: 7, sourceBranch: 'alice/draft' }]]);
+    vi.mocked(fileLocks.releaseAllOnBranch).mockRejectedValueOnce(new Error('lock table is down'));
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      // The close is the decision the admin made; a lock expires on its own
+      // within the minute, so it is not worth half-closing the set over.
+      await expect(svc.closeOpenChangeRequestsAsRepositoryReplaced()).resolves.toBe(1);
+    } finally {
+      vi.restoreAllMocks();
+    }
+  });
+
+  it('still closes the requests when the queued commits cannot be set aside', async () => {
+    const { svc, pendingCommits, unlocked } = makeService([
+      [{ number: 7, sourceBranch: 'alice/draft' }],
+    ]);
+    vi.mocked(pendingCommits.markNeedsAttentionOnBranch).mockRejectedValueOnce(
+      new Error('pending_commits is down'),
+    );
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      await expect(svc.closeOpenChangeRequestsAsRepositoryReplaced()).resolves.toBe(1);
+      expect(unlocked).toEqual(['alice/draft']);
+    } finally {
+      vi.restoreAllMocks();
+    }
+  });
+
+  it('closes nothing, and asks nothing of the lock table, when no request is open', async () => {
+    const { svc, unlocked, dequeued, emitted } = makeService([]);
+    await expect(svc.closeOpenChangeRequestsAsRepositoryReplaced()).resolves.toBe(0);
+    expect(unlocked).toEqual([]);
+    expect(dequeued).toEqual([]);
+    expect(emitted).toEqual([]);
+  });
+});
+
+describe('countOpenChangeRequests', () => {
+  it('answers how many are open, so the confirmation can say what it is about', async () => {
+    const { svc } = makeService([], 2);
+    // A SQL aggregate: the question is an integer, and materializing one row
+    // per open request to answer it would scale with the wrong thing.
+    await expect(svc.countOpenChangeRequests()).resolves.toBe(2);
+  });
+
+  it('answers zero when the aggregate comes back empty', async () => {
+    const { svc } = makeService([], 0);
+    await expect(svc.countOpenChangeRequests()).resolves.toBe(0);
+  });
+});