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

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

@@ -49,3 +49,8 @@ export {
 } from './tool-def.js';
 export { ToolError, hasHttpStatus, type ToolContext, type ToolHandler } from './tool.contract.js';
 export type { JsonSchema, UtcpTool } from '../tool-registry/tool.contract.js';
+export {
+  CAN_WRITE_CLAUSE,
+  defaultBranchWriteVerdicts,
+  type DefaultBranchWriteDeps,
+} from './default-branch-write.js';

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

@@ -36,8 +36,8 @@ export interface ToolHandlerOptions {
   writeScope?: boolean;
   /**
    * How this route treats `branch`, when it must differ from what its
-   * `toolDef` recorded. Only `execute_command` sets it (`own`): it falls back
-   * to an internal caller's focused branch rather than being refused.
+   * `toolDef` recorded (`own`: the handler resolves it itself rather than
+   * being refused).
    */
   branch?: BranchHandling;
 }

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

@@ -41,8 +41,8 @@ export interface ToolContext {
   sessionId?: string;
   /**
    * The branch the in-process agent's workspace is focused on, from its internal
-   * token. An internal-only workspace tool (e.g. `execute_command`) falls back to
-   * it when the model omits `branch`, so the in-app chat agent acts on its own
+   * token. A tool may fall back to it when the model omits `branch` (`list_tool_setup`
+   * reads the focused branch's setup), so the in-app chat agent acts on its own
    * workspace even on a branch-less call. Only set for `source: 'internal'`;
    * external callers must name the branch explicitly (a present-but-invalid value
    * still fails closed regardless of this).

package/src/modules/tool-registry/__tests__/tool-description-length.test.ts

@@ -15,6 +15,7 @@ import type { UtcpTool } from '../tool.contract.js';
 import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
 import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
+import { WorkerPatternMatcher } from '../../workspace/bounded-matcher.js';
 import { registerWorkflowTools } from '../../workflow/agent-tools/workflow.tools.js';
 import { registerPluginsTools } from '../../plugins/plugins.tools.js';
 import { registerSkillsTools } from '../../skills/skills.tools.js';
@@ -24,6 +25,7 @@ import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
 import { UuidSessionSink } from '../../workspace/session-sink.js';
 import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
 import { CLIENT_SHORT_CUT, TOOL_DESCRIPTION_CAP, clientVisibleLength, firstSentenceEnd } from '../description-length.js';
+import { CAN_WRITE_CLAUSE } from '../../tool-helpers/index.js';
 import {
   TOOL_PREFIX_CAP,
   sharedFileRules,
@@ -79,7 +81,7 @@ function servedMetaTools(external: readonly UtcpTool[]) {
 }
 
 /** Every tool Hexis itself registers, on both surfaces, deduplicated by name. */
-async function hexisTools(): Promise<UtcpTool[]> {
+async function hexisTools(skills: Parameters<typeof registerSkillsTools>[4] = emptySkills): Promise<UtcpTool[]> {
   const registry = new ToolRegistry();
   const router = express.Router();
   const toolAuth = ((_req, _res, next) => next()) as unknown as ToolAuth;
@@ -109,10 +111,15 @@ async function hexisTools(): Promise<UtcpTool[]> {
     // mounted on the same terms as the upload one.
     undefined,
     unused(),
+    // Starter packs and the tree walk, not needed; then the grep matcher,
+    // mounted on the same terms (it spawns no worker until a search runs).
+    undefined,
+    undefined,
+    new WorkerPatternMatcher(),
   );
   registerWorkflowTools(registry, router, toolAuth, toolHandler, kb, async () => true);
   registerPluginsTools(registry, kb);
-  registerSkillsTools(registry, router, toolAuth, toolHandler, emptySkills);
+  registerSkillsTools(registry, router, toolAuth, toolHandler, skills);
   registerToolManualsTools(registry, router, toolAuth, toolHandler, emptyManuals, {
     accessControl: unused(),
     variableStatus: unused(),
@@ -256,7 +263,6 @@ describe('every file tool opens with the guide-first sentence and carries no sha
     'move_file',
     'copy_file',
     'unzip',
-    'execute_command',
     'apply_file_upload',
   ];
 
@@ -391,3 +397,36 @@ describe('the shared rules describe the tools they name', () => {
     expect(rule.body).not.toContain('and unzip act on bytes of any kind');
   });
 });
+
+/** A realistic catalog: forty skills with names as long as real ones, so the skill tools' name lists are full. */
+const fortySkills = {
+  listSkills: async () =>
+    Array.from({ length: 40 }, (_, i) => ({
+      name: `specialist-skill-number-${i}`,
+      description: 'A skill.',
+      path: `Plugins/Everyone/specialist-skill-number-${i}`,
+    })),
+} as unknown as Parameters<typeof registerSkillsTools>[4];
+
+describe('the four tools that report canWrite say what `false` means', () => {
+  const FOUR = ['list_skills', 'get_skill', 'list_files', 'read_file'];
+
+  it.each([
+    ['an empty skill catalog', emptySkills],
+    ['a forty-skill catalog', fortySkills],
+  ])('carries the clause within the caps, with %s', async (_label, skills) => {
+    const tools = (await hexisTools(skills)).filter((t) => FOUR.includes(t.name));
+    expect(tools.map((t) => t.name).sort()).toEqual([...FOUR].sort());
+    for (const tool of tools) {
+      expect(tool.description, tool.name).toContain(CAN_WRITE_CLAUSE);
+      expect(clientVisibleLength(tool), tool.name).toBeLessThanOrEqual(TOOL_DESCRIPTION_CAP);
+      expect(firstSentenceEnd(tool.description!), tool.name).toBeLessThanOrEqual(CLIENT_SHORT_CUT);
+    }
+  });
+
+  it('keeps the clause ahead of the skill names a client may cut from the end', async () => {
+    for (const tool of (await hexisTools(fortySkills)).filter((t) => t.name === 'list_skills' || t.name === 'get_skill')) {
+      expect(tool.description!.indexOf(CAN_WRITE_CLAUSE), tool.name).toBeLessThan(tool.description!.indexOf('specialist-skill-number-0'));
+    }
+  });
+});

package/src/modules/workflow/__tests__/fake-file-lock-db.ts

@@ -66,10 +66,21 @@ function comparable(value: unknown): string {
 
 const dialect = new PgDialect();
 const TERM = /"file_locks"\."(\w+)"\s*(<=|>=|=|<|>)\s*\$(\d+)/g;
+/** `inArray`: `"file_locks"."col" in ($1, $2)`. */
+const IN_TERM = /"file_locks"\."(\w+)"\s+in\s*\(((?:\s*\$\d+\s*,?)+)\)/g;
 
 function predicateFor(condition: SQL | undefined): (row: LockRow) => boolean {
   if (!condition) return () => true;
-  const { sql: text, params } = dialect.sqlToQuery(condition);
+  const { sql: rawText, params } = dialect.sqlToQuery(condition);
+  const sets = [...rawText.matchAll(IN_TERM)].map(([, column, list]) => {
+    const field = FIELD_FOR_COLUMN[column];
+    if (!field) {
+      throw new Error(`fake file_locks db has no field mapped for column "${column}": ${rawText}`);
+    }
+    const values = [...list.matchAll(/\$(\d+)/g)].map(([, index]) => comparable(params[Number(index) - 1]));
+    return { field, values };
+  });
+  const text = rawText.replace(IN_TERM, '');
   const terms = [...text.matchAll(TERM)].map(([, column, operator, index]) => {
     const field = FIELD_FOR_COLUMN[column];
     // A column the regex matched but FIELD_FOR_COLUMN does not know would
@@ -92,7 +103,7 @@ function predicateFor(condition: SQL | undefined): (row: LockRow) => boolean {
   return (row) =>
     terms.every(({ field, operator, value }) =>
       COMPARISONS[operator](comparable(row[field]), value),
-    );
+    ) && sets.every(({ field, values }) => values.includes(comparable(row[field])));
 }
 
 function keyOf(row: Pick<LockRow, 'workspaceId' | 'branch' | 'path'>): string {

package/src/modules/workflow/__tests__/workflow.routes.lock-path.test.ts

@@ -18,6 +18,7 @@ import { WorkflowService } from '../workflow.service.js';
 import { createWorkflowRoutes } from '../workflow.routes.js';
 import { makeFakeLockDb, type FakeLockDb } from './fake-file-lock-db.js';
 import { openChangeGate } from '../../../__tests__/open-change-gate.js';
+import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 
 /**
  * The lock routes over the real service and a real lock store: acquire,
@@ -53,6 +54,10 @@ interface Harness {
   fake: FakeLockDb;
   enqueue: ReturnType<typeof vi.fn>;
   commitFile: ReturnType<typeof vi.fn>;
+  /** The service behind the routes, for the in-process callers (an agent's edits) that use it directly. */
+  workflow: IWorkflowService;
+  /** The read rule the status read consults; every file is readable unless a test says otherwise. */
+  canRead: ReturnType<typeof vi.fn>;
   /** Whose credentials the next request carries. */
   actAs: (user: AuthUser) => void;
 }
@@ -85,6 +90,7 @@ async function makeHarness(): Promise<Harness> {
     events,
   );
 
+  const canRead = vi.fn(async () => true);
   let current = ALICE;
   const authService = {
     getUserById: vi.fn(async (id: string) => (id === BOB.id ? BOB : ALICE)),
@@ -103,7 +109,7 @@ async function makeHarness(): Promise<Harness> {
       {} as unknown as WorkspaceService,
       authService,
       events,
-      {} as unknown as IAccessControl,
+      { canRead } as unknown as IAccessControl,
       KB,
     ),
   );
@@ -117,6 +123,8 @@ async function makeHarness(): Promise<Harness> {
     fake,
     enqueue,
     commitFile,
+    workflow: workflow as unknown as IWorkflowService,
+    canRead,
     actAs: (user) => {
       current = user;
     },
@@ -225,6 +233,16 @@ describe('lock routes coordinate on one file identity', () => {
     });
   });
 
+  it('stores a lock taken through the route under the encoded workspace id the deletion gate asks with', async () => {
+    // Express hands the route the decoded `:id`; the deletion paths and an
+    // agent's edits ask with `workspaceIdForBranch(branch)`, the encoded one.
+    await acquire(CANONICAL);
+
+    expect(h.fake.rows().map((r) => r.workspaceId)).toEqual([WS]);
+    expect((await release(CANONICAL)).status).toBe(200);
+    expect(h.fake.rows()).toEqual([]);
+  });
+
   it('reads the status of a raw spelling after a canonical acquire', async () => {
     await acquire(CANONICAL);
 
@@ -304,3 +322,152 @@ describe('lock routes coordinate on one file identity', () => {
     });
   });
 });
+
+/**
+ * A slashed branch's workspace has two spellings: the lock routes get the
+ * `:id` Express decoded (`feat/x`), while an agent's edits and the deletion
+ * gate use the encoded id (`feat%2Fx`). They are one workspace — one clone,
+ * one branch — so they are one lock: a file a person holds in the app is held
+ * against an agent's edit too, and the other way round.
+ */
+describe('lock routes coordinate on one workspace identity', () => {
+  let h: Harness;
+
+  beforeEach(async () => {
+    h = await makeHarness();
+  });
+  afterEach(async () => {
+    await close(h.server);
+  });
+
+  const url = (suffix: string) => `${h.baseUrl}/api/workspace/${WS}/workflow/locks${suffix}`;
+  const send = (method: string, suffix: string, body: unknown) =>
+    fetch(url(suffix), {
+      method,
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+  const acquire = () => send('POST', '', { branch: BRANCH, path: CANONICAL });
+  const release = () => send('DELETE', '', { branch: BRANCH, path: CANONICAL });
+  const heartbeat = () => send('POST', '/heartbeat', { branch: BRANCH, path: CANONICAL });
+  const status = () =>
+    fetch(`${url('')}?branch=${encodeURIComponent(BRANCH)}&path=${encodeURIComponent(CANONICAL)}`);
+
+  it("holds a file taken in the app against an agent's edit, and frees it on release", async () => {
+    expect(await (await acquire()).json()).toMatchObject({ acquired: true });
+
+    await expect(h.workflow.acquireLock(workspaceIdForBranch(BRANCH), BRANCH, CANONICAL, BOB)).resolves.toMatchObject({
+      acquired: false,
+      lock: { holderUserId: ALICE.id },
+    });
+
+    expect((await release()).status).toBe(200);
+    await expect(h.workflow.acquireLock(workspaceIdForBranch(BRANCH), BRANCH, CANONICAL, BOB)).resolves.toMatchObject({
+      acquired: true,
+    });
+  });
+
+  it("holds a file an agent took against the app, which reads its status", async () => {
+    await h.workflow.acquireLock(workspaceIdForBranch(BRANCH), BRANCH, CANONICAL, ALICE);
+
+    expect(await (await status()).json()).toMatchObject({ lock: { holderUserId: ALICE.id } });
+    h.actAs(BOB);
+    expect(await (await acquire()).json()).toMatchObject({ acquired: false, lock: { holderUserId: ALICE.id } });
+    expect(h.fake.rows()).toHaveLength(1);
+  });
+
+  it('answers a caller who may not read the file the same refusal whether or not anyone holds it', async () => {
+    // An agent's lock is found from the app's spelling, so the status read
+    // must not name its holder to someone the file is hidden from.
+    h.canRead.mockImplementation(async (_ws: string, email: string) => email !== BOB.email);
+    await h.workflow.acquireLock(workspaceIdForBranch(BRANCH), BRANCH, CANONICAL, ALICE);
+    h.actAs(BOB);
+
+    const rawStatus = () =>
+      fetch(`${url('')}?branch=${encodeURIComponent(BRANCH)}&path=${encodeURIComponent(RAW)}`);
+    const held = await status();
+    const heldRaw = await rawStatus();
+    expect(held.status).toBe(403);
+    expect(heldRaw.status).toBe(403);
+    const heldBody = await held.json();
+    expect(JSON.stringify(heldBody)).not.toContain(ALICE.id);
+
+    h.actAs(ALICE);
+    expect((await release()).status).toBe(200);
+    h.actAs(BOB);
+    const free = await status();
+    expect(free.status).toBe(403);
+    expect(await free.json()).toEqual(heldBody);
+    // The raw spelling is judged as the file it names, not let through as non-KB.
+    expect(h.canRead).toHaveBeenCalledWith(BRANCH, BOB.email, 'x/a.md');
+  });
+
+  it('judges a path without the KB prefix as the repository file it names', async () => {
+    // The git layer reads `x/a.md` as `${KB}/x/a.md`, so the alias is no way
+    // round the read rule.
+    h.canRead.mockImplementation(async (_ws: string, email: string) => email !== BOB.email);
+    h.actAs(BOB);
+
+    const alias = await fetch(`${url('')}?branch=${encodeURIComponent(BRANCH)}&path=${encodeURIComponent('x/a.md')}`);
+
+    expect(alias.status).toBe(403);
+    expect(h.canRead).toHaveBeenCalledWith(BRANCH, BOB.email, 'x/a.md');
+  });
+
+  it('leaves an unslashed workspace id as it is', async () => {
+    const res = await fetch(`${h.baseUrl}/api/workspace/main/workflow/locks`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ branch: 'main', path: CANONICAL }),
+    });
+    expect(res.status).toBe(200);
+    expect(h.fake.rows().map((r) => r.workspaceId)).toEqual(['main']);
+  });
+
+  describe('a lock the previous version left under the decoded id', () => {
+    /** A row as the previous version wrote it through these routes. */
+    const seedLegacy = (expiresInMs: number) => {
+      const now = Date.now();
+      h.fake.seed({
+        workspaceId: BRANCH,
+        branch: BRANCH,
+        path: CANONICAL,
+        holderUserId: ALICE.id,
+        holderName: ALICE.name,
+        mode: 'edit',
+        acquiredAt: new Date(now - 1_000),
+        lastHeartbeatAt: new Date(now - 1_000),
+        expiresAt: new Date(now + expiresInMs),
+      });
+    };
+
+    it("while live: the app reads it, another editor and an agent's edit are refused, its holder heartbeats and releases it", async () => {
+      seedLegacy(30_000);
+
+      expect(await (await status()).json()).toMatchObject({ lock: { holderUserId: ALICE.id } });
+      h.actAs(BOB);
+      expect(await (await acquire()).json()).toMatchObject({ acquired: false, lock: { holderUserId: ALICE.id } });
+      await expect(h.workflow.acquireLock(workspaceIdForBranch(BRANCH), BRANCH, CANONICAL, BOB)).resolves.toMatchObject({
+        acquired: false,
+      });
+      // No second row was written beside it.
+      expect(h.fake.rows().map((r) => r.workspaceId)).toEqual([BRANCH]);
+
+      h.actAs(ALICE);
+      const beat = await heartbeat();
+      expect(beat.status).toBe(200);
+      expect(new Date((await beat.json()).expiresAt).getTime()).toBeGreaterThan(Date.now() + 30_000);
+      expect(await (await release()).json()).toEqual({ queued: true });
+      expect(h.fake.rows()).toEqual([]);
+    });
+
+    it('once expired: it holds nothing, and the file is taken under the encoded id', async () => {
+      seedLegacy(-1_000);
+
+      expect(await (await status()).json()).toMatchObject({ lock: null });
+      h.actAs(BOB);
+      expect(await (await acquire()).json()).toMatchObject({ acquired: true, lock: { holderUserId: BOB.id } });
+      expect(h.fake.rows().map((r) => r.workspaceId)).toEqual([WS]);
+    });
+  });
+});

package/src/modules/workflow/__tests__/workflow.service.delete-branch.test.ts

@@ -20,6 +20,7 @@ import { WorkflowHooks } from '../workflow-hooks.js';
 import { WorkflowService } from '../workflow.service.js';
 import type { WorkflowEventBus } from '../event-bus.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
+import { makeFakeLockDb } from './fake-file-lock-db.js';
 import {
   BranchAuthorshipError,
   BranchDeleteBlockedError,
@@ -112,7 +113,6 @@ interface Harness {
   };
   fetch: ReturnType<typeof vi.fn>;
   deleted: string[];
-  fileLocks: FileLockService;
   /** What the service announced to connected tabs. */
   emitted: { kind: string; number?: number }[];
   hasAnyActive: MockInstance<FileLockService['hasAnyActive']>;
@@ -137,6 +137,8 @@ function harness(opts: {
   changes?: Record<string, string[] | 'error'>;
   /** Branches whose deletion fails at the host (the leased push is refused). */
   deleteFails?: string[];
+  /** Hold locks in a real (in-memory) lock store instead of answering from `savesLanding`. */
+  realLocks?: boolean;
 }): Harness {
   const deleted: string[] = [];
   const emitted: { kind: string; number?: number }[] = [];
@@ -175,8 +177,10 @@ function harness(opts: {
   const landing = new Set((opts.savesLanding ?? []).map(workspaceIdForBranch));
   const queued = new Set((opts.commitsQueued ?? []).map(workspaceIdForBranch));
   // The real service, for its gate on acquiring; what is held is mocked.
-  const fileLocks = new FileLockService({} as Database);
-  const hasAnyActive = vi.spyOn(fileLocks, 'hasAnyActive').mockImplementation(async (ws: string) => landing.has(ws));
+  const fileLocks = new FileLockService(opts.realLocks ? makeFakeLockDb().db : ({} as Database));
+  const hasAnyActive = opts.realLocks
+    ? vi.spyOn(fileLocks, 'hasAnyActive')
+    : vi.spyOn(fileLocks, 'hasAnyActive').mockImplementation(async (ws: string) => landing.has(ws));
   const svc = new WorkflowService(
     fakeDb(rows),
     git as unknown as GitService,
@@ -209,7 +213,7 @@ function harness(opts: {
     openChangeGate(),
     { emit: (e: { kind: string; number?: number }) => void emitted.push(e) } as unknown as WorkflowEventBus,
   );
-  return { svc, git, fetch, deleted, fileLocks, emitted, hasAnyActive };
+  return { svc, git, fetch, deleted, emitted, hasAnyActive };
 }
 
 const merged = (number: number, source: string, sha: string | null): CrRow => ({
@@ -352,7 +356,7 @@ describe('deleteBranchChecked — an agent deletes a branch', () => {
     h.hasAnyActive.mockResolvedValue(false);
     let during: unknown = null;
     h.git.deleteBranch.mockImplementationOnce(async () => {
-      during = await h.fileLocks.acquire(workspaceIdForBranch('ali/draft'), 'ali/draft', 'KnowledgeBase/f.md', BOB).catch((e: unknown) => e);
+      during = await h.svc.acquireLock(workspaceIdForBranch('ali/draft'), 'ali/draft', 'KnowledgeBase/f.md', BOB).catch((e: unknown) => e);
       return { lastCommit: 'a1' };
     });
     await h.svc.deleteBranchChecked(ADMIN, 'ali/draft');
@@ -560,6 +564,46 @@ describe('a change request that proposes nothing never blocks a deletion', () =>
     expect(rows.map((r) => r.state)).toEqual(['open', 'open']);
   });
 
+  it('names the person by id, never by email address, on the close, reopen and deletion lines', async () => {
+    // Log lines carry no email addresses: who acted is the user's id.
+    const rows = [open(21, 'ali/sync', DEFAULT)];
+    const h = harness({
+      rows,
+      branches: { 'ali/sync': clean('s1'), 'ali/old-draft': clean('a1') },
+      changes: { 'ali/sync': [] },
+      deleteFails: ['ali/sync'],
+    });
+    const lines: string[] = [];
+    const spy = vi.spyOn(console, 'log').mockImplementation((line: unknown) => void lines.push(String(line)));
+    try {
+      await expect(h.svc.deleteBranchChecked(ADMIN, 'ali/sync')).rejects.toThrow(/stale info/);
+      await h.svc.deleteBranchChecked(ADMIN, 'ali/old-draft');
+    } finally {
+      spy.mockRestore();
+    }
+    const pick = (needle: string) => lines.filter((l) => l.includes(needle));
+    expect(pick('closed change request #21')).toEqual([expect.stringContaining(' by u-ana: ')]);
+    expect(pick('reopened change request #21')).toEqual([expect.stringContaining(' for u-ana: ')]);
+    expect(pick('branch deleted by')).toEqual(['[workflow] branch deleted by u-ana: "ali/old-draft" at a1']);
+    for (const line of lines) expect(line).not.toContain('@');
+  });
+
+  it("names the person by id on the close made when a request's page is opened", async () => {
+    const rows = [open(23, 'ali/page', DEFAULT)];
+    const h = harness({ rows, branches: { 'ali/page': clean('p1') }, changes: { 'ali/page': [] } });
+    const lines: string[] = [];
+    const spy = vi.spyOn(console, 'log').mockImplementation((line: unknown) => void lines.push(String(line)));
+    try {
+      await expect(h.svc.closeEmptyChangeRequest(23, BOB)).resolves.toBe(true);
+    } finally {
+      spy.mockRestore();
+    }
+    expect(lines.filter((l) => l.includes('closed change request #23'))).toEqual([
+      expect.stringContaining(' by u-bob: '),
+    ]);
+    for (const line of lines) expect(line).not.toContain('@');
+  });
+
   it('a request the caller may not see is not in the preview at all, and is refused on without its number or link', async () => {
     // #21 is empty and #25 live; the caller can see neither.
     const rows = [open(21, 'bob/sync', DEFAULT), open(25, 'ali/secret', 'bob/sync')];
@@ -656,7 +700,7 @@ describe('closeEmptyOpenChangeRequests — the background close', () => {
     const h = harness({ rows, branches: { 'ali/empty': clean('e1') }, changes: { 'ali/empty': [] } });
     let during: unknown = null;
     h.git.deleteBranch.mockImplementationOnce(async () => {
-      during = await h.fileLocks.acquire(workspaceIdForBranch('ali/empty'), 'ali/empty', 'KnowledgeBase/f.md', BOB).catch((e: unknown) => e);
+      during = await h.svc.acquireLock(workspaceIdForBranch('ali/empty'), 'ali/empty', 'KnowledgeBase/f.md', BOB).catch((e: unknown) => e);
       return { lastCommit: 'e1' };
     });
     await h.svc.closeEmptyOpenChangeRequests();
@@ -902,6 +946,58 @@ const GIT_ENV = {
 const git = async (cwd: string, args: string[]) =>
   (await execFileAsync('git', args, { cwd, env: GIT_ENV })).stdout.trim();
 
+/**
+ * A file held through the app: the lock route hands the service the `:id`
+ * Express decoded, so a slashed branch's workspace arrives as `ali/draft`,
+ * not the `ali%2Fdraft` the deletion paths ask with. Over a real lock store,
+ * every deletion path has to see that hold.
+ */
+describe('a file held through the app on a slashed branch', () => {
+  const holdAsTheRouteDoes = (h: Harness, branch: string) =>
+    h.svc.acquireLock(branch, branch, 'KnowledgeBase/f.md', BOB);
+
+  it('refuses the agent delete, with or without discardUnmerged', async () => {
+    const h = harness({ realLocks: true, branches: { 'ali/draft': { exists: true, lastCommit: 'a3', unmergedCommits: 1 } } });
+    await expect(holdAsTheRouteDoes(h, 'ali/draft')).resolves.toMatchObject({ acquired: true });
+    for (const discardUnmerged of [false, true]) {
+      const err = await refusal(h.svc.deleteBranchChecked(ADMIN, 'ali/draft', { discardUnmerged }));
+      expect((err as BranchDeleteBlockedError).payload).toMatchObject({ reason: 'saves-landing' });
+    }
+    expect(h.deleted).toEqual([]);
+  });
+
+  it('keeps an empty request into the branch being deleted open, and refuses on it', async () => {
+    const rows = [open(22, 'ali/feature', 'ali/sync')];
+    const h = harness({ realLocks: true, rows, branches: { 'ali/sync': clean('s1') }, changes: { 'ali/feature': [] } });
+    await holdAsTheRouteDoes(h, 'ali/feature');
+    const err = await refusal(h.svc.deleteBranchChecked(ADMIN, 'ali/sync'));
+    expect((err as BranchDeleteBlockedError).payload).toMatchObject({ reason: 'open-change-request', number: 22 });
+    expect(rows[0]!.state).toBe('open');
+    expect(h.deleted).toEqual([]);
+  });
+
+  it('the background close leaves the request open and its source branch in place', async () => {
+    const rows = [open(31, 'ali/saving', DEFAULT)];
+    const h = harness({ realLocks: true, rows, admins: [], branches: { 'ali/saving': clean('e1') }, changes: { 'ali/saving': [] } });
+    await holdAsTheRouteDoes(h, 'ali/saving');
+    await expect(h.svc.closeEmptyOpenChangeRequests()).resolves.toBe(0);
+    expect(rows[0]!.state).toBe('open');
+    expect(h.deleted).toEqual([]);
+  });
+
+  it('the leftover cleanup leaves the branch in place', async () => {
+    const h = harness({
+      realLocks: true,
+      rows: [merged(9, 'ali/saving', 'm9')],
+      branches: { 'ali/saving': clean('t9') },
+      ancestry: [['t9', 'm9']],
+    });
+    await holdAsTheRouteDoes(h, 'ali/saving');
+    await expect(h.svc.retireLeftoverMergedBranches()).resolves.toBe(0);
+    expect(h.deleted).toEqual([]);
+  });
+});
+
 describe('deleteBranchChecked over real git — a delete made from another workspace', () => {
   let root: string;
   beforeEach(async () => {