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

package/src/modules/version-control/git/__tests__/git.service.commitLanded.test.ts

@@ -0,0 +1,199 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import type { FilesChange } from '@bevel-software/platform-shared';
+import { testKbContext } from '../../../../__tests__/kb-context.js';
+import type { IGitRunner } from '../../../../shared/git.contract.js';
+import { VersionControlHooks } from '../../version-control-hooks.js';
+import { GitService } from '../git.service.js';
+import { NodeGitRunner } from '../node-git-runner.js';
+import { gitOut, runGit, stubWorkspaceService } from './git-test-helpers.js';
+
+/**
+ * Every commit the git service lands is reported once through
+ * `VersionControlHooks.onCommitLanded` — the one place a commit is announced
+ * from, so no committer can be forgotten. Each way of committing is driven
+ * here on a real repository: the one-file `commit`, `commitFile`, a scoped
+ * `commitChanges`, a `commitChanges` that finds its scope clean, and a merge.
+ * Paths arrive workspace-relative (the notifier sorts them), as the person.
+ */
+const KB = 'knowledge-base';
+const WS = 'ws-landed';
+const USER = { id: 'u-alice', name: 'Alice', email: 'alice@bevel.software' };
+
+describe('GitService reports every commit it lands through onCommitLanded', () => {
+  let root: string;
+  let repo: string;
+  let git: GitService;
+  let landed: FilesChange[];
+
+  const write = async (rel: string, text: string) => {
+    const abs = path.join(repo, rel);
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+    await fs.writeFile(abs, text);
+  };
+  /** As the notifier will hand it on: paths sorted. */
+  const heard = () => landed.map((c) => ({ ...c, paths: [...c.paths].sort() }));
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-git-landed-'));
+    const workspaceDir = path.join(root, WS);
+    repo = path.join(workspaceDir, KB);
+    await fs.mkdir(repo, { recursive: true });
+    await runGit(repo, ['init', '-b', 'main']);
+    await runGit(repo, ['config', 'user.email', 'test@bevel.local']);
+    await runGit(repo, ['config', 'user.name', 'Test Runner']);
+    await write('Old.md', 'old\n');
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'seed']);
+
+    const hooks = new VersionControlHooks();
+    hooks.onCommitValidation(vi.fn(async () => ({ ok: true, mustFix: [], warnings: [], rawOutput: '' })));
+    landed = [];
+    hooks.onCommitLanded((change) => landed.push(change));
+    git = new GitService(stubWorkspaceService({ [WS]: workspaceDir }), hooks, testKbContext({ kbDirName: KB }));
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+  });
+
+  it('commit: the one file the change touched', async () => {
+    await write('A.md', 'a\n');
+    await git.commit(WS, USER, { summary: 'add A' });
+    expect(heard()).toEqual([{ workspaceId: WS, branch: 'main', paths: [`${KB}/A.md`], byUser: USER }]);
+  });
+
+  it('commit: every file of a new folder, and both ends of a rename — the commit, not the status listing, names them', async () => {
+    await write('Folder/one.md', '1\n');
+    await write('Folder/two.md', '2\n');
+    await git.commit(WS, USER, { summary: 'add a folder' });
+    expect(heard().map((c) => c.paths)).toEqual([[`${KB}/Folder/one.md`, `${KB}/Folder/two.md`]]);
+
+    landed.length = 0;
+    await runGit(repo, ['mv', 'Old.md', 'New.md']);
+    await git.commit(WS, USER, { summary: 'rename' });
+    expect(heard().map((c) => c.paths)).toEqual([[`${KB}/New.md`, `${KB}/Old.md`]]);
+  });
+
+  it('commitChanges without a scope: both ends of a rename', async () => {
+    await runGit(repo, ['mv', 'Old.md', 'Moved.md']);
+    await write('K.md', 'k\n');
+    await git.commitChanges(WS, USER, 'move and add');
+    expect(heard().map((c) => c.paths)).toEqual([[`${KB}/K.md`, `${KB}/Moved.md`, `${KB}/Old.md`]]);
+  });
+
+  it('commitFile: the file named, once — a non-ASCII name verbatim', async () => {
+    await write('B.md', 'b\n');
+    await git.commitFile(WS, USER, `${KB}/B.md`);
+    await write('Ünïcode ñ.md', 'ü\n');
+    await git.commitFile(WS, USER, `${KB}/Ünïcode ñ.md`);
+    expect(heard().map((c) => c.paths)).toEqual([[`${KB}/B.md`], [`${KB}/Ünïcode ñ.md`]]);
+  });
+
+  it('a commit is reported with the paths known before it when the read of its files fails', async () => {
+    const real = new NodeGitRunner();
+    const diffTreeFails: IGitRunner = {
+      defaultTimeoutMs: real.defaultTimeoutMs,
+      credentials: real.credentials,
+      run: ((cwd: string, args: string[], opts?: unknown) =>
+        args[0] === 'diff-tree' ? Promise.reject(new Error('diff-tree unavailable')) : real.run(cwd, args, opts as never)) as IGitRunner['run'],
+    };
+    const hooks = new VersionControlHooks();
+    hooks.onCommitValidation(vi.fn(async () => ({ ok: true, mustFix: [], warnings: [], rawOutput: '' })));
+    const heardHere: FilesChange[] = [];
+    hooks.onCommitLanded((change) => heardHere.push(change));
+    const fragile = new GitService(stubWorkspaceService({ [WS]: path.join(root, WS) }), hooks, testKbContext({ kbDirName: KB }), undefined, null, diffTreeFails);
+
+    await write('L.md', 'l\n');
+    await fragile.commit(WS, USER, { summary: 'add L' });
+    await write('M.md', 'm\n');
+    await write('N.md', 'n\n');
+    await fragile.commitChanges(WS, USER, 'add M and N', [`${KB}/M.md`, `${KB}/N.md`]);
+    await write('O.md', 'o\n');
+    await fragile.commitFile(WS, USER, `${KB}/O.md`);
+
+    // The status listing stands in: the files are still named, the report still made.
+    expect(heardHere.map((c) => [...c.paths].sort())).toEqual([[`${KB}/L.md`], [`${KB}/M.md`, `${KB}/N.md`], [`${KB}/O.md`]]);
+  });
+
+  it('commitChanges: exactly the scoped dirty set — a dirty path outside the scope stays out', async () => {
+    await write('C.md', 'c\n');
+    await write('D.md', 'd\n');
+    await write('E.md', 'e\n');
+    await git.commitChanges(WS, USER, 'batch', [`${KB}/C.md`, `${KB}/D.md`]);
+    expect(heard()).toEqual([{ workspaceId: WS, branch: 'main', paths: [`${KB}/C.md`, `${KB}/D.md`], byUser: USER }]);
+    // E is still the caller's uncommitted business.
+    expect(await gitOut(repo, ['status', '--porcelain'])).toContain('E.md');
+  });
+
+  it('commitChanges on a clean scope lands nothing and reports nothing', async () => {
+    expect(await git.commitChanges(WS, USER, 'nothing', [`${KB}/Old.md`])).toBeNull();
+    expect(landed).toEqual([]);
+  });
+
+  it('a merge: every path the merge brought onto the branch, as the person who merged', async () => {
+    await runGit(repo, ['checkout', '-b', 'topic']);
+    await write('F.md', 'f\n');
+    await write('Old.md', 'old, edited on topic\n');
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'topic work']);
+    await runGit(repo, ['checkout', 'main']);
+    // Main moves too, so the merge is a real merge commit, not a fast-forward.
+    await write('G.md', 'g\n');
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'main work']);
+    // The merge reads the other side as `origin/<branch>`: this repository is its own remote.
+    await runGit(repo, ['remote', 'add', 'origin', repo]);
+
+    const outcome = await git.mergeIntoBranch(WS, 'main', 'topic', USER, { subject: 'Merge topic', body: '' });
+    expect(outcome.kind).toBe('merged');
+    expect(heard()).toEqual([{ workspaceId: WS, branch: 'main', paths: [`${KB}/F.md`, `${KB}/Old.md`], byUser: USER }]);
+  });
+
+  it('a commit is reported even when the attribution read after it fails — the commit exists, so the reactors hear of it', async () => {
+    // A runner like the real one, except that `git log` fails: what a disk or
+    // process fault between the commit and its attribution read looks like.
+    const real = new NodeGitRunner();
+    const logFails: IGitRunner = {
+      defaultTimeoutMs: real.defaultTimeoutMs,
+      credentials: real.credentials,
+      run: ((cwd: string, args: string[], opts?: unknown) =>
+        args[0] === 'log' ? Promise.reject(new Error('git log unavailable')) : real.run(cwd, args, opts as never)) as IGitRunner['run'],
+    };
+    const hooks = new VersionControlHooks();
+    hooks.onCommitValidation(vi.fn(async () => ({ ok: true, mustFix: [], warnings: [], rawOutput: '' })));
+    const heardHere: FilesChange[] = [];
+    hooks.onCommitLanded((change) => heardHere.push(change));
+    const fragile = new GitService(stubWorkspaceService({ [WS]: path.join(root, WS) }), hooks, testKbContext({ kbDirName: KB }), undefined, null, logFails);
+    const before = Number(await gitOut(repo, ['rev-list', '--count', 'HEAD']));
+
+    await write('I.md', 'i\n');
+    await expect(fragile.commitFile(WS, USER, `${KB}/I.md`)).rejects.toThrow('git log unavailable');
+    await write('J.md', 'j\n');
+    await expect(fragile.commit(WS, USER, { summary: 'add J' })).rejects.toThrow('git log unavailable');
+
+    // Both commits landed, and both were reported before the read that failed.
+    expect(Number(await gitOut(repo, ['rev-list', '--count', 'HEAD']))).toBe(before + 2);
+    expect(heardHere.map((c) => c.paths)).toEqual([[`${KB}/I.md`], [`${KB}/J.md`]]);
+  });
+
+  it('a hook that throws, or whose promise rejects, is isolated: the commit stands and the other hooks still hear of it', async () => {
+    const hooks = new VersionControlHooks();
+    hooks.onCommitValidation(vi.fn(async () => ({ ok: true, mustFix: [], warnings: [], rawOutput: '' })));
+    const others: FilesChange[] = [];
+    hooks.onCommitLanded(() => {
+      throw new Error('reactor exploded');
+    });
+    hooks.onCommitLanded(async () => Promise.reject(new Error('reactor exploded later')));
+    hooks.onCommitLanded((change) => others.push(change));
+    const loud = new GitService(stubWorkspaceService({ [WS]: path.join(root, WS) }), hooks, testKbContext({ kbDirName: KB }));
+
+    await write('H.md', 'h\n');
+    const change = await loud.commitFile(WS, USER, `${KB}/H.md`);
+    expect(change?.sha).toMatch(/^[0-9a-f]{40}$/);
+    expect(await gitOut(repo, ['status', '--porcelain'])).toBe('');
+    expect(others.map((c) => c.paths)).toEqual([[`${KB}/H.md`]]);
+  });
+});

package/src/modules/version-control/git/__tests__/git.service.mergeChangeRequest.test.ts

@@ -5,10 +5,12 @@ import { promisify } from 'node:util';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
-import type { AuthUser } from '@bevel-software/platform-shared';
-import type { WorkspaceService } from '../../../workspace/workspace.service.js';
+import type { AuthUser, FilesChange } from '@bevel-software/platform-shared';
+import type { WorkspaceService } from '../../../workspace/index.js';
+import type { IGitRunner } from '../../../../shared/git.contract.js';
 import { VersionControlHooks } from '../../version-control-hooks.js';
 import { GitService } from '../git.service.js';
+import { NodeGitRunner } from '../node-git-runner.js';
 import { mergeCommitSubject } from '../merge-commit.js';
 
 const execFileAsync = promisify(execFile);
@@ -119,6 +121,81 @@ describe('GitService.mergeChangeRequest', () => {
     expect(log).toContain('Add feature (#1)');
   });
 
+  describe('reports the merge it lands through onCommitLanded, once, with every path it brought in', () => {
+    const KB = 'knowledge-base';
+    const sorted = (changes: FilesChange[]) => changes.map((c) => ({ ...c, paths: [...c.paths].sort() }));
+    function listening(baseWsId: string, baseRepo: string, runner?: IGitRunner) {
+      const hooks = new VersionControlHooks();
+      const landed: FilesChange[] = [];
+      hooks.onCommitLanded((change) => landed.push(change));
+      const git = new GitService(stubWorkspaceService(baseWsId, baseRepo), hooks, testKbContext(), undefined, null, runner);
+      return { git, landed };
+    }
+
+    it('names both ends of a rename and a non-ASCII name verbatim, after the push landed', async () => {
+      const { upstream, baseWsId, baseRepo } = await seed(root, { 'base.md': 'base\n', 'keep.md': 'keep\n' });
+      await pushFeatureBranch(root, upstream, 'alice/rename', async (dir) => {
+        await runGit(dir, ['mv', 'base.md', 'renamed.md']);
+        await fs.writeFile(path.join(dir, 'Ünïcode ñ.md'), 'ü\n');
+      });
+      const { git, landed } = listening(baseWsId, baseRepo);
+
+      const result = await git.mergeChangeRequest(baseWsId, 'alice/rename', BASE, { subject: 'Rename (#2)', body: '' }, USER);
+
+      expect(result.kind).toBe('merged');
+      expect(sorted(landed)).toEqual([
+        { workspaceId: baseWsId, branch: BASE, byUser: USER, paths: [`${KB}/base.md`, `${KB}/renamed.md`, `${KB}/Ünïcode ñ.md`] },
+      ]);
+    });
+
+    it('reports nothing when there was nothing to merge', async () => {
+      const { upstream, baseWsId, baseRepo } = await seed(root, { 'base.md': 'base\n' });
+      await pushFeatureBranch(root, upstream, 'alice/add', async (dir) => {
+        await fs.writeFile(path.join(dir, 'feature.md'), 'new content\n');
+      });
+      const { git, landed } = listening(baseWsId, baseRepo);
+      await git.mergeChangeRequest(baseWsId, 'alice/add', BASE, { subject: 'Add (#3)', body: '' }, USER);
+      expect(landed).toHaveLength(1);
+
+      // Again: the target already holds the source; no commit, no report.
+      const again = await git.mergeChangeRequest(baseWsId, 'alice/add', BASE, { subject: 'Add (#3)', body: '' }, USER);
+      expect(again.kind).toBe('merged');
+      expect(landed).toHaveLength(1);
+    });
+
+    it('reports once when the first push is rejected and the retry lands — the attempt that was reset away is not announced', async () => {
+      const { upstream, seedDir, baseWsId, baseRepo } = await seed(root, { 'base.md': 'base\n' });
+      await pushFeatureBranch(root, upstream, 'alice/add', async (dir) => {
+        await fs.writeFile(path.join(dir, 'feature.md'), 'new content\n');
+      });
+      // A runner like the real one, except that just before the first push a
+      // teammate's commit lands on the target, so that push is rejected and
+      // the merge is redone on the new tip.
+      const real = new NodeGitRunner();
+      let pushes = 0;
+      const racing: IGitRunner = {
+        defaultTimeoutMs: real.defaultTimeoutMs,
+        credentials: real.credentials,
+        run: (async (cwd: string, args: string[], opts?: unknown) => {
+          if (args[0] === 'push' && pushes++ === 0) {
+            await fs.writeFile(path.join(seedDir, 'teammate.md'), 'meanwhile\n');
+            await runGit(seedDir, ['add', '-A']);
+            await runGit(seedDir, ['commit', '-m', 'teammate']);
+            await runGit(seedDir, ['push', 'origin', BASE]);
+          }
+          return real.run(cwd, args, opts as never);
+        }) as IGitRunner['run'],
+      };
+      const { git, landed } = listening(baseWsId, baseRepo, racing);
+
+      const result = await git.mergeChangeRequest(baseWsId, 'alice/add', BASE, { subject: 'Add (#4)', body: '' }, USER);
+
+      expect(result.kind).toBe('merged');
+      expect(pushes).toBe(2);
+      expect(sorted(landed)).toEqual([{ workspaceId: baseWsId, branch: BASE, byUser: USER, paths: [`${KB}/feature.md`] }]);
+    });
+  });
+
   // cubic P1 on #347. When the target already contains the source there is
   // nothing to merge, so no commit is written and `sha` is the TARGET TIP —
   // whatever landed on the target last, which in a deployment that lands

package/src/modules/version-control/git/git.service.ts

@@ -344,6 +344,36 @@ export class GitService implements IGitService {
     return this.kb.kbDirName;
   }
 
+  /**
+   * Every commit this service lands is reported here, once, to the hooks the
+   * composition root registered (`VersionControlHooks.onCommitLanded`): a
+   * single-file commit, a batch, a merge. Paths go out workspace-relative, as
+   * the notifier's contract has them. The hooks run isolated, so a reactor can
+   * neither fail nor unwind the commit it hears of. This is the ONE place a
+   * commit is announced from — a new way of committing reports here or it is
+   * not announced at all, which a test pins.
+   */
+  private landed(workspaceId: string, branch: string, user: AuthUser, repoRelativePaths: readonly string[]): void {
+    this.hooks.commitLanded({
+      workspaceId,
+      branch,
+      paths: repoRelativePaths.map((p) => `${this.kbDirName}/${p}`),
+      byUser: user,
+    });
+  }
+
+  /**
+   * The files the commit at HEAD changed, repo-relative, read from the commit
+   * itself rather than from the status listing that preceded it: every file
+   * of a new folder (status shows the folder), both ends of a rename (status
+   * shows one entry). A read that fails must not lose the report, so callers
+   * fall back to what they knew before the commit.
+   */
+  private async committedPaths(cwd: string): Promise<string[]> {
+    const { stdout } = await this.git(cwd, ['diff-tree', '--root', '--no-commit-id', '--name-only', '--no-renames', '-r', '-z', 'HEAD']);
+    return stdout.split('\0').filter(Boolean);
+  }
+
   /**
    * The credentials the runner authenticates with — for the services above
    * this one that scrub a message git or the host echoed a token into.
@@ -1082,6 +1112,10 @@ export class GitService implements IGitService {
         args.push('-m', req.description.trim());
       }
       await this.git(cwd, args);
+      // The commit exists from here on: reported now, before the attribution
+      // read, which can fail without unmaking it — with the files the commit
+      // holds, or the status listing if even that read fails.
+      this.landed(workspaceId, branch, user, await this.committedPaths(cwd).catch(() => touched));
 
       const { stdout } = await this.git(cwd, [
         'log',
@@ -1246,6 +1280,10 @@ export class GitService implements IGitService {
         `--author=${user.name} <${user.email}>`,
         '-m', subject,
       ]);
+      // The commit exists from here on: reported now, before the attribution
+      // read, which can fail without unmaking it — with the files the commit
+      // holds (the one path, as it was staged), or that path if the read fails.
+      this.landed(workspaceId, branch, user, await this.committedPaths(cwd).catch(() => [repoRelativePath]));
 
       const { stdout } = await this.git(cwd, [
         'log',
@@ -1383,6 +1421,10 @@ export class GitService implements IGitService {
       // committed" and restore their pre-edit bytes, which here would publish
       // a compensating revert of a commit that DID land. The attribution read
       // is best-effort; on failure fall back to what we already know.
+      // The commit exists: report it, with the files it holds — both ends of a
+      // rename, every file of a new folder — or the scoped status listing if
+      // that read fails. Neither the read nor the hooks can throw here.
+      this.landed(workspaceId, branch, user, await this.committedPaths(cwd).catch(() => touched));
       let sha = '';
       let authorName = user.name;
       let authorEmail = user.email;
@@ -1811,8 +1853,13 @@ export class GitService implements IGitService {
     opts: { subject: string; body: string; publish?: (ops: ReservedPushOps) => Promise<void> },
     resolvedPaths: string[],
   ): Promise<MergeIntoBranchOutcome> {
+    // What this merge brings onto the branch: the index holds the merged tree.
+    // NUL-delimited and with renames as a delete plus an add, so every path is
+    // named verbatim, both ends of a rename included.
+    const { stdout: merged } = await this.git(cwd, ['diff', '--cached', '--name-only', '--no-renames', '-z']);
     await this.git(cwd, ['commit', `--author=${user.name} <${user.email}>`, '-m', opts.subject, '-m', opts.body]);
     this.accessControl?.invalidate(workspaceId);
+    this.landed(workspaceId, branch, user, merged.split('\0').filter(Boolean));
     // The publish runs here, inside the reservation the merge was made in,
     // over this checkout's own push and pull-rebase (the merge kept as a
     // merge) — the caller's policy, the git layer's moves. Whatever it
@@ -2124,8 +2171,10 @@ export class GitService implements IGitService {
         // finalize the row (a transient database fault between the push and the
         // update) has one, and it is the only place its file list survives — so
         // it is looked for rather than assumed absent (cubic P2 on #347).
-        const { stdout: staged } = await this.git(cwd, ['diff', '--cached', '--name-only']);
-        if (staged.trim() === '') {
+        // NUL-delimited and with renames as a delete plus an add, so every path
+        // the merge touches is named verbatim, both ends of a rename included.
+        const { stdout: staged } = await this.git(cwd, ['diff', '--cached', '--name-only', '--no-renames', '-z']);
+        if (staged === '') {
           const { stdout: sha } = await this.git(cwd, ['rev-parse', 'HEAD']);
           await this.git(cwd, ['merge', '--abort']).catch(() => undefined);
           const own =
@@ -2145,6 +2194,10 @@ export class GitService implements IGitService {
 
         try {
           await this.git(cwd, ['push', 'origin', `HEAD:refs/heads/${targetBranch}`]);
+          // This merge commit is provisional until its push lands: a rejected
+          // push resets the checkout and the next attempt commits anew. So it
+          // is reported here, once, for the attempt that landed on the target.
+          this.landed(baseWorkspaceId, targetBranch, user, staged.split('\0').filter(Boolean));
           this.accessControl?.invalidate(baseWorkspaceId);
           // A commit of this request's own, with the subject the reader verifies.
           return { kind: 'merged' as const, sha: sha.trim(), mergeCommit: sha.trim() };

package/src/modules/version-control/version-control-hooks.ts

@@ -1,4 +1,8 @@
-import type { AuthUser, ValidationReport } from '@bevel-software/platform-shared';
+import type { AuthUser, FilesChange, ValidationReport } from '@bevel-software/platform-shared';
+import { callFireAndForget, type FireAndForgetListener } from '../../shared/fire-and-forget.js';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('version-control');
 
 /**
  * Version-control lifecycle hooks — the generic seam that replaced the
@@ -7,7 +11,17 @@ import type { AuthUser, ValidationReport } from '@bevel-software/platform-shared
  * composition root, right after `createCoreServices` returns. Core registers
  * none, so a core-only deployment runs every hook point as a no-op.
  *
- * Three hook kinds, with deliberately different failure semantics:
+ * Four hook kinds, with deliberately different failure semantics:
+ *
+ *   - `commitLanded` — INFORMATIONAL. Runs in `GitService` when a commit it
+ *     made is final: right after `git commit` for a save, an autosave
+ *     checkpoint, a batch, a branch merge and a `commit_change`; after the
+ *     push lands for a change-request merge, whose commit is redone on the new
+ *     tip if the push is rejected because the target advanced (any other
+ *     refusal throws, and nothing is reported). Carries the commit's
+ *     workspace-relative paths and the person. The one place a commit is reported from; the composition root
+ *     hands it to the file-change notifier. A hook that throws, or whose
+ *     promise rejects, is logged and can neither fail nor unwind the commit.
  *
  *   - `commitValidation` — ADVISORY. Runs at commit time in `GitService`
  *     (`commit` / `commitFile`), exactly where the injected `IKbValidator`
@@ -82,6 +96,15 @@ export type AgentReadHook = (ctx: AgentOperationContext) => Promise<void>;
 /** Blocking pre-write hook: throw to refuse the write; return to allow. */
 export type PreWriteHook = (ctx: AgentOperationContext) => Promise<void>;
 
+/**
+ * Told of every commit the git service lands — a single-file save, an autosave
+ * checkpoint, a batch, a merge, a `commit_change` — when it lands: pushed, or
+ * awaiting its push. The one place a commit is reported from, so no committer
+ * can be forgotten; the composition root hands it to the file-change notifier.
+ * Fire-and-forget: a hook may answer a promise, which nobody awaits.
+ */
+export type CommitLandedHook = FireAndForgetListener<FilesChange>;
+
 /**
  * The registry instance. ONE per composition (created in
  * `createCoreServices`, shared by `GitService` and exposed as
@@ -91,6 +114,7 @@ export class VersionControlHooks {
   private readonly commitValidation: CommitValidationHook[] = [];
   private readonly agentRead: AgentReadHook[] = [];
   private readonly preWrite: PreWriteHook[] = [];
+  private readonly commitLandedHooks: CommitLandedHook[] = [];
 
   /** Register an advisory commit-time validation hook. */
   onCommitValidation(hook: CommitValidationHook): void {
@@ -107,6 +131,21 @@ export class VersionControlHooks {
     this.preWrite.push(hook);
   }
 
+  onCommitLanded(hook: CommitLandedHook): void {
+    this.commitLandedHooks.push(hook);
+  }
+
+  /**
+   * Report a landed commit to every hook, each isolated: a reactor that throws,
+   * or whose promise rejects, is logged and cannot fail — or unwind — the
+   * commit it was told of.
+   */
+  commitLanded(change: FilesChange): void {
+    for (const hook of this.commitLandedHooks) {
+      callFireAndForget(hook, change, log, 'a commit-landed hook failed:');
+    }
+  }
+
   /**
    * The registered commit-validation hooks, for the caller (`GitService`) to
    * iterate with its own advisory catch-and-log semantics.

package/src/modules/version-control/version-control.service.ts

@@ -83,7 +83,6 @@ import { canonicalFileIdentity } from '../../shared/canonical-file-identity.js';
 import type { PendingCommitsService } from './pending-commits.service.js';
 import type { VersionControlEventBus } from './event-bus.js';
 import { describeSyncFailure, sanitizeError } from './sanitize-error.js';
-import type { FileChangeNotifier } from '../kb-fs/index.js';
 import { VersionControlHooks } from './version-control-hooks.js';
 import {
   ChangeRequestHooks,
@@ -304,13 +303,6 @@ export class VersionControlService implements IVersionControlService {
      * boot the composition root always wires one.
      */
     private readonly events?: VersionControlEventBus,
-    /**
-     * In-process post-commit hook (distinct from the SSE `events` bus): fires
-     * after a file's change is committed + pushed so backend services (catalog
-     * invalidation, id-repair) react without the per-file TTL wait. Optional,
-     * like `events`.
-     */
-    private readonly fileChanges?: FileChangeNotifier,
     /**
      * Version-control lifecycle-hook registry (see `version-control-hooks.ts`). PUBLIC so
      * the composition root registers module-owned behavior against it
@@ -1777,11 +1769,14 @@ export class VersionControlService implements IVersionControlService {
       // which is exactly how a diverged workspace ends up stuck forever.
       // So: if the branch is ahead of its remote-tracking ref, push (with
       // the same cooperative recovery, so a conflicting divergence throws
-      // and the worker's ladder takes over). Nothing to emit either way —
+      // and the worker's ladder takes over). No `file-changed` either way —
       // there's no new sha.
       if (await this.git.hasUnpushedCommits(workspaceId)) {
         await this.pushWithRecovery(workspaceId, branch, targetPath, user, opts);
       }
+      // Nothing landed here, so nothing is announced: the git layer reports
+      // each commit as it lands (an autosave checkpoint, a batch whose push
+      // retry this row is), and this row made none.
       return;
     }
     await this.pushWithRecovery(workspaceId, branch, targetPath, user, opts);
@@ -1794,9 +1789,6 @@ export class VersionControlService implements IVersionControlService {
       byUserId: user.id,
       byUserName: user.name,
     });
-    // Post-commit, post-lock-release: the one chokepoint every single-file write
-    // converges on. Backend reactors (catalog invalidation, id-repair) hook here.
-    this.fileChanges?.emit({ workspaceId, branch, paths: [targetPath], byUser: user });
   }
 
   /**

package/src/shared/__tests__/fire-and-forget.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+import { capturingLogger } from '../../__tests__/capturing-logger.js';
+import { callFireAndForget } from '../fire-and-forget.js';
+
+const settled = () => new Promise<void>((resolve) => setImmediate(resolve));
+const FAILED = 'a listener failed:';
+
+describe('callFireAndForget — nothing a listener does reaches the caller', () => {
+  it('a listener that throws is logged as failed, and the call returns', () => {
+    const { logger, lines } = capturingLogger();
+    expect(() =>
+      callFireAndForget(
+        () => {
+          throw new Error('reactor exploded');
+        },
+        'event',
+        logger,
+        FAILED,
+      ),
+    ).not.toThrow();
+    expect(lines).toEqual([{ level: 'error', message: FAILED, fields: { err: expect.objectContaining({ message: 'reactor exploded' }) } }]);
+  });
+
+  it('a listener whose promise rejects is logged as failed — a rejection the try/catch alone would miss', async () => {
+    const { logger, lines } = capturingLogger();
+    callFireAndForget(async () => Promise.reject(new Error('reactor exploded later')), 'event', logger, FAILED);
+    expect(lines).toEqual([]);
+    await settled();
+    expect(lines).toEqual([{ level: 'error', message: FAILED, fields: { err: expect.objectContaining({ message: 'reactor exploded later' }) } }]);
+  });
+
+  it('a listener that returns, or whose promise resolves, logs nothing', async () => {
+    const { logger, lines } = capturingLogger();
+    callFireAndForget(() => undefined, 'event', logger, FAILED);
+    callFireAndForget(async () => undefined, 'event', logger, FAILED);
+    await settled();
+    expect(lines).toEqual([]);
+  });
+});

package/src/shared/fire-and-forget.ts

@@ -0,0 +1,26 @@
+import type { ILogger } from './logger.contract.js';
+
+/** A listener told of something after the fact: it may answer a promise, which nobody awaits. */
+export type FireAndForgetListener<E> = (event: E) => void | Promise<void>;
+
+/**
+ * Call a fire-and-forget listener so that nothing it does reaches the caller:
+ * a throw is caught, a returned promise's rejection is caught, and either is
+ * logged as `failed`. The caller's own effect — the commit that landed, the
+ * change that was announced — stands whatever the listener does. The one way
+ * core dispatches such listeners (the commit-landed hooks, the file-change
+ * notifier), so the rule is written once; the awaited, channel-answering kind
+ * is `ListenerSeam`.
+ */
+export function callFireAndForget<E>(listener: FireAndForgetListener<E>, event: E, log: ILogger, failed: string): void {
+  try {
+    const answer: unknown = listener(event);
+    if (isPromiseLike(answer)) answer.then(undefined, (err: unknown) => log.error(failed, { err }));
+  } catch (err) {
+    log.error(failed, { err });
+  }
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return typeof value === 'object' && value !== null && typeof (value as PromiseLike<unknown>).then === 'function';
+}