@bevel-software/platform-core-backend 0.26.0 → 0.27.0

package/src/modules/tool-manuals/tool-manuals.tools.ts

@@ -3,6 +3,7 @@ import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js'
 import type { KbContext } from '../../shared/kb-context.js';
 import type { ToolContext } from '../tool-helpers/tool.contract.js';
 import { toolDef } from '../tool-helpers/tool-def.js';
+import { declareRouteTool } from '../tool-helpers/route-tool-schemas.js';
 import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
@@ -54,6 +55,11 @@ export function registerToolManualsTools(
 ): void {
   registry.registerExternalTool((ctx) => buildListLocalToolsDef(toolManualService, ctx.userEmail));
   registry.registerInternalTool((ctx) => buildListLocalToolsDef(toolManualService, ctx.userEmail));
+  // The def above is built per catalog listing (its description names the
+  // tools configured for THIS caller), so declare the arguments here as well:
+  // a direct REST call that lands before the first listing must be checked
+  // against them too.
+  declareRouteTool('list_local_tools', LIST_LOCAL_TOOLS_INPUTS);
 
   router.post(
     '/agent/tools/list_local_tools',
@@ -79,13 +85,14 @@ export function registerToolManualsTools(
     // answers and the four things an agent cannot read off a field.
     //
     // It sits a few characters under `TOOL_DESCRIPTION_CAP` WITH the guide-first
-    // sentence the registry puts in front of it (`tool-registry/guide-first.ts`),
+    // sentence the registry puts in front of it (`tool-registry/guide-first.ts`)
+    // and the `Call:` line generated ahead of everything,
     // which is why every sentence here is the short form: the `hiddenTools`
     // clause and that opener both came out of the same budget, and what a
     // hidden tool's entry CONTAINS is on the field below rather than here.
     description:
-      'Configuration status of every `.tool` the current user can access: what each tool needs set up and what is ' +
-      'already configured, as `{ tools, invalid, onBranchOnly, note? }`. Scoped to the CALLER: a `.tool` it cannot ' +
+      'Configuration status of every `.tool` the current user can access: what each needs set up and what is ' +
+      'configured, as `{ tools, invalid, onBranchOnly, note? }`. Scoped to the CALLER: a `.tool` it cannot ' +
       'READ is absent, and every flag is the caller\'s own. ' +
       'Secret VALUES are never returned and can never be set through a tool: an admin enters them in the tool ' +
       'editor; users sign in on /connect. ' +
@@ -96,7 +103,7 @@ export function registerToolManualsTools(
       'The listing is the RELEASED catalog, built from the default branch only: a server or `.tool` you declared on a ' +
       'draft is not listed, callable or signed-in-able until it is merged. Pass `branch` (the draft you wrote the ' +
       'declaration on) and `onBranchOnly` names every tool declared there that the default branch does not serve ' +
-      'yet — open a change request and ask the user to merge it in the app to activate it.',
+      'yet — open a change request and ask the user to merge it.',
     path: '/api/agent/tools/list_tool_setup',
     inputs: {
       type: 'object',
@@ -303,6 +310,9 @@ async function localToolsLine(svc: IToolManualService, userEmail?: string): Prom
   return `Local-only tools configured for you: ${tools.map((t) => `\`${t.name}\``).join(', ')}.`;
 }
 
+/** `list_local_tools` takes nothing; a const so the route and the def share one declaration. */
+const LIST_LOCAL_TOOLS_INPUTS = { type: 'object' as const, properties: {}, additionalProperties: false };
+
 async function buildListLocalToolsDef(svc: IToolManualService, userEmail?: string): Promise<UtcpTool> {
   return toolDef({
     name: 'list_local_tools',
@@ -318,7 +328,7 @@ async function buildListLocalToolsDef(svc: IToolManualService, userEmail?: strin
       'setup by hand. ' +
       (await localToolsLine(svc, userEmail)),
     path: '/api/agent/tools/list_local_tools',
-    inputs: { type: 'object', properties: {}, additionalProperties: false },
+    inputs: LIST_LOCAL_TOOLS_INPUTS,
     outputs: {
       type: 'object',
       properties: {

package/src/modules/tool-registry/__tests__/own-tool-schemas.test.ts

@@ -9,6 +9,7 @@ import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
 import { registerSkillsTools } from '../../skills/skills.tools.js';
 import { registerPluginsTools } from '../../plugins/plugins.tools.js';
 import { registerToolManualsTools } from '../../tool-manuals/tool-manuals.tools.js';
+import { registerEmbedTools } from '../../embed/embed.tools.js';
 import { registerAgentGuideTool } from '../../agent-guide/agent-guide.tools.js';
 import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
@@ -58,7 +59,7 @@ const CORE_SERVER_SOURCE = new URL('../../../core/create-core-server.ts', import
 const MODULES: ReadonlyArray<{ name: string; register: (registry: ToolRegistry) => void }> = [
   {
     name: 'registerWorkflowTools',
-    register: (registry) => registerWorkflowTools(registry, express.Router(), pass, handler, testKbContext()),
+    register: (registry) => registerWorkflowTools(registry, express.Router(), pass, handler, testKbContext(), async () => true),
   },
   {
     name: 'registerChangeRequestReadTools',
@@ -93,6 +94,18 @@ const MODULES: ReadonlyArray<{ name: string; register: (registry: ToolRegistry)
     register: (registry) => registerSkillsTools(registry, express.Router(), pass, handler, nothing),
   },
   { name: 'registerPluginsTools', register: (registry) => registerPluginsTools(registry, testKbContext()) },
+  {
+    name: 'registerEmbedTools',
+    register: (registry) =>
+      registerEmbedTools(registry, express.Router(), pass, handler, {
+        embedService: nothing,
+        kb: testKbContext(),
+        readForTool: nothing,
+        canBeReached: () => true,
+        appUrlFor: (repoRelative) => `https://example.test/workspace/main/knowledge-base/${repoRelative}`,
+        notes: new ToolDescriptionNotes(),
+      }),
+  },
   {
     name: 'registerToolManualsTools',
     register: (registry) =>

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

@@ -4,7 +4,9 @@ import {
   CALL_TOOL_CHAIN_NAME,
   CHAIN_FAILURES_RULE,
   CHAIN_LARGE_RESULTS_RULE,
+  callLine,
   codeModeMetaTools,
+  splitCallLine,
 } from '@bevel-software/platform-mcp-core';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 import { EXTERNAL_KB_MANUAL_NAME } from '../../tool-manuals/tool-manuals.contract.js';
@@ -103,8 +105,12 @@ async function hexisTools(): Promise<UtcpTool[]> {
     // every real composition supplies one: without it they would be the two
     // descriptions this suite never measured.
     unused(),
+    // The guide reader, not needed to build defs; then the download store,
+    // mounted on the same terms as the upload one.
+    undefined,
+    unused(),
   );
-  registerWorkflowTools(registry, router, toolAuth, toolHandler, kb);
+  registerWorkflowTools(registry, router, toolAuth, toolHandler, kb, async () => true);
   registerPluginsTools(registry, kb);
   registerSkillsTools(registry, router, toolAuth, toolHandler, emptySkills);
   registerToolManualsTools(registry, router, toolAuth, toolHandler, emptyManuals, {
@@ -170,8 +176,10 @@ describe('no Hexis tool description is long enough to be cut', () => {
     // ONE predicate for both halves, so no description falls between them: a
     // tool whose own description is empty is served the sentence alone, and
     // one with text after it has whitespace between — not `here.Read`.
+    // Behind the `Call:` line, when the description already carries one (the
+    // meta-tools are built with theirs): that line comes first on every tool.
     const opensWithGuide = (t: UtcpTool): boolean => {
-      const description = t.description ?? '';
+      const description = splitCallLine(t.description ?? '').rest;
       if (description === GUIDE_FIRST_SENTENCE) return true;
       return description.startsWith(GUIDE_FIRST_SENTENCE) && /^\s/.test(description.slice(GUIDE_FIRST_SENTENCE.length));
     };
@@ -202,12 +210,15 @@ describe('no Hexis tool description is long enough to be cut', () => {
   it('fails, naming the tool, when a paragraph takes a description over the cap', () => {
     const padded = { name: 'write_file', description: 'x'.repeat(TOOL_DESCRIPTION_CAP + 1) } as UtcpTool;
     expect(clientVisibleLength(padded)).toBeGreaterThan(TOOL_DESCRIPTION_CAP);
-    // A tool with no description at all is not over the cap.
-    expect(clientVisibleLength({ name: 'nothing' } as UtcpTool)).toBe(0);
-    // Unless it is a PREFIXED one: the prefix is sent on its own then (no
-    // description, so no blank line either), and that text is what the client
-    // was handed. Measuring it as nothing would hide the only thing it got.
-    expect(clientVisibleLength({ name: 'read_file' } as UtcpTool)).toBe(TOOL_PREFIX_CAP);
+    // A tool with no description at all is handed its `Call:` line alone —
+    // the example counts toward the cap like any other text a client gets.
+    const nothingCall = callLine(`${EXTERNAL_KB_MANUAL_NAME}.nothing`, undefined);
+    expect(clientVisibleLength({ name: 'nothing' } as UtcpTool)).toBe(nothingCall.length);
+    // A PREFIXED one is handed the prefix too, behind the line (no
+    // description, so no blank line after the prefix), and that text is what
+    // the client was handed. Measuring it as nothing would hide what it got.
+    const readCall = callLine(`${EXTERNAL_KB_MANUAL_NAME}.read_file`, undefined);
+    expect(clientVisibleLength({ name: 'read_file' } as UtcpTool)).toBe(readCall.length + 2 + TOOL_PREFIX_CAP);
   });
 
   it('measures the catalog, which is what a client lists — and says what is outside it', async () => {
@@ -292,13 +303,15 @@ describe('the shared rules describe the tools they name', () => {
     // to the rules. Composed at the mount, because `mcp-core` builds the
     // constant without knowing where this deployment states them.
     const served = (await hexisTools()).find((t) => t.name === CALL_TOOL_CHAIN_NAME)!;
-    expect(served.description!.startsWith(`${GUIDE_FIRST_SENTENCE} `)).toBe(true);
+    // Behind its `Call:` line, which is the first line of every description.
+    expect(served.description!.startsWith('Call: call_tool_chain(')).toBe(true);
+    expect(splitCallLine(served.description!).rest.startsWith(`${GUIDE_FIRST_SENTENCE} `)).toBe(true);
     expect(served.description!.split(GUIDE_FIRST_SENTENCE)).toHaveLength(2);
     expect(served.description!.trimEnd().endsWith('.')).toBe(true);
     expect(clientVisibleLength(served)).toBeLessThanOrEqual(TOOL_DESCRIPTION_CAP);
     // The other two open the same way: the guide comes before the registry too.
     for (const tool of servedMetaTools([]).filter((t) => t.name !== CALL_TOOL_CHAIN_NAME)) {
-      expect(tool.description!.startsWith(`${GUIDE_FIRST_SENTENCE} `), tool.name).toBe(true);
+      expect(splitCallLine(tool.description!).rest.startsWith(`${GUIDE_FIRST_SENTENCE} `), tool.name).toBe(true);
     }
   });
 

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

@@ -11,8 +11,10 @@
  * what makes the cap below reachable rather than aspirational.
  */
 
+import { callLine, splitCallLine } from '@bevel-software/platform-mcp-core';
 import { TOOL_PREFIX_CAP } from '@bevel-software/platform-shared';
 import { PREFIXED_TOOLS } from '../agent-instructions/compose.js';
+import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/tool-manuals.contract.js';
 import { GUIDE_FIRST_SENTENCE } from './guide-first.js';
 import type { UtcpTool } from './tool.contract.js';
 
@@ -61,6 +63,25 @@ export const TOOL_DESCRIPTION_CAP = 1_200;
  */
 export const CLIENT_SHORT_CUT = 500;
 
+/** What these measurements read of a tool: its name, its text and the schema its `Call:` line is generated from. */
+export type MeasuredTool = Pick<UtcpTool, 'name' | 'description'> & { inputs?: unknown };
+
+/**
+ * The `Call:` line a client is handed ahead of everything else, and the blank
+ * line after it — counted, because it is part of what a client cuts. Taken
+ * from the description when it already opens with one (a meta-tool is built
+ * with its line), generated from the tool's inputs under the namespace the
+ * hosted endpoint serves otherwise, as mcp-core's `withCallExample` does at
+ * listing time. The rest of the description comes back beside it.
+ */
+function splitServedCallLine(tool: MeasuredTool): { callChars: number; rest: string } {
+  const { call, rest } = splitCallLine(tool.description ?? '');
+  const line = call ?? callLine(`${EXTERNAL_KB_MANUAL_NAME}.${tool.name}`, tool.inputs);
+  // The blank line after it only when something follows it.
+  const followed = rest !== '' || PREFIXED_TOOLS.has(tool.name);
+  return { callChars: line.length + (followed ? 2 : 0), rest };
+}
+
 /**
  * Where the tool's OWN opening sentence ends in the text a client is handed:
  * the purpose prefix counted at its cap, as in {@link clientVisibleLength},
@@ -71,9 +92,9 @@ export const CLIENT_SHORT_CUT = 500;
  * A description with no sentence-ending punctuation counts whole — the honest
  * answer for text that never finishes a sentence.
  */
-export function firstSentenceEnd(tool: Pick<UtcpTool, 'name' | 'description'>): number {
-  const prefix = PREFIXED_TOOLS.has(tool.name) ? TOOL_PREFIX_CAP + 2 : 0;
-  const description = tool.description ?? '';
+export function firstSentenceEnd(tool: MeasuredTool): number {
+  const { callChars, rest: description } = splitServedCallLine(tool);
+  const prefix = callChars + (PREFIXED_TOOLS.has(tool.name) ? TOOL_PREFIX_CAP + 2 : 0);
   if (description === '') return prefix;
   // The opener and whatever whitespace follows it: `guideFirstDescription`
   // joins with one space, and leaves a description that already opens with
@@ -97,13 +118,19 @@ export function firstSentenceEnd(tool: Pick<UtcpTool, 'name' | 'description'>):
  * The guide-first sentence every listed tool opens with is already in the
  * description the registry lists, so it is measured as the text it is.
  */
-export function clientVisibleLength(tool: Pick<UtcpTool, 'name' | 'description'>): number {
-  const own = tool.description?.length ?? 0;
+export function clientVisibleLength(tool: MeasuredTool): number {
+  const { callChars, rest } = splitServedCallLine(tool);
+  return callChars + ownVisibleLength(tool.name, rest);
+}
+
+/** {@link clientVisibleLength} without the `Call:` line: the purpose prefix and the tool's own text. */
+function ownVisibleLength(name: string, description: string): number {
+  const own = description.length;
   // A prefixed tool with no description of its own is still handed the prefix,
   // and nothing else — `prefixToolDescription` sends the prefix alone, with no
   // blank line after it. Measuring that as zero would under-report the only
   // text the client got.
-  if (own === 0) return PREFIXED_TOOLS.has(tool.name) ? TOOL_PREFIX_CAP : 0;
+  if (own === 0) return PREFIXED_TOOLS.has(name) ? TOOL_PREFIX_CAP : 0;
   // `+ 2` for the blank line `prefixToolDescription` puts between the two.
-  return PREFIXED_TOOLS.has(tool.name) ? own + TOOL_PREFIX_CAP + 2 : own;
+  return PREFIXED_TOOLS.has(name) ? own + TOOL_PREFIX_CAP + 2 : own;
 }

package/src/modules/tool-registry/guide-first.ts

@@ -1,3 +1,4 @@
+import { splitCallLine } from '@bevel-software/platform-mcp-core';
 import type { UtcpTool } from './tool.contract.js';
 
 /** The one tool that returns the platform's guide (see `modules/agent-guide`). */
@@ -19,9 +20,15 @@ export const GUIDE_FIRST_SENTENCE = `Call \`${GET_AGENT_GUIDE_TOOL}\` first and
  * sentence is put in front of a description — the registry for the tools it
  * lists, the MCP service for the meta-tools it builds itself — so the two
  * cannot drift apart on what "once" means.
+ *
+ * Behind a `Call:` line, never ahead of it: the call example is the first
+ * line of every description (see mcp-core's `withCallExample`), and the
+ * sentence opens what follows it.
  */
 export function guideFirstDescription(description: string | undefined): string {
-  const own = description ?? '';
+  const { call, rest } = splitCallLine(description ?? '');
+  if (call !== null) return `${call}\n\n${guideFirstDescription(rest)}`;
+  const own = rest;
   if (own.startsWith(GUIDE_FIRST_SENTENCE)) return own;
   return own ? `${GUIDE_FIRST_SENTENCE} ${own}` : GUIDE_FIRST_SENTENCE;
 }

package/src/modules/workflow/__tests__/file-lock.service.deletion-gate.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import type { AuthUser } from '@bevel-software/platform-shared';
+import type { Database } from '../../database/connection.js';
+import { FileLockService } from '../file-lock.service.js';
+import { WorkflowValidationError } from '../../../shared/domain-errors.js';
+import { makeFakeLockDb, type FakeLockDb } from './fake-file-lock-db.js';
+
+/**
+ * A deletion runs its last "is any save landing?" check inside
+ * `whileNoneAcquired`, and a save starts by taking its file lock. An acquire
+ * that passed the gate before the deletion began, but whose row was still
+ * being written, must be seen by that check — not land after it.
+ */
+
+const ALICE: AuthUser = { id: '11111111-1111-4111-8111-111111111111', email: 'alice@example.com', name: 'Alice' };
+const WS = 'alice%2Fdraft';
+const BRANCH = 'alice/draft';
+const PATH = 'knowledge-base/a.md';
+
+/** The fake lock db, with every INSERT held until `release()`. */
+function withHeldInserts(fake: FakeLockDb): { db: Database; release: () => void } {
+  let release!: () => void;
+  const gate = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const base = fake.db as unknown as { insert: () => { values: (row: unknown) => Record<string, unknown> } };
+  const db = {
+    ...base,
+    insert: () => ({
+      values: (row: unknown) => {
+        const chain = base.insert().values(row) as {
+          onConflictDoUpdate: (arg: unknown) => unknown;
+          returning: () => Promise<unknown>;
+        };
+        const held = {
+          onConflictDoUpdate: (arg: unknown) => {
+            chain.onConflictDoUpdate(arg);
+            return held;
+          },
+          returning: async () => {
+            await gate;
+            return chain.returning();
+          },
+        };
+        return held;
+      },
+    }),
+  } as unknown as Database;
+  return { db, release };
+}
+
+describe('FileLockService deletion gate', () => {
+  let fake: FakeLockDb;
+
+  beforeEach(() => {
+    fake = makeFakeLockDb();
+  });
+
+  it('waits for an acquire already under way, so the check inside sees its lock', async () => {
+    const { db, release } = withHeldInserts(fake);
+    const locks = new FileLockService(db);
+
+    const acquire = locks.acquire(WS, BRANCH, PATH, ALICE);
+    let sawLock: boolean | null = null;
+    const deletion = locks.whileNoneAcquired(BRANCH, async () => {
+      sawLock = await locks.hasAnyActive(WS);
+    });
+
+    await new Promise((r) => setTimeout(r, 10));
+    // The acquire's row is not written yet, so the check has not run.
+    expect(sawLock).toBeNull();
+
+    release();
+    await expect(acquire).resolves.toMatchObject({ acquired: true });
+    await deletion;
+    expect(sawLock).toBe(true);
+  });
+
+  it('refuses an acquire that starts while the deletion runs', async () => {
+    const locks = new FileLockService(fake.db);
+    let refused: unknown = null;
+    await locks.whileNoneAcquired(BRANCH, async () => {
+      refused = await locks.acquire(WS, BRANCH, PATH, ALICE).catch((err: unknown) => err);
+    });
+    expect(refused).toBeInstanceOf(WorkflowValidationError);
+    expect(fake.rows()).toHaveLength(0);
+    // And grants it again once the deletion is over.
+    await expect(locks.acquire(WS, BRANCH, PATH, ALICE)).resolves.toMatchObject({ acquired: true });
+  });
+
+  it('does not wait for an acquire on another branch', async () => {
+    const { db, release } = withHeldInserts(fake);
+    const locks = new FileLockService(db);
+
+    const other = locks.acquire('bob%2Fdraft', 'bob/draft', PATH, ALICE);
+    let ran = false;
+    await locks.whileNoneAcquired(BRANCH, async () => {
+      ran = true;
+    });
+    expect(ran).toBe(true);
+    release();
+    await other;
+  });
+});

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

@@ -109,3 +109,69 @@ describe('PendingCommitsService.markNeedsAttentionInWorkspace', () => {
     await expect(new PendingCommitsService(db).markNeedsAttentionInWorkspace('main', 'whatever')).resolves.toBe(0);
   });
 });
+
+/**
+ * What `mergeBranch` waits on: the commits still between a branch's saved
+ * files and its remote. `pending` and `running` both count — a row the worker
+ * holds is not pushed yet — and a `needs_attention` row is reported with its
+ * message, because nothing will land it without a person.
+ */
+describe('PendingCommitsService.queuedOnBranch', () => {
+  function selectDb(rows: Array<{ status: string; lastError: string | null }>) {
+    const orderBy = vi.fn(async () => rows);
+    const where = vi.fn(() => ({ orderBy }));
+    const db = { select: vi.fn(() => ({ from: () => ({ where }) })) } as unknown as Database;
+    return { db, where, orderBy };
+  }
+
+  it('counts pending and running rows, and reports no attention when none is stuck', async () => {
+    const { db, where } = selectDb([
+      { status: 'pending', lastError: null },
+      { status: 'running', lastError: null },
+    ]);
+    await expect(new PendingCommitsService(db).queuedOnBranch('alice/draft')).resolves.toEqual({
+      queued: 2,
+      stuck: 0,
+      needsAttention: null,
+    });
+    // Keyed on the branch column.
+    const sql = new PgDialect().sqlToQuery((where.mock.calls[0] as unknown as [SQL])[0]);
+    expect(sql.sql).toMatch(/"branch" = \$1/);
+    expect(sql.params).toEqual(['alice/draft']);
+  });
+
+  it('reports the oldest needs_attention row\'s message alongside the count', async () => {
+    const { db, orderBy } = selectDb([
+      { status: 'pending', lastError: null },
+      { status: 'needs_attention', lastError: 'push rejected' },
+      { status: 'needs_attention', lastError: 'later' },
+    ]);
+    await expect(new PendingCommitsService(db).queuedOnBranch('alice/draft')).resolves.toEqual({
+      queued: 1,
+      stuck: 2,
+      needsAttention: 'push rejected',
+    });
+    // "Oldest" is the query's order, so every call reports the same message.
+    const dialect = new PgDialect();
+    const order = (orderBy.mock.calls[0] as unknown as SQL[]).map((o) => dialect.sqlToQuery(o).sql);
+    expect(order).toEqual(['"pending_commits"."queued_at" asc', '"pending_commits"."id" asc']);
+  });
+
+  it('falls back to a message when a stuck row has an empty error, so it is never read as retryable', async () => {
+    const { db } = selectDb([{ status: 'needs_attention', lastError: '' }]);
+    await expect(new PendingCommitsService(db).queuedOnBranch('alice/draft')).resolves.toEqual({
+      queued: 0,
+      stuck: 1,
+      needsAttention: 'A queued commit on this branch failed and needs a person.',
+    });
+  });
+
+  it('answers nothing queued for a quiet branch', async () => {
+    const { db } = selectDb([]);
+    await expect(new PendingCommitsService(db).queuedOnBranch('quiet')).resolves.toEqual({
+      queued: 0,
+      stuck: 0,
+      needsAttention: null,
+    });
+  });
+});

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

@@ -139,6 +139,30 @@ describe('PendingCommitsWorker.drainOnce', () => {
     expect(feedback.send).not.toHaveBeenCalled();
   });
 
+  /**
+   * The author's synthetic id reaches log lines (`user=<id>` when a push or
+   * its recovery fails), and log lines carry no email addresses: the id is
+   * opaque, and the same person gets the same one however their address was
+   * typed.
+   */
+  it("the commit author's id carries no address, and is the same for one person", async () => {
+    const seen: string[] = [];
+    workflow.runPendingCommit.mockImplementation(async (_ws: string, _b: string, _p: string, user: AuthUser) => {
+      seen.push(user.id);
+    });
+    for (const authorEmail of ['alice@example.com', 'Alice@Example.com ', 'bob@example.com']) {
+      (service.claimNext as ReturnType<typeof vi.fn>).mockResolvedValueOnce(makeRow({ authorEmail }));
+      await worker.drainOnce();
+    }
+    expect(seen).toHaveLength(3);
+    for (const id of seen) {
+      expect(id).not.toContain('@');
+      expect(id).not.toMatch(/alice|bob|example/i);
+    }
+    expect(seen[0]).toBe(seen[1]);
+    expect(seen[0]).not.toBe(seen[2]);
+  });
+
   it('skips work entirely when claimNext returns null (idle queue)', async () => {
     (service.claimNext as ReturnType<typeof vi.fn>).mockResolvedValueOnce(null);
 
@@ -225,7 +249,11 @@ describe('PendingCommitsWorker.drainOnce', () => {
     expect(call.message).toContain('ws-1');
     expect(call.message).toContain('Foo.md');
     expect(call.message).toContain('unrecoverable');
-    expect(call.message).toContain('alice@example.com');
+    // The author is on the queue row the notice names — never in the body,
+    // which a core-only deployment writes to its log.
+    expect(call.message).toContain('Queue row: row-1');
+    expect(call.message).not.toContain('@');
+    expect(call.message).not.toContain('Alice');
   });
 
   it('a path-outside-repo refusal escalates at once: no retry, no recovery agent, the notice names the corrected path', async () => {
@@ -258,7 +286,8 @@ describe('PendingCommitsWorker.drainOnce', () => {
     // The correction survives the truncation: it rides on the error payload,
     // not on the message.
     expect(call.message).toContain('Use instead: knowledge-base/KnowledgeBase/Reviews/PR-12.html');
-    expect(call.message).toContain('alice@example.com');
+    expect(call.message).toContain('Queue row: row-1');
+    expect(call.message).not.toContain('@');
   });
 
   it('a feedback-sink failure does not throw — the row stays needs_attention regardless', async () => {