@bevel-software/platform-core-backend 0.30.0 → 0.32.0

package/src/modules/audit/audit.routes.ts

@@ -7,6 +7,7 @@ import {
   AuditPrincipalNotFoundError,
   InvalidCursorError,
   isUuid,
+  parsePagePrincipalId,
   type AuditPrincipalRef,
   type IAgentAuditService,
 } from './audit.contract.js';
@@ -20,7 +21,7 @@ const DEFAULT_EVENT_PAGE = 50;
 /**
  * The Audit log's routes, JWT-only (mounted behind the session middleware):
  *
- *   GET    /api/audit/principals?scope=me|all           — agents + keys, with owners and event counts
+ *   GET    /api/audit/principals?scope=me|all           — agents, keys and pages, with owners and event counts
  *   GET    /api/audit/principals/:kind/:id/events        — one principal's events, newest first, cursor-paged
  *   DELETE /api/audit/agents/:id                         — revoke an agent (owner or admin)
  *   DELETE /api/audit/keys/:id                           — revoke a key (owner or admin)
@@ -44,14 +45,20 @@ export function createAuditRoutes(
   const principalOf = (req: express.Request): AuditPrincipalRef | null => {
     const kind = String(req.params.kind);
     const id = String(req.params.id);
+    if (kind === 'page') return parsePagePrincipalId(id) ? { kind, id } : null;
     if ((kind !== 'key' && kind !== 'agent') || !isUuid(id)) return null;
     return { kind, id };
   };
 
-  /** Whether the caller may read or revoke `principal`: its owner, or an admin. Null when there is no such principal. */
-  const mayAct = async (req: express.Request, principal: AuditPrincipalRef): Promise<boolean | null> => {
+  /**
+   * Whether the caller may read `principal`'s events: its owner, or an admin.
+   * False both when there is no such principal and when it is someone else's,
+   * so the refusal does not tell a member which of another person's pages,
+   * agents or keys exist.
+   */
+  const mayRead = async (req: express.Request, principal: AuditPrincipalRef): Promise<boolean> => {
     const owner = await audit.ownerOf(principal);
-    if (owner === null) return null;
+    if (owner === null) return false;
     if (owner === req.userId) return true;
     return isAdmin(req);
   };
@@ -74,17 +81,12 @@ export function createAuditRoutes(
   router.get('/audit/principals/:kind/:id/events', async (req, res) => {
     const principal = principalOf(req);
     if (!principal) {
-      res.status(404).json({ error: 'No such agent or key' });
+      res.status(404).json({ error: 'No such agent, key or page' });
       return;
     }
     try {
-      const allowed = await mayAct(req, principal);
-      if (allowed === null) {
-        res.status(404).json({ error: 'No such agent or key' });
-        return;
-      }
-      if (!allowed) {
-        res.status(403).json({ error: 'Not yours' });
+      if (!(await mayRead(req, principal))) {
+        res.status(404).json({ error: 'No such agent, key or page' });
         return;
       }
       const rawLimit = Number(req.query.limit);

package/src/modules/audit/request-audit.ts

@@ -1,6 +1,6 @@
 import type { CodeModeUtcpClient } from '@utcp/code-mode';
 import { logger } from '../../shared/logging.js';
-import type { AgentEventOutcome, AuditPrincipalRef, IAgentEventRecorder } from './audit.contract.js';
+import type { AgentEventOutcome, IAgentEventRecorder, RecordedPrincipal } from './audit.contract.js';
 import {
   classifyToolCall,
   skillReadPath,
@@ -13,11 +13,11 @@ const log = logger('audit');
 
 /**
  * The Audit log's view of ONE MCP request: who is calling (the user and the
- * key or agent connection the request arrived through), and how to name what
- * they call. The MCP proxy creates one per request that has a principal and
- * routes every call through it; a request with none (a browser JWT, an
- * internal token minted before connections existed) gets no instance and
- * records nothing.
+ * key, agent connection or page the request arrived through), and how to name
+ * what they call. The MCP proxy creates one per request that has a principal
+ * and routes every call through it; a request with none (a browser JWT that
+ * names no page, an internal token minted before connections existed) gets no
+ * instance and records nothing.
  *
  * Holds nothing that outlives the request. The skill catalog it may need to
  * tell a skill read from a file read is fetched at most once, and only when
@@ -29,7 +29,7 @@ export class RequestAudit {
   constructor(
     private readonly recorder: IAgentEventRecorder,
     private readonly userId: string,
-    private readonly principal: AuditPrincipalRef,
+    private readonly principal: RecordedPrincipal,
     private readonly ctx: {
       kbManualName: string;
       /** Read at classification time — the surface (and its catalog names) is built lazily. */
@@ -93,9 +93,13 @@ export class RequestAudit {
     }
   }
 
-  /** A call refused before it ran, because the caller's sign-in for its manual is missing. */
-  async denied(utcpName: string, args: Record<string, unknown>): Promise<void> {
-    this.emit(await this.classify(utcpName, args), 'denied', null);
+  /**
+   * A call refused before it ran: `denied` when the caller's sign-in for its
+   * manual is missing, `refused` when the person viewing a page answered its
+   * request to write with Deny.
+   */
+  async denied(utcpName: string, args: Record<string, unknown>, outcome: 'denied' | 'refused' = 'denied'): Promise<void> {
+    this.emit(await this.classify(utcpName, args), outcome, null);
   }
 
   /**
@@ -106,11 +110,22 @@ export class RequestAudit {
    * The direct MCP path (`callToolStreaming`) is deliberately NOT wrapped —
    * the proxy's tool handler records those itself, with the result's
    * `isError` in hand.
+   *
+   * Installed ONCE, when the client is built, because the client is shared by
+   * every request of its person: `current` names the request a call belongs
+   * to, at call time, and a call outside any request (or in one attributed to
+   * nothing) is recorded nowhere. Rebinding the client per request instead
+   * would hand one request's calls to another's audit, and stack a wrapper
+   * per request.
    */
-  instrumentChainCalls(client: CodeModeUtcpClient): void {
+  static instrumentChainCalls(client: CodeModeUtcpClient, current: () => RequestAudit | null | undefined): void {
     const callTool = client.callTool.bind(client);
-    client.callTool = (toolName: string, toolArgs: Record<string, unknown>) =>
-      this.call(toolName, toolArgs, () => callTool(toolName, toolArgs), isErrorShaped);
+    client.callTool = (toolName: string, toolArgs: Record<string, unknown>) => {
+      const audit = current();
+      return audit
+        ? audit.call(toolName, toolArgs, () => callTool(toolName, toolArgs), isErrorShaped)
+        : callTool(toolName, toolArgs);
+    };
   }
 
   private skillCatalog(): Promise<readonly SkillFolder[] | null> {

package/src/modules/auth/__tests__/account-deactivation.test.ts

@@ -25,10 +25,17 @@ import { RECOVERY_BOT_EMAIL } from '../../workflow/recovery-bot.js';
  * shows up as `db:`.
  */
 function makeFakeDb(queue: unknown[]) {
-  const captured: { values: Record<string, unknown>[]; set: Record<string, unknown>[]; order: string[] } = {
+  const captured: {
+    values: Record<string, unknown>[];
+    set: Record<string, unknown>[];
+    order: string[];
+    /** Every `where` predicate, rendered to the SQL it would send. */
+    where: { sql: string; params: unknown[] }[];
+  } = {
     values: [],
     set: [],
     order: [],
+    where: [],
   };
   const dialect = new PgDialect();
   function nextChain(): unknown {
@@ -42,7 +49,10 @@ function makeFakeDb(queue: unknown[]) {
     Object.assign(chain, {
       values: passthrough((a) => captured.values.push(a)),
       set: passthrough((a) => captured.set.push(a)),
-      where: passthrough(),
+      where: passthrough((a) => {
+        const { sql, params } = dialect.sqlToQuery(a as unknown as SQL);
+        captured.where.push({ sql, params });
+      }),
       limit: passthrough(),
       from: passthrough(),
       orderBy: passthrough(),
@@ -124,6 +134,32 @@ describe('signing in with a switched-off account', () => {
   });
 });
 
+describe('the accounts a change request\'s approvers resolve to', () => {
+  it('are read in one indexed query through the email blind index, live accounts only, keyed by canonical address', async () => {
+    const { db, captured } = makeFakeDb([[{ id: 'user-1', email: 'Alice@Example.com', name: 'Alice' }]]);
+    const svc = new AuthService(db, makeConfig());
+    const found = await svc.findActiveAccountsByEmail(['ALICE@example.com', 'alice@example.com', 'bob@example.com']);
+    // One read, by the blind index, with the addresses canonicalised and
+    // deduplicated, and a switched-off account excluded in the query itself.
+    expect((db as unknown as { select: ReturnType<typeof vi.fn> }).select).toHaveBeenCalledTimes(1);
+    expect(captured.where).toHaveLength(1);
+    expect(captured.where[0]!.sql).toMatch(/"users"."email_bidx" in \(\$1, \$2\) and "users"."deactivated_at" is null/);
+    // The blind-index column hashes each address with the handle's key as
+    // the query is sent; what was asked for is the canonical plain address.
+    expect(captured.where[0]!.params.map((p) => (p as { plain: string }).plain)).toEqual(['alice@example.com', 'bob@example.com']);
+    // Keyed by the canonical address, whatever spelling the row holds.
+    expect([...found.keys()]).toEqual(['alice@example.com']);
+    expect(found.get('alice@example.com')).toEqual({ id: 'user-1', email: 'Alice@Example.com', name: 'Alice' });
+  });
+
+  it('asks nothing for no addresses', async () => {
+    const { db } = makeFakeDb([]);
+    const svc = new AuthService(db, makeConfig());
+    expect(await svc.findActiveAccountsByEmail([])).toEqual(new Map());
+    expect((db as unknown as { select: ReturnType<typeof vi.fn> }).select).not.toHaveBeenCalled();
+  });
+});
+
 describe('a session that outlives a deactivation', () => {
   it('stops being accepted once the account is switched off', async () => {
     const { db } = makeFakeDb([[ROW], [{ deactivatedAt: new Date() }]]);

package/src/modules/auth/account-hooks.ts

@@ -1,5 +1,6 @@
 import type { AuthUser } from '@bevel-software/platform-shared';
 import { logger } from '../../shared/logging.js';
+import { ListenerSeam, type NotifyingListener } from '../../shared/listener-seam.js';
 
 const log = logger('accounts');
 
@@ -24,13 +25,10 @@ export interface AccountInvitedEvent {
 
 /**
  * A listener answers how it reached the person — a non-empty channel name,
- * `'email'` say — or null when it did not (nothing configured, the send
- * failed). It is awaited: the admin's answer says who was notified,
- * truthfully, so a listener bounds its own wait. A throw is logged and
- * counts as null; it never fails the invite. An empty name is no channel and
- * counts as null too.
+ * `'email'` say — or null when it did not; the rule is {@link NotifyingListener}'s:
+ * awaited, a throw logged and counted as null, never failing the invite.
  */
-export type AccountInvitedHook = (event: AccountInvitedEvent) => Promise<string | null>;
+export type AccountInvitedHook = NotifyingListener<AccountInvitedEvent>;
 
 /**
  * Core's seam for "an account was invited": a deployment (the cloud with its
@@ -46,24 +44,18 @@ export interface IAccountHooks {
 }
 
 export class AccountHooks implements IAccountHooks {
-  private readonly invited: AccountInvitedHook[] = [];
+  // The account exists whether or not the person was told: the admin's
+  // answer says they were not, and the admin sends the link themselves.
+  private readonly invited = new ListenerSeam<AccountInvitedEvent>(
+    log,
+    'an account-invited listener failed; the person was not notified by it:',
+  );
 
   onAccountInvited(hook: AccountInvitedHook): void {
-    this.invited.push(hook);
+    this.invited.add(hook);
   }
 
-  async runAccountInvited(event: AccountInvitedEvent): Promise<string[]> {
-    const notified: string[] = [];
-    for (const hook of this.invited) {
-      try {
-        const channel = await hook(event);
-        if (channel !== null && channel !== '') notified.push(channel);
-      } catch (err) {
-        // The account exists whether or not the person was told: the admin's
-        // answer says they were not, and the admin sends the link themselves.
-        log.error('an account-invited listener failed; the person was not notified by it:', { err });
-      }
-    }
-    return notified;
+  runAccountInvited(event: AccountInvitedEvent): Promise<string[]> {
+    return this.invited.run(event);
   }
 }

package/src/modules/auth/auth.service.ts

@@ -1,9 +1,9 @@
 import jwt from 'jsonwebtoken';
-import { and, eq, getTableColumns, isNotNull, isNull, sql } from 'drizzle-orm';
+import { and, eq, getTableColumns, inArray, isNotNull, isNull, sql } from 'drizzle-orm';
 import type { Database } from '../database/connection.js';
 import { users } from '../database/schema.js';
 import type { AuthUser } from '@bevel-software/platform-shared';
-import { canonicalEmail, hashEmail } from '../../shared/email-identity.js';
+import { canonicalEmail } from '../../shared/email-identity.js';
 import {
   AccountAdmissionRefusedError,
   AccountChangeRefusedError,
@@ -863,26 +863,27 @@ export class AuthService implements IAccountSwitchGuard {
   }
 
   /**
-   * Resolve a set of `authorId` hashes back to the app users that produced
-   * them. Used by the PR list to display the human who triggered each PR
-   * instead of the shared GitHub service account.
+   * The live accounts behind a set of addresses — the approvers of a change
+   * request just opened, which the workflow module hands to the deployment's
+   * notification listeners as people with accounts (`ApproverAccounts`).
    *
-   * Loads all users and hashes them in-process rather than indexing on a
-   * stored hash column — the user table is small (one row per team member)
-   * and refreshes are infrequent (PR list polls at 60s), so the cost is
-   * negligible and we avoid carrying a denormalised hash column.
+   * One indexed read through the email's blind index, never a scan of every
+   * account: this is asked on every change request opened, and a deployment
+   * is as large as it is. Switched-off accounts are left out — a person who
+   * cannot act on a request is not told of it — so a caller that needs them
+   * asks another way. Keyed by the canonical address asked for.
    */
-  async findUsersByEmailHash(
-    hashes: Set<string>,
+  async findActiveAccountsByEmail(
+    emails: readonly string[],
   ): Promise<Map<string, { id: string; email: string; name: string }>> {
     const result = new Map<string, { id: string; email: string; name: string }>();
-    if (hashes.size === 0) return result;
-    const rows = await this.db.select().from(users);
-    for (const row of rows) {
-      const h = hashEmail(row.email);
-      if (!hashes.has(h)) continue;
-      result.set(h, { id: row.id, email: row.email, name: row.name });
-    }
+    const canonical = [...new Set(emails.map((e) => canonicalEmail(e)).filter(Boolean))];
+    if (canonical.length === 0) return result;
+    const rows = await this.db
+      .select({ id: users.id, email: users.email, name: users.name })
+      .from(users)
+      .where(and(inArray(users.emailBidx, canonical), isNull(users.deactivatedAt)));
+    for (const row of rows) result.set(canonicalEmail(row.email), { id: row.id, email: row.email, name: row.name });
     return result;
   }
 

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

@@ -550,7 +550,10 @@ export const agentConnections = pgTable('agent_connections', {
  * `api_tokens`: plaintext shown only in the token response, SHA-256 hashes
  * stored, revoked-not-deleted so `last_used_at` keeps its audit value and a
  * revoked token can't be re-issued. One row per pair; refresh rotation
- * revokes the old row and inserts a new one.
+ * retires the old row (`rotated_at`) and inserts a new one. A retired row's
+ * access token still verifies until its own expiry, unless the row is then
+ * revoked: by a revoke, a sign-out, or its refresh token's one allowed replay
+ * within the reuse grace, which revokes it in the statement that admits it.
  *
  * `connection_id` names the {@link agentConnections} row the pair belongs to,
  * so every call made with the token is attributed to that agent and revoking
@@ -569,6 +572,18 @@ export const oauthTokens = pgTable('oauth_tokens', {
   expiresAt: timestamp('expires_at').notNull(),
   refreshExpiresAt: timestamp('refresh_expires_at'),
   revokedAt: timestamp('revoked_at'),
+  /**
+   * When a refresh of this row's refresh token minted its successor. Set by
+   * rotation and never by a revoke, so the two are told apart: a rotated
+   * row's access token still verifies until its own expiry, and its refresh
+   * token is honoured once more within the reuse grace (see
+   * `exchangeRefreshToken`), a replay that revokes the row — access token
+   * included — in the statement that admits it; a revoked row does neither.
+   * Null on a row whose refresh token has not been used, and on rows from
+   * before the column existed, which rotation then marks as it does any
+   * other.
+   */
+  rotatedAt: timestamp('rotated_at'),
   lastUsedAt: timestamp('last_used_at'),
   createdAt: timestamp('created_at').defaultNow().notNull(),
 }, (t) => ({
@@ -589,22 +604,30 @@ export const oauthTokens = pgTable('oauth_tokens', {
  * which agent, when" — not "what was said".
  *
  * Exactly one principal per row (the CHECK): the connection key or the agent
- * connection the call arrived through. Both cascade, so deleting a key for
- * good, revoking-then-erasing a person, or dropping a connection takes its
- * events along — the same contract the LLM-usage rows already keep.
+ * connection the call arrived through, or the knowledge-base page whose
+ * script made the call as the person viewing it (`page_path`). Key and
+ * connection cascade, so deleting a key for good, revoking-then-erasing a
+ * person, or dropping a connection takes its events along — the same contract
+ * the LLM-usage rows already keep; a page's events go with the person.
  */
 export const agentEvents = pgTable('agent_events', {
   id: uuid('id').defaultRandom().primaryKey(),
   userId: uuid('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
   keyId: uuid('key_id').references(() => externalApiKeys.id, { onDelete: 'cascade' }),
   connectionId: uuid('connection_id').references(() => agentConnections.id, { onDelete: 'cascade' }),
+  /** The knowledge-base path of the HTML page that made the call, for a page's calls; null otherwise. */
+  pagePath: text('page_path'),
   /** `capability` | `tool` | `skill`. */
   kind: text('kind').notNull(),
   /** The MCP server / `.tool` manual (catalog name) for a tool, the skill folder for a skill; null for a capability. */
   manual: text('manual'),
   /** The tool's bare name, or the skill's name. */
   name: text('name').notNull(),
-  /** `ok` | `error` | `denied` (denied: the caller's sign-in for the tool was missing, so nothing ran). */
+  /**
+   * `ok` | `error` | `denied` | `refused`. Denied: the caller's sign-in for the
+   * tool was missing, so nothing ran. Refused: the viewer answered a page's
+   * request to write with Deny, so nothing ran.
+   */
   outcome: text('outcome').notNull(),
   durationMs: integer('duration_ms'),
   at: timestamp('at').defaultNow().notNull(),
@@ -612,14 +635,15 @@ export const agentEvents = pgTable('agent_events', {
   // The two read paths: one principal's events, newest first.
   byKey: index('agent_events_by_key').on(t.keyId, t.at),
   byConnection: index('agent_events_by_connection').on(t.connectionId, t.at),
+  byPage: index('agent_events_by_page').on(t.userId, t.pagePath, t.at),
   // The retention prune, and per-user counts.
   byAt: index('agent_events_by_at').on(t.at),
   byUser: index('agent_events_by_user').on(t.userId),
   kindCheck: check('agent_events_kind', sql`${t.kind} IN ('capability', 'tool', 'skill')`),
-  outcomeCheck: check('agent_events_outcome', sql`${t.outcome} IN ('ok', 'error', 'denied')`),
+  outcomeCheck: check('agent_events_outcome', sql`${t.outcome} IN ('ok', 'error', 'denied', 'refused')`),
   principalCheck: check(
     'agent_events_principal',
-    sql`(${t.keyId} IS NULL) <> (${t.connectionId} IS NULL)`,
+    sql`num_nonnulls(${t.keyId}, ${t.connectionId}, ${t.pagePath}) = 1`,
   ),
 }));
 

package/src/modules/kb-fs/__tests__/mutex.canonical.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import { WorkspaceIdMutex, WorkspaceMutex } from '../mutex.js';
+
+/**
+ * `WorkspaceIdMutex`: a workspace id in either spelling — a route's decoded
+ * `alice/feature`, a tool's `alice%2Ffeature` — takes the one key.
+ */
+describe('WorkspaceIdMutex', () => {
+  /** A task that signals when it starts and ends only when released. */
+  const held = () => {
+    let release: () => void = () => {};
+    let started: () => void = () => {};
+    const begun = new Promise<void>((r) => { started = r; });
+    const task = () =>
+      new Promise<void>((resolve) => {
+        release = resolve;
+        started();
+      });
+    return { task, begun, release: () => release() };
+  };
+  const settled = () => new Promise<void>((r) => setImmediate(r));
+
+  it('queues the decoded and the encoded spelling of one workspace on the same key', async () => {
+    const mutex = new WorkspaceIdMutex();
+    const first = held();
+    const order: string[] = [];
+    const a = mutex.run('alice/feature', first.task).then(() => { order.push('decoded'); });
+    await first.begun;
+    const b = mutex.run('alice%2Ffeature', async () => { order.push('encoded'); });
+    await settled();
+    // The encoded spelling waits on the decoded one's reservation: nothing
+    // has run until the first is released; then both do.
+    expect(order).toEqual([]);
+    first.release();
+    await Promise.all([a, b]);
+    expect([...order].sort()).toEqual(['decoded', 'encoded']);
+  });
+
+  it('is what the plain mutex is not: two spellings, two keys, no wait', async () => {
+    const mutex = new WorkspaceMutex();
+    const first = held();
+    const order: string[] = [];
+    const a = mutex.run('alice/feature', first.task).then(() => { order.push('decoded'); });
+    await first.begun;
+    await mutex.run('alice%2Ffeature', async () => { order.push('encoded'); });
+    expect(order).toEqual(['encoded']);
+    first.release();
+    await a;
+  });
+
+  it('leaves a protected branch (no slash, one spelling) and a malformed id as they are', async () => {
+    const mutex = new WorkspaceIdMutex();
+    const seen: string[] = [];
+    await mutex.runAll(['main', 'bad%'], async () => { seen.push('ran'); });
+    expect(seen).toEqual(['ran']);
+  });
+});

package/src/modules/kb-fs/index.ts

@@ -4,5 +4,6 @@
  * workspace needs only the shape of the gate every write passes first.
  */
 export type { WriteValidator } from './locking-filesystem.js';
+export { WorkspaceMutex, WorkspaceIdMutex } from './mutex.js';
 export { readRefSha, readRevSha, type RefFileAnswer } from './ref-files.js';
 export { gitDirOf, readGitfile } from './git-dir.js';

package/src/modules/kb-fs/locking-filesystem.ts

@@ -52,6 +52,7 @@ import { PushNeedsAgentResolutionError } from '../../shared/domain-errors.js';
 import type { FileChangeNotifier } from './file-change-notifier.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import { DestinationTakenError, lstatOrNull, renameNoReplace, takenError } from '../../shared/rename-no-replace.js';
+import { linkedAncestor } from '../../shared/no-link-below.js';
 import { assertInsideRepo } from './repo-path.js';
 import { GitGuardedFilesystem } from './git-guarded-filesystem.js';
 import type { CreationGrantPlan, ICreatorAccess } from '../access-model/creator.js';
@@ -644,18 +645,8 @@ export class LockingFilesystem extends GitGuardedFilesystem {
   private async assertNoLinkBelowBase(inputPath: string): Promise<void> {
     const absolute = this.resolveAbsolutePath(inputPath);
     if (!absolute) return;
-    const base = path.resolve(this.basePath);
-    let current = path.resolve(absolute);
-    const ancestors: string[] = [];
-    while (current.startsWith(base) && current !== base) {
-      ancestors.push(current);
-      current = path.dirname(current);
-    }
-    for (const ancestor of ancestors) {
-      const stat = await lstatOrNull(ancestor);
-      if (stat?.isSymbolicLink()) {
-        throw new Error(`"${inputPath}" is reached through a link, so nothing was moved.`);
-      }
+    if ((await linkedAncestor(this.basePath, absolute)) !== null) {
+      throw new Error(`"${inputPath}" is reached through a link, so nothing was moved.`);
     }
   }
 

package/src/modules/kb-fs/mutex.ts

@@ -1,3 +1,5 @@
+import { canonicalWorkspaceId } from '../../shared/workspace-id.js';
+
 /**
  * Serializes async operations by key. Two `run(k, ...)` calls with the same key
  * execute sequentially in call order; different keys run independently.
@@ -65,3 +67,17 @@ export class WorkspaceMutex {
     }
   }
 }
+
+/**
+ * A `WorkspaceMutex` whose keys are WORKSPACE IDS, taken in their canonical
+ * spelling: a route's Express-decoded `:id` (`alice/feature`) and a tool's
+ * `alice%2Ffeature` name the same clone and must queue on the same key — two
+ * spellings would let a route's read run beside a tool's merge of the same
+ * checkout. `canonicalWorkspaceId` collapses both to the encoded form every
+ * other keyed store (the file locks, the pending commits) already uses.
+ */
+export class WorkspaceIdMutex extends WorkspaceMutex {
+  override async runAll<T>(keys: string[], fn: () => Promise<T>): Promise<T> {
+    return super.runAll(keys.map(canonicalWorkspaceId), fn);
+  }
+}