@bevel-software/platform-core-backend 0.36.1 → 0.37.0

package/src/modules/database/__tests__/connection.test.ts

@@ -10,6 +10,8 @@ import {
   getDb,
   type Database,
 } from '../connection.js';
+import { setLogger } from '../../../shared/logging.js';
+import { capturingLogger } from '../../../__tests__/capturing-logger.js';
 
 /**
  * Pools here are never connected: `pg.Pool` opens nothing until a query is
@@ -27,6 +29,34 @@ afterEach(async () => {
   await Promise.all(opened.splice(0).map((db) => closeDb(db)));
 });
 
+describe('an idle connection the server closes', () => {
+  it('is logged, with the error, and let go — the pool has a listener, so the event cannot end the process', () => {
+    // A capturing logger stands in for the process's: the warning is the
+    // behaviour under test, not a side effect to tolerate.
+    const { logger: capturing, lines } = capturingLogger();
+    const previous = setLogger(capturing);
+    try {
+      const db = createDb(URL);
+      opened.push(db);
+      // `pg.Pool` emits an idle client's failure on itself; without a listener
+      // Node throws the event. The terminated-backend error is what a server
+      // restart or a forced drop sends to every idle client.
+      const terminated = Object.assign(new Error('terminating connection due to administrator command'), { code: '57P01' });
+      expect(db.$client.listenerCount('error')).toBe(1);
+      expect(() => db.$client.emit('error', terminated)).not.toThrow();
+      expect(lines).toEqual([
+        {
+          level: 'warn',
+          message: 'an idle database connection was closed by the server; the next query opens a new one:',
+          fields: { module: 'database', err: terminated },
+        },
+      ]);
+    } finally {
+      setLogger(previous);
+    }
+  });
+});
+
 describe('schema per knowledge base', () => {
   it('searches the schema it was built for, and leaves the default schema to the server', () => {
     const acme = createDb(URL, { schema: 'acme' });

package/src/modules/database/connection.ts

@@ -2,6 +2,9 @@ import { sql } from 'drizzle-orm';
 import { drizzle } from 'drizzle-orm/node-postgres';
 import pg from 'pg';
 import * as schema from './schema.js';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('database');
 import { PII_CIPHERTEXT_PREFIX, PiiParam, derivePiiKeys, type PiiKeys } from '../../shared/column-crypto.js';
 
 /**
@@ -189,6 +192,15 @@ export function createDb(databaseUrl: string, opts: DbOptions = {}) {
     // operator's own `search_path` stays in force there.
     ...(dbSchema === DEFAULT_DB_SCHEMA ? {} : { options: `-c search_path=${dbSchema}` }),
   });
+  // An IDLE client's failure — its backend terminated by the server (a
+  // restart, a `drop database … with (force)`, an administrator's
+  // `pg_terminate_backend`), a dropped network — is emitted on the pool, and
+  // an 'error' event nobody listens to ends the process. Logged and let go:
+  // the pool has already discarded that client, and the next query opens a
+  // fresh one. A query in flight is not this path; it fails to its caller.
+  pool.on('error', (err) => {
+    log.warn('an idle database connection was closed by the server; the next query opens a new one:', { err });
+  });
   const db = drizzle(pool, { schema });
   schemas.set(db, dbSchema);
   if (keys) piiKeys.set(db, { keys, of: opts.piiKey! });

package/src/modules/embed/__tests__/embed.service.test.ts

@@ -1,10 +1,9 @@
 import jwt from 'jsonwebtoken';
 import { createHmac } from 'node:crypto';
 import { describe, expect, it, vi } from 'vitest';
-import { createFileReaderRegistry } from '../../workspace/file-readers/file-reader.registry.js';
-import type { DocExtractOutcome, DocExtractService } from '../../workspace/file-readers/doc-extract.service.js';
-import { makeRolesYamlWriteValidator, RolesYamlInvalidError } from '../../access-model/roles-yaml-guard.js';
-import { ACCOUNT_DEACTIVATED_MESSAGE } from '../../auth/account-admission.js';
+import { realFileReaders } from '../../../__tests__/real-readers.js';
+import { makeRolesYamlWriteValidator } from '../../access-model/index.js';
+import { ACCOUNT_DEACTIVATED_MESSAGE } from '../../auth/index.js';
 import { testKbContext, TEST_BRANCH_MODEL } from '../../../__tests__/kb-context.js';
 import { EmbedService, type EmbedConfig } from '../embed.service.js';
 import {
@@ -54,19 +53,6 @@ interface Opts {
   resolveNodeId?: ((id: string) => Promise<string | null>) | null;
 }
 
-/**
- * The extraction service the reader registry takes, typed against its
- * contract: no test here reads a document-format file, and one that did
- * would get this typed refusal, not a silent empty text.
- */
-function noDocExtract(): DocExtractService {
-  const extract = async (): Promise<DocExtractOutcome> => ({
-    ok: false,
-    message: 'this suite reads no document-format file',
-  });
-  return { extract } satisfies Pick<DocExtractService, 'extract'> as DocExtractService;
-}
-
 function build(opts: Opts = {}) {
   const files: Record<string, string | Buffer> = opts.files ?? { [WS]: PAGE };
   const workspaceService = {
@@ -138,7 +124,7 @@ function build(opts: Opts = {}) {
     versionControlService as never,
     gitService as never,
     accountLinks as never,
-    createFileReaderRegistry(noDocExtract()),
+    realFileReaders(),
     // The real gate: the property under test is that an embed write cannot
     // put on disk what the app's editor would refuse.
     makeRolesYamlWriteValidator(KB),
@@ -791,7 +777,7 @@ describe('EmbedService: the roles.yaml write gate', () => {
   it('refuses to save a roles.yaml that would not parse, writing nothing and taking no lock', async () => {
     const { service, workspaceService, versionControlService } = build({ files: { [ROLES]: VALID } });
     const { token } = await service.mintForUser({ userId: USER.id, reference: 'roles.yaml' });
-    await expect(service.save(token, 'roles: [oops')).rejects.toThrow(RolesYamlInvalidError);
+    await expect(service.save(token, 'roles: [oops')).rejects.toMatchObject({ status: 422, payload: { kind: 'roles-yaml-invalid' } });
     expect(workspaceService.writeFile).not.toHaveBeenCalled();
     expect(versionControlService.acquireLock).not.toHaveBeenCalled();
     expect(versionControlService.releaseLock).not.toHaveBeenCalled();
@@ -803,7 +789,7 @@ describe('EmbedService: the roles.yaml write gate', () => {
       files: { [ROLES]: VALID },
     });
     const { token } = await service.mintForUser({ userId: USER.id, reference: 'roles.yaml' });
-    await expect(service.propose(token, 'roles: [oops')).rejects.toThrow(RolesYamlInvalidError);
+    await expect(service.propose(token, 'roles: [oops')).rejects.toMatchObject({ status: 422, payload: { kind: 'roles-yaml-invalid' } });
     expect(versionControlService.createBranch).not.toHaveBeenCalled();
     expect(workspaceService.writeFile).not.toHaveBeenCalled();
     expect(versionControlService.commitChanges).not.toHaveBeenCalled();

package/src/modules/kb-fs/__tests__/file-change-notifier.test.ts

@@ -18,12 +18,13 @@ describe('FileChangeNotifier', () => {
     const b = vi.fn();
     notifier.onFilesChanged(a);
     notifier.onFilesChanged(b);
-    const c = change(['x/Tools/a.tool', 'x/Knowledge/B.md']);
-    notifier.emit(c);
+    notifier.emit(change(['x/Tools/a.tool', 'x/Knowledge/B.md']));
+    // Both hear the one change, shaped: paths sorted.
+    const shaped = change(['x/Knowledge/B.md', 'x/Tools/a.tool']);
     expect(a).toHaveBeenCalledTimes(1);
-    expect(a).toHaveBeenCalledWith(c);
+    expect(a).toHaveBeenCalledWith(shaped);
     expect(b).toHaveBeenCalledTimes(1);
-    expect(b).toHaveBeenCalledWith(c);
+    expect(b).toHaveBeenCalledWith(shaped);
   });
 
   it('a throwing listener never blocks the others (commit isolation)', () => {
@@ -38,6 +39,16 @@ describe('FileChangeNotifier', () => {
     expect(after).toHaveBeenCalledOnce();
   });
 
+  it('a listener whose promise rejects is isolated too — the rejection is caught, the others heard', async () => {
+    const notifier = new FileChangeNotifier();
+    const after = vi.fn();
+    notifier.onFilesChanged(async () => Promise.reject(new Error('boom, later')));
+    notifier.onFilesChanged(after);
+    expect(() => notifier.emit(change(['x/A.md']))).not.toThrow();
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    expect(after).toHaveBeenCalledOnce();
+  });
+
   it('an empty path list emits nothing; unsubscribe stops delivery', () => {
     const notifier = new FileChangeNotifier();
     const listener = vi.fn();
@@ -48,4 +59,12 @@ describe('FileChangeNotifier', () => {
     notifier.emit(change(['x/A.md']));
     expect(listener).not.toHaveBeenCalled();
   });
+
+  it('hands every listener the paths sorted and unique: the shape of the contract is made here, once', () => {
+    const notifier = new FileChangeNotifier();
+    const heard: FilesChange[] = [];
+    notifier.onFilesChanged((c) => heard.push(c));
+    notifier.emit(change(['x/B.md', 'x/A.md', 'x/B.md']));
+    expect(heard).toEqual([change(['x/A.md', 'x/B.md'])]);
+  });
 });

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

@@ -6,11 +6,7 @@ import type { AuthUser, IVersionControlService } from '@bevel-software/platform-
 import { LocalFilesystem } from '@mastra/core/workspace';
 import { LockingFilesystem } from '../locking-filesystem.js';
 import { PushNeedsAgentResolutionError, VersionControlValidationError } from '../../../shared/domain-errors.js';
-import {
-  makeAgentRolesYamlWriteValidator,
-  RolesYamlInvalidError,
-  RolesYamlNewRoleError,
-} from '../../access-model/roles-yaml-guard.js';
+import { makeAgentRolesYamlWriteValidator } from '../../access-model/index.js';
 
 /** The clone folder at the workspace root: every path the filesystem mutates lives under it. */
 const KB = 'knowledge-base';
@@ -213,7 +209,7 @@ describe('LockingFilesystem — every mutating op runs acquire → super → rel
   });
 });
 
-describe('LockingFilesystem.writeFiles — batch with deletes + one batched change event', () => {
+describe('LockingFilesystem.writeFiles — batch with deletes', () => {
   let root: string;
 
   beforeEach(async () => {
@@ -224,12 +220,11 @@ describe('LockingFilesystem.writeFiles — batch with deletes + one batched chan
     await fs.rm(root, { recursive: true, force: true });
   });
 
-  it('locks writes AND deletes, applies both, emits ONE batched onFilesChanged', async () => {
+  it('locks writes AND deletes, applies both, returns the commit', async () => {
     await fs.mkdir(path.join(root, 'knowledge-base/Tools'), { recursive: true });
     await fs.writeFile(path.join(root, 'knowledge-base/Tools/old.tool'), '{}');
 
     const versionControl = makeVersionControl();
-    const emitted: unknown[] = [];
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
       {
@@ -237,7 +232,6 @@ describe('LockingFilesystem.writeFiles — batch with deletes + one batched chan
         workspaceId: 'ws-feat',
         branch: 'feat',
         user: USER, kbDirName: KB,
-        fileChanges: { emit: (c: unknown) => emitted.push(c) } as never,
       },
     );
 
@@ -253,23 +247,14 @@ describe('LockingFilesystem.writeFiles — batch with deletes + one batched chan
     expect(await fs.readFile(path.join(root, 'knowledge-base/Tools/new.tool'), 'utf-8')).toContain('http');
     await expect(fs.access(path.join(root, 'knowledge-base/Tools/old.tool'))).rejects.toThrow();
     expect(change).toEqual({});
-    // ONE event carrying the whole batch (sorted), attributed to the user.
-    expect(emitted).toHaveLength(1);
-    expect(emitted[0]).toMatchObject({
-      workspaceId: 'ws-feat',
-      branch: 'feat',
-      paths: ['knowledge-base/Tools/new.tool', 'knowledge-base/Tools/old.tool'],
-      byUser: USER,
-    });
   });
 
-  it('a failing commit releases every lock WITHOUT committing and emits nothing', async () => {
+  it('a failing commit releases every lock WITHOUT committing', async () => {
     await fs.mkdir(path.join(root, 'knowledge-base/Tools'), { recursive: true });
     await fs.writeFile(path.join(root, 'knowledge-base/Tools/old.tool'), '{}');
 
     const versionControl = makeVersionControl();
     (versionControl.commitChanges as ReturnType<typeof vi.fn>).mockRejectedValue(new Error('push exploded'));
-    const emitted: unknown[] = [];
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
       {
@@ -277,7 +262,6 @@ describe('LockingFilesystem.writeFiles — batch with deletes + one batched chan
         workspaceId: 'ws-feat',
         branch: 'feat',
         user: USER, kbDirName: KB,
-        fileChanges: { emit: (c: unknown) => emitted.push(c) } as never,
       },
     );
 
@@ -292,11 +276,10 @@ describe('LockingFilesystem.writeFiles — batch with deletes + one batched chan
     // Every acquired path goes through the NO-COMMIT release — which is what
     // discards the uncommitted bytes (write reverted, delete restored) in the
     // real VersionControlService via git.discardPath. The committing release must
-    // never run, and no change event fires for a failed batch.
+    // never run.
     expect(versionControl.releaseLockNoCommit).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/Tools/new.tool', USER);
     expect(versionControl.releaseLockNoCommit).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/Tools/old.tool', USER);
     expect(versionControl.releaseLock).not.toHaveBeenCalled();
-    expect(emitted).toHaveLength(0);
   });
 
   it('a POST-commit push failure releases WITH commit-on-release (arms the worker retry), never the discard path', async () => {
@@ -311,7 +294,6 @@ describe('LockingFilesystem.writeFiles — batch with deletes + one batched chan
     (versionControl.commitChanges as ReturnType<typeof vi.fn>).mockRejectedValue(
       new PushNeedsAgentResolutionError('feat', 'knowledge-base/A.md', 'non-fast-forward', 'rebase failed'),
     );
-    const emitted: unknown[] = [];
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
       {
@@ -319,7 +301,6 @@ describe('LockingFilesystem.writeFiles — batch with deletes + one batched chan
         workspaceId: 'ws-feat',
         branch: 'feat',
         user: USER, kbDirName: KB,
-        fileChanges: { emit: (c: unknown) => emitted.push(c) } as never,
       },
     );
 
@@ -329,25 +310,6 @@ describe('LockingFilesystem.writeFiles — batch with deletes + one batched chan
 
     expect(versionControl.releaseLock).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/A.md', USER);
     expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
-    expect(emitted).toHaveLength(0);
-  });
-
-  it('emits nothing on a no-op commit (clean tree)', async () => {
-    const versionControl = makeVersionControl();
-    (versionControl.commitChanges as ReturnType<typeof vi.fn>).mockResolvedValue(null);
-    const emitted: unknown[] = [];
-    const fsLayer = new LockingFilesystem(
-      { basePath: root, contained: true },
-      {
-        versionControl,
-        workspaceId: 'ws-feat',
-        branch: 'feat',
-        user: USER, kbDirName: KB,
-        fileChanges: { emit: (c: unknown) => emitted.push(c) } as never,
-      },
-    );
-    await fsLayer.writeFiles([{ path: 'knowledge-base/A.md', content: 'same' }], 'noop');
-    expect(emitted).toHaveLength(0);
   });
 });
 
@@ -714,7 +676,6 @@ describe('LockingFilesystem — creator read grants on creation', () => {
       wsRelPath: 'knowledge-base/KnowledgeBase/Mine/access.md',
       apply: (current: string) => current, // grant already present → no-op
     });
-    const emitted: { paths: string[] }[] = [];
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
       {
@@ -723,7 +684,6 @@ describe('LockingFilesystem — creator read grants on creation', () => {
         branch: 'feat',
         user: USER, kbDirName: KB,
         creatorAccess,
-        fileChanges: { emit: (c: { paths: string[] }) => emitted.push(c) } as never,
       },
     );
     await fsLayer.writeFiles([{ path: 'knowledge-base/KnowledgeBase/Mine/doc.md', content: 'body' }], 'batch');
@@ -734,7 +694,6 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     // ...but the commit is scoped to the caller's path only.
     const commitPaths = (versionControl.commitChanges as ReturnType<typeof vi.fn>).mock.calls[0][3];
     expect(commitPaths).toEqual(['knowledge-base/KnowledgeBase/Mine/doc.md']);
-    expect(emitted[0].paths).toEqual(['knowledge-base/KnowledgeBase/Mine/doc.md']);
     // The seeded file is untouched.
     expect(await fs.readFile(path.join(root, 'knowledge-base/KnowledgeBase/Mine/access.md'), 'utf-8')).toBe(
       seedContent,
@@ -1228,7 +1187,7 @@ describe('LockingFilesystem — the agent roles.yaml gate covers every op that l
   }
 
   async function expectRefused(op: Promise<unknown>, versionControl: IVersionControlService): Promise<void> {
-    await expect(op).rejects.toBeInstanceOf(RolesYamlNewRoleError);
+    await expect(op).rejects.toMatchObject({ status: 422, payload: { kind: 'roles-yaml-new-role' } });
     expect(versionControl.acquireLock).not.toHaveBeenCalled();
     expect(await fs.readFile(path.join(root, ROLES), 'utf-8')).toBe(CURRENT);
   }
@@ -1291,7 +1250,7 @@ describe('LockingFilesystem — the agent roles.yaml gate covers every op that l
     }
 
     async function expectRefusedUnderLock(op: Promise<unknown>, versionControl: IVersionControlService, locks: number): Promise<void> {
-      await expect(op).rejects.toBeInstanceOf(RolesYamlNewRoleError);
+      await expect(op).rejects.toMatchObject({ status: 422, payload: { kind: 'roles-yaml-new-role' } });
       expect(versionControl.releaseLockUntouched).toHaveBeenCalledTimes(locks);
       expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
       expect(versionControl.releaseLock).not.toHaveBeenCalled();
@@ -1325,7 +1284,7 @@ describe('LockingFilesystem — the agent roles.yaml gate covers every op that l
       // change is validity: the same line appended to the rewritten file breaks it.
       const rewritten = 'roles:\n  Admin:\n    - a@x.eu';
       const versionControl = racingVersionControl(() => fs.writeFile(path.join(root, ROLES), rewritten));
-      await expect(layer(versionControl).appendFile(ROLES, '    - b@x.eu\n')).rejects.toBeInstanceOf(RolesYamlInvalidError);
+      await expect(layer(versionControl).appendFile(ROLES, '    - b@x.eu\n')).rejects.toMatchObject({ status: 422, payload: { kind: 'roles-yaml-invalid' } });
       expect(versionControl.releaseLockUntouched).toHaveBeenCalledTimes(1);
       expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
       expect(await fs.readFile(path.join(root, ROLES), 'utf-8')).toBe(rewritten);

package/src/modules/kb-fs/__tests__/move-with-edits.test.ts

@@ -4,11 +4,11 @@ import { promisify } from 'node:util';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
-import type { AuthUser, IVersionControlService } from '@bevel-software/platform-shared';
+import type { AuthUser, FilesChange, IVersionControlService } from '@bevel-software/platform-shared';
+import type { VersionControlHooks } from '../../version-control/index.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
-import { GitService } from '../../version-control/git/git.service.js';
-import { VersionControlHooks } from '../../version-control/version-control-hooks.js';
-import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import { realGitService, realVersionControlHooks } from '../../../__tests__/real-version-control.js';
+import type { WorkspaceService } from '../../workspace/index.js';
 import { LockingFilesystem, MoveLockedError, MoveRacedError, MoveUndoError } from '../locking-filesystem.js';
 import { PushNeedsAgentResolutionError } from '../../../shared/domain-errors.js';
 
@@ -59,13 +59,14 @@ beforeEach(async () => {
   await git(repo, ['add', '-A']);
   await git(repo, ['commit', '-m', 'seed']);
 
-  const svc = new GitService(
+  landed = [];
+  hooks = realVersionControlHooks();
+  hooks.onCommitValidation(vi.fn(async () => ({ ok: true, mustFix: [], warnings: [], rawOutput: '' })));
+  // What the git layer reports landing — the one place every commit is announced from.
+  hooks.onCommitLanded((change) => landed.push(change));
+  const svc = realGitService(
     { getWorkspacePath: async () => root } as unknown as WorkspaceService,
-    (() => {
-      const hooks = new VersionControlHooks();
-      hooks.onCommitValidation(vi.fn(async () => ({ ok: true, mustFix: [], warnings: [], rawOutput: '' })));
-      return hooks;
-    })(),
+    hooks,
     testKbContext({ kbDirName: KB }),
   );
   lockedPaths = new Set();
@@ -103,6 +104,11 @@ const edits = () => [
   { path: `${KB}/Index.md`, lockAt: `${KB}/Index.md`, content: '[one](Topics/Deep/A/One.md)\n' },
 ];
 
+/** Every commit the git layer landed, as the hook heard it (paths as git named them; the notifier is what sorts). */
+let landed: FilesChange[] = [];
+let hooks: VersionControlHooks;
+const heard = () => landed.map((c) => ({ ...c, paths: [...c.paths].sort() }));
+
 describe('LockingFilesystem.moveWithEdits', () => {
   it('lands the folder move and every edit as ONE commit that git reads as renames', async () => {
     const before = (await git(repo, ['rev-list', '--count', 'HEAD'])).trim();
@@ -123,6 +129,40 @@ describe('LockingFilesystem.moveWithEdits', () => {
     expect(await read('Topics/Deep/A/One.md')).toContain('../../../NodeTypes/Task.md');
     // The binary moved byte for byte.
     expect([...(await fs.readFile(path.join(repo, 'Topics/Deep/A/pic.png')))]).toEqual([0x89, 0x50, 0x4e, 0x47, 0, 1, 2, 3]);
+    // The git layer reported the ONE commit, with every path it named at both
+    // ends — the one place any commit is announced from.
+    expect(heard()).toEqual([
+      {
+        workspaceId: WS,
+        branch: 'feature-test',
+        byUser: USER,
+        paths: [
+          `${KB}/Index.md`,
+          `${KB}/Projects/A/One.md`,
+          `${KB}/Projects/A/Two.md`,
+          `${KB}/Projects/A/pic.png`,
+          `${KB}/Topics/Deep/A/One.md`,
+          `${KB}/Topics/Deep/A/Two.md`,
+          `${KB}/Topics/Deep/A/pic.png`,
+        ],
+      },
+    ]);
+  });
+
+  it('a reactor that throws cannot unwind the landed move: the hook runs isolated, the commit, the files and the rename stay', async () => {
+    hooks.onCommitLanded(() => {
+      throw new Error('reactor exploded');
+    });
+    const before = (await git(repo, ['rev-list', '--count', 'HEAD'])).trim();
+    await fsLayer().moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A');
+    expect(landed).toHaveLength(1);
+    expect((await git(repo, ['rev-list', '--count', 'HEAD'])).trim()).toBe(String(Number(before) + 1));
+    expect((await git(repo, ['status', '--porcelain'])).trim()).toBe('');
+    expect(await read('Index.md')).toBe('[one](Topics/Deep/A/One.md)\n');
+    expect(await read('Topics/Deep/A/One.md')).toContain('../../../NodeTypes/Task.md');
+    await expect(fs.access(path.join(repo, 'Projects/A'))).rejects.toThrow();
+    // Every lock had already been given back untouched; nothing was discarded.
+    expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
   });
 
   it('a single file moved with edits is one commit with a rename', async () => {
@@ -152,6 +192,7 @@ describe('LockingFilesystem.moveWithEdits', () => {
     expect(released(versionControl.releaseLockUntouched)).toEqual([`${KB}/Index.md`, `${KB}/Projects/A`, `${KB}/Projects/A/One.md`]);
     expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
     expect(versionControl.releaseLock).not.toHaveBeenCalled();
+    expect(landed).toEqual([]);
     expect(await read('Index.md')).toBe('[one](Projects/A/One.md)\n');
   }, 20_000);
 
@@ -176,6 +217,7 @@ describe('LockingFilesystem.moveWithEdits', () => {
     expect(await read('Index.md')).toBe('[one](Projects/A/One.md)\n');
     expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
     expect(released(versionControl.releaseLockUntouched).length).toBeGreaterThan(0);
+    expect(landed).toEqual([]);
   });
 
   it('a move that fails and cannot be undone releases every lock with the discard, and says both', async () => {
@@ -195,6 +237,8 @@ describe('LockingFilesystem.moveWithEdits', () => {
     expect(discarded).toContain(`${KB}/Projects/A`);
     expect(discarded).toContain(`${KB}/Topics/Deep/A/One.md`);
     expect(discarded).toContain(`${KB}/Index.md`);
+    // A failed commit announces nothing.
+    expect(landed).toEqual([]);
   });
 
   it('a commit that landed but could not be pushed enqueues the committed paths only; the folder locks go back untouched', async () => {
@@ -223,6 +267,25 @@ describe('LockingFilesystem.moveWithEdits', () => {
     expect(enqueued).not.toContain(`${KB}/Projects/A`);
     expect(enqueued).not.toContain(`${KB}/Topics/Deep/A`);
     expect(untouched).toEqual([`${KB}/Projects/A`, `${KB}/Topics/Deep/A`]);
+    // The commit landed, so the git layer reported it — once, with the
+    // committed scope; the worker's later push makes no new commit and
+    // reports nothing more.
+    expect(heard()).toEqual([
+      {
+        workspaceId: WS,
+        branch: 'feature-test',
+        byUser: USER,
+        paths: [
+          `${KB}/Index.md`,
+          `${KB}/Projects/A/One.md`,
+          `${KB}/Projects/A/Two.md`,
+          `${KB}/Projects/A/pic.png`,
+          `${KB}/Topics/Deep/A/One.md`,
+          `${KB}/Topics/Deep/A/Two.md`,
+          `${KB}/Topics/Deep/A/pic.png`,
+        ],
+      },
+    ]);
   });
 
   it('locks every file of a moved folder at its old and its new path', async () => {

package/src/modules/kb-fs/file-change-notifier.ts

@@ -1,38 +1,63 @@
 /**
- * One in-process notification fired AFTER a set of file changes is committed +
- * pushed (post-lock-release), so backend services can react to KB writes without
- * the per-file TTL wait. Distinct from the SSE `VersionControlEventBus`, which fans
- * scoped events to browser sessions; this is an unscoped, server-side domain hook.
+ * One in-process notification per commit the git service lands — a single-file
+ * save, an autosave checkpoint, a batch (`LockingFilesystem.writeFiles`, a
+ * bulk upload, the admin roster commits, a plugin rename), a merge, a
+ * `commit_change` — fired when the commit lands: pushed, or awaiting its push
+ * (the later push makes no new commit and is not announced again). Backend
+ * services react to KB writes here without the per-file TTL wait. Distinct
+ * from the SSE `VersionControlEventBus`, which fans scoped events to browser
+ * sessions; this is an unscoped, server-side domain hook.
  *
- * BATCHED by design: a single-file save emits `paths: [p]`, a batch write
- * (`LockingFilesystem.writeFiles`, e.g. a bulk node upload) emits ONE event with
- * every path it committed. Subscribers that do expensive per-event work (the
- * id-repair rebuilds the id index) handle a whole batch off one rebuild instead
- * of N back-to-back ones.
+ * ONE SOURCE. The git service reports every commit it lands through
+ * `VersionControlHooks.onCommitLanded`, and the composition root hands that to
+ * this notifier once; nothing else emits here, and a test pins both. A commit
+ * made some other way (the startup runner's seed of a fresh knowledge base,
+ * before any catalog exists) is the one commit this does not see. A commit
+ * that ARRIVES by a pull was landed — and announced — by the process that made
+ * it; a pull of the default branch also announces the tree change on the SSE
+ * bus (`fs-tree-changed`), which the catalogs listen to, and a pull rebases
+ * this process's own commits without re-announcing them (their content is
+ * unchanged).
  *
- * Emitted from the two post-commit chokepoints (`VersionControlService.runPendingCommit`
- * for single-file writes, `LockingFilesystem.writeFiles` for batches).
+ * BATCHED by design: a single-file save emits `paths: [p]`, a batch emits ONE
+ * event with every path it committed, a merge every path it brought in — so a
+ * subscriber that does expensive per-event work (the id-repair rebuilds the id
+ * index) handles a whole batch off one rebuild instead of N back-to-back ones.
+ * Paths are workspace-relative, sorted and unique: `emit` shapes them.
  *
- * Every listener is invoked inside try/catch — a throwing subscriber must never
- * fail the commit that triggered it (mirrors the SSE bus's per-subscriber
- * isolation). Firing is fire-and-forget; a listener that needs to write files
- * (id-repair) does so on its own, after the locks have already been released.
+ * TIMING. The announcement is made when the commit lands, inside the git
+ * layer's reservation. A listener that only reads (the catalogs) is
+ * unaffected by locks. A listener that WRITES an announced path acquires its
+ * lock like any writer, and two cases differ: a batch's committer (the
+ * lock-aware filesystem, the admin commit driver) releases its locks once the
+ * commit's push has either gone through or been handed off to the recovery
+ * worker (the push is then still owed, and the lock no longer guards the
+ * path) — the lock-aware filesystem's acquire retries (three, two seconds
+ * apart) cover the usual push, and a push that outlasts them leaves the writer
+ * to skip; an editor's autosave checkpoint is announced while the editor's
+ * own lock is held, for as long as the person keeps editing, so a write to
+ * that path cannot be made then. In both cases the path's next announcement —
+ * the editor's release commit when it carries new bytes, the next change to
+ * the file — is when such a writer catches up; a writer that skips must
+ * therefore treat "could not lock" as "not now", as the id-repair already
+ * does. Before this release a batch was announced only where its filesystem
+ * had been handed the notifier, and a checkpoint not at all.
+ *
+ * Every listener is invoked isolated (`callFireAndForget`): one that throws, or
+ * whose promise rejects, is logged and never fails the commit that triggered
+ * it (mirrors the SSE bus's per-subscriber isolation). Firing is
+ * fire-and-forget; nothing awaits a listener.
  */
-import type { AuthUser } from '@bevel-software/platform-shared';
+import type { FilesChange } from '@bevel-software/platform-shared';
+import { callFireAndForget, type FireAndForgetListener } from '../../shared/fire-and-forget.js';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('file-change');
 
-export interface FilesChange {
-  workspaceId: string;
-  branch: string;
-  /** Workspace-relative paths committed in this change (≥1; sorted for batches). */
-  paths: string[];
-  /** Who the change was committed as — a reacting write (id-repair) acts as the same user. */
-  byUser: AuthUser;
-}
+export type { FilesChange };
 
-export type FilesChangedListener = (change: FilesChange) => void;
+/** Fire-and-forget: a listener may answer a promise, which nobody awaits; a rejection is logged like a throw. */
+export type FilesChangedListener = FireAndForgetListener<FilesChange>;
 
 export class FileChangeNotifier {
   private readonly listeners = new Set<FilesChangedListener>();
@@ -43,15 +68,13 @@ export class FileChangeNotifier {
     return () => this.listeners.delete(listener);
   }
 
-  /** Fan a change out to every listener; isolate + log each so one can't break the commit. */
+  /** Fan a change out to every listener — paths sorted and unique, nothing for an empty set; each isolated (a throw or a rejection is logged) so one can't break the commit. */
   emit(change: FilesChange): void {
-    if (change.paths.length === 0) return;
+    const paths = [...new Set(change.paths)].sort();
+    if (paths.length === 0) return;
+    const shaped: FilesChange = { ...change, paths };
     for (const listener of this.listeners) {
-      try {
-        listener(change);
-      } catch (err) {
-        log.error('listener threw:', { err });
-      }
+      callFireAndForget(listener, shaped, log, 'a file-change listener failed:');
     }
   }
 }