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

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

@@ -8,6 +8,7 @@ import { isAbsence, type ITreeWalker, type WalkListener } from '../../shared/fs.
 import { assertOneSpecPerLine, isGitTimeout, type IGitRunner } from '../../shared/git.contract.js';
 import { hashEmail } from '../../shared/email-identity.js';
 import { NodeGitRunner } from '../workflow/git/node-git-runner.js';
+import { readRevSha } from '../kb-fs/index.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type {
   IAccessControl,
@@ -66,6 +67,11 @@ import {
   DIRECTORY_SYNC_BOT_NAME,
 } from './directory-sync-bot.js';
 
+/** A full object id, which is what every at-ref gate resolves its ref to before reading. */
+function isCommitSha(ref: string): boolean {
+  return /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(ref);
+}
+
 /**
  * What one spec of a batched read came back as: a blob's text, nothing at
  * that path, or an object that is not a file (a directory, say). The last
@@ -1370,7 +1376,13 @@ function ineligibleNamedEmailsResolved(
  * was built from (not the ref name that led there), so the per-file
  * own-entries reads that follow a gate resolve against exactly that tree.
  */
-type AtRefModel = { model: AccessModel; resolvedRef: string };
+/**
+ * A model built at a commit, with the commit it was built at and, when the
+ * tree is not too large to hold, every path the commit carries: what the
+ * own-entries reads need to tell a path that is absent at the commit (a
+ * fact, remembered) from a blob the batch could not read (never remembered).
+ */
+type AtRefModel = { model: AccessModel; resolvedRef: string; tree: ReadonlySet<string> | null };
 /**
  * One build's outcome: a model, no roles.yaml at the commit, or one that
  * doesn't parse. A git read failure is none of these: it throws
@@ -1440,6 +1452,25 @@ export class AccessControlService implements IAccessControl {
   private readonly atRefInFlight = new Map<string, Promise<AtRefBuild>>();
   private static readonly AT_REF_CACHE_MAX = 512;
 
+  /**
+   * A path's own access entries AT A COMMIT, keyed by commit + path. A blob
+   * at a commit never changes, so neither does what it declares for itself:
+   * no TTL, no invalidation, and no workspace in the key (every clone holds
+   * the same objects). This is the read every at-ref gate makes after the
+   * model: one `cat-file --batch` per call for the paths asked, which a
+   * change-request listing made once per ref per listing for the same paths
+   * at the same commits. Bounded FIFO; the bound only caps memory.
+   */
+  private readonly ownEntriesAtCommit = new Map<string, OwnEntries | null>();
+  private static readonly OWN_ENTRIES_AT_COMMIT_MAX = 16_384;
+  /** Paths a cached model keeps of its commit's tree, at most; a larger tree is not kept. */
+  private static readonly TREE_INDEX_MAX_PATHS = 20_000;
+  /** Paths held across every cached model's tree, at most; past it the oldest models let their tree go. */
+  private static readonly TREE_INDEX_BUDGET = 500_000;
+  private readonly treeIndexMaxPaths: number;
+  private readonly treeIndexBudget: number;
+  private treePathsHeld = 0;
+
   /**
    * Canonicalised deployment-owner emails (see `AccessModel.deploymentOwners`).
    * Held on the service rather than read per-model because it comes from the
@@ -1473,10 +1504,19 @@ export class AccessControlService implements IAccessControl {
      * run on the default layout.
      */
     private readonly kb: Pick<KbContext, 'layout'> = { layout: DEFAULT_KB_LAYOUT },
+    /**
+     * How much of the commits' trees the at-ref models may hold (see
+     * `TREE_INDEX_MAX_PATHS`, `TREE_INDEX_BUDGET`). The defaults are the
+     * deployment's; a suite lowers them to reach the bounds with a small
+     * repository.
+     */
+    limits: { treeIndexMaxPaths?: number; treeIndexBudget?: number } = {},
   ) {
     this.deploymentOwners = new Set(
       deploymentOwners.filter(Boolean).map((e) => canonicalEmail(e)),
     );
+    this.treeIndexMaxPaths = limits.treeIndexMaxPaths ?? AccessControlService.TREE_INDEX_MAX_PATHS;
+    this.treeIndexBudget = limits.treeIndexBudget ?? AccessControlService.TREE_INDEX_BUDGET;
   }
 
   /**
@@ -1618,6 +1658,23 @@ export class AccessControlService implements IAccessControl {
     return result;
   }
 
+  async groupsOfUser(workspaceId: string, userEmail: string): Promise<string[]> {
+    const model = await this.loadModel(workspaceId);
+    const email = canonicalEmail(userEmail);
+    const names: string[] = [];
+    for (const principal of model.roles.byCanonical.values()) {
+      if (principal.kind === 'group' && principal.emails.has(email)) names.push(principal.displayName);
+    }
+    return names;
+  }
+
+  async visibleGroups(workspaceId: string, userEmail: string, groups: readonly string[]): Promise<string[]> {
+    if (groups.length === 0) return [];
+    if (await this.holdsAdminRootWrite(workspaceId, userEmail)) return [...groups];
+    const mine = new Set(await this.groupsOfUser(workspaceId, userEmail));
+    return groups.filter((g) => mine.has(g));
+  }
+
   async canWriteBatch(
     workspaceId: string,
     userEmail: string,
@@ -2135,7 +2192,7 @@ export class AccessControlService implements IAccessControl {
     const loaded = await this.loadModelAtRef(workspaceId, ref);
     if (!loaded) return null;
     const repoDir = await this.repoDir(workspaceId);
-    const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath);
+    const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath, loaded.tree);
     return hasPermissionResolved(loaded.model, 'write', userEmail, relativePath, own);
   }
 
@@ -2148,7 +2205,7 @@ export class AccessControlService implements IAccessControl {
     const loaded = await this.loadModelAtRef(workspaceId, ref);
     if (!loaded) return null;
     const repoDir = await this.repoDir(workspaceId);
-    const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath);
+    const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath, loaded.tree);
     return canReadResolved(loaded.model, userEmail, relativePath, own);
   }
 
@@ -2171,7 +2228,7 @@ export class AccessControlService implements IAccessControl {
     const repoDir = await this.repoDir(workspaceId);
     // One `git cat-file --batch` for the whole path set — a per-path `git
     // show` spawn made CR owner-routing take minutes on large change sets.
-    const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths);
+    const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths, loaded.tree);
     const result = new Map<string, boolean>();
     for (const p of relativePaths) {
       const machineOwned = machineAnswers.get(p);
@@ -2196,7 +2253,7 @@ export class AccessControlService implements IAccessControl {
     if (!loaded) return null;
     const repoDir = await this.repoDir(workspaceId);
     // One `git cat-file --batch` for the whole set — see canWriteBatchAtRef.
-    const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths);
+    const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths, loaded.tree);
     const result = new Map<string, boolean>();
     for (const p of relativePaths) {
       result.set(p, canReadResolved(loaded.model, userEmail, p, owns.get(p) ?? null));
@@ -2219,7 +2276,7 @@ export class AccessControlService implements IAccessControl {
     const loaded = await this.loadModelAtRef(workspaceId, ref);
     if (!loaded) return null;
     const repoDir = await this.repoDir(workspaceId);
-    const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath);
+    const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath, loaded.tree);
     return eligibleHoldersResolved(loaded.model, 'write', relativePath, own);
   }
 
@@ -2333,7 +2390,7 @@ export class AccessControlService implements IAccessControl {
     if (!loaded) return null;
     const repoDir = await this.repoDir(workspaceId);
     // One `git cat-file --batch` for the whole path set — see canWriteBatchAtRef.
-    const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths);
+    const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths, loaded.tree);
     for (const p of relativePaths) {
       if (result.has(p)) continue;
       const own = owns.get(p) ?? null;
@@ -2551,8 +2608,14 @@ export class AccessControlService implements IAccessControl {
     repoDir: string,
     ref: string,
     relativePath: string,
+    tree: ReadonlySet<string> | null = null,
   ): Promise<OwnEntries | null> {
     if (relativePath === 'roles.yaml') return null;
+    // At a commit (what every gate passes: `resolvedRef`), the batched read
+    // and its memo answer; a single `git show` stays for a symbolic ref.
+    if (isCommitSha(ref)) {
+      return (await this.readOwnEntriesAtRefBatch(repoDir, ref, [relativePath], tree)).get(relativePath) ?? null;
+    }
     const text = await this.showAtRef(repoDir, ref, relativePath);
     if (text === null) return null;
     if (isAccessMdPath(relativePath)) return accessMdSelfEntries(text);
@@ -2571,23 +2634,60 @@ export class AccessControlService implements IAccessControl {
     repoDir: string,
     ref: string,
     relativePaths: string[],
+    tree: ReadonlySet<string> | null = null,
   ): Promise<Map<string, OwnEntries | null>> {
     const result = new Map<string, OwnEntries | null>();
     const wanted: string[] = [];
+    const memo = isCommitSha(ref) ? this.ownEntriesAtCommit : null;
     for (const p of relativePaths) {
-      if (p === 'roles.yaml') result.set(p, null);
-      else if (!wanted.includes(p)) wanted.push(p);
+      if (p === 'roles.yaml') {
+        result.set(p, null);
+        continue;
+      }
+      const key = `${ref}\0${p}`;
+      if (memo?.has(key)) {
+        result.set(p, memo.get(key) ?? null);
+        continue;
+      }
+      // A path the commit's tree does not carry has no own entries, as a
+      // fact about the commit: remembered, and not read. (A change request
+      // that adds a file asks about it at the base, where it does not exist
+      // yet; one that deletes a file asks at the head.)
+      if (tree && !tree.has(p)) {
+        result.set(p, null);
+        if (memo) this.rememberOwnEntriesAtCommit(key, null);
+        continue;
+      }
+      if (!wanted.includes(p)) wanted.push(p);
     }
     if (wanted.length === 0) return result;
     const texts = await catFileBatch(this.gitRunner, repoDir, wanted.map((p) => `${ref}:${p}`));
     wanted.forEach((p, i) => {
       const text = texts[i];
-      if (text === null) result.set(p, null);
-      else result.set(p, isAccessMdPath(p) ? accessMdSelfEntries(text) : parseOwnAccessEntries(text));
+      if (text === null) {
+        // Absent at the commit (when no tree was there to say so first), or
+        // a blob git could not read: the batch says "missing" for both, and
+        // only the first is a fact about the commit. Answered as no own
+        // entries, as before, but never remembered.
+        result.set(p, null);
+        return;
+      }
+      const own = isAccessMdPath(p) ? accessMdSelfEntries(text) : parseOwnAccessEntries(text);
+      result.set(p, own);
+      // What a blob declares for itself — including nothing — is a fact about the commit.
+      if (memo) this.rememberOwnEntriesAtCommit(`${ref}\0${p}`, own);
     });
     return result;
   }
 
+  private rememberOwnEntriesAtCommit(key: string, value: OwnEntries | null): void {
+    this.ownEntriesAtCommit.set(key, value);
+    if (this.ownEntriesAtCommit.size > AccessControlService.OWN_ENTRIES_AT_COMMIT_MAX) {
+      const oldest = this.ownEntriesAtCommit.keys().next().value;
+      if (oldest !== undefined) this.ownEntriesAtCommit.delete(oldest);
+    }
+  }
+
   /**
    * Resolve a candidate ref to one git accepts. Falls back to `origin/<ref>`
    * for short branch names, matching the heuristic in
@@ -2649,11 +2749,12 @@ export class AccessControlService implements IAccessControl {
   private async listAccessFilesAtRef(
     repoDir: string,
     ref: string,
-  ): Promise<{ accessFiles: string[]; pluginDirs: string[]; named: Set<string> } | 'error'> {
+  ): Promise<{ accessFiles: string[]; pluginDirs: string[]; named: Set<string>; all: string[] } | 'error'> {
     try {
       const { stdout } = await this.gitRunner.run(repoDir, ['ls-tree', '-r', '-z', '--name-only', ref]);
       const out: string[] = [];
       const pluginDirs: string[] = [];
+      const all: string[] = [];
       // The fixed-name sources the tree carries (roles.yaml, the groups
       // files): a read of one of these that comes back empty is "absent"
       // only when the tree does not name it.
@@ -2661,13 +2762,15 @@ export class AccessControlService implements IAccessControl {
       const { pluginsDir } = this.kb.layout;
       for (const p of stdout.split('\0')) {
         if (!p) continue;
+        // One past the cap is enough to know the tree is not kept.
+        if (all.length <= this.treeIndexMaxPaths) all.push(p);
         if (p === 'access.md' || p.endsWith('/access.md')) out.push(p);
         else if (p === 'roles.yaml' || p === SYNCED_GROUPS_YAML || p === GROUPS_YAML) named.add(p);
         else if (p.startsWith(`${pluginsDir}/`) && p.endsWith(`/${PLUGIN_MANIFEST_FILE}`)) {
           pluginDirs.push(p.slice(0, -(PLUGIN_MANIFEST_FILE.length + 1)));
         }
       }
-      return { accessFiles: out, pluginDirs, named };
+      return { accessFiles: out, pluginDirs, named, all };
     } catch {
       return 'error';
     }
@@ -2742,6 +2845,14 @@ export class AccessControlService implements IAccessControl {
   /** The commit `ref` points at in this clone, or null when it doesn't resolve. */
   private async revParseCommit(repoDir: string, ref: string): Promise<string | null> {
     if (!ref || ref.startsWith('-')) return null;
+    // The ref files first (`readRevSha`): the names git would try, in git's
+    // order, read without a process. "Missing" from the files is what
+    // rev-parse answers nothing for; "unreadable" — a spelling the reader
+    // does not resolve, a tag it cannot peel, a file it could not read — is
+    // git's to decide, as the authority.
+    const fromFiles = await readRevSha(repoDir, ref);
+    if (fromFiles === 'missing') return null;
+    if (fromFiles !== 'unreadable') return fromFiles.sha;
     try {
       const { stdout } = await this.gitRunner.run(repoDir, [
         'rev-parse',
@@ -2762,9 +2873,22 @@ export class AccessControlService implements IAccessControl {
 
   private rememberAtRef(key: string, value: AtRefModel): void {
     this.atRefCache.set(key, value);
+    this.treePathsHeld += value.tree?.size ?? 0;
     if (this.atRefCache.size > AccessControlService.AT_REF_CACHE_MAX) {
       const oldest = this.atRefCache.keys().next().value;
-      if (oldest !== undefined) this.atRefCache.delete(oldest);
+      if (oldest !== undefined) {
+        this.treePathsHeld -= this.atRefCache.get(oldest)?.tree?.size ?? 0;
+        this.atRefCache.delete(oldest);
+      }
+    }
+    // The trees are a budget of their own, across every held model: past
+    // it, the oldest models keep their model and let their tree go — the
+    // gate still answers, absence is just no longer remembered for them.
+    for (const held of this.atRefCache.values()) {
+      if (this.treePathsHeld <= this.treeIndexBudget) break;
+      if (!held.tree) continue;
+      this.treePathsHeld -= held.tree.size;
+      held.tree = null;
     }
   }
 
@@ -2940,6 +3064,10 @@ export class AccessControlService implements IAccessControl {
         deploymentOwners: this.deploymentOwners,
       },
       resolvedRef: commit,
+      // The listing already named every path; held so an own-entries read
+      // can tell absence from a lost blob, unless the tree is too large to
+      // hold for every cached commit (then absence is simply not remembered).
+      tree: listed.all.length <= this.treeIndexMaxPaths ? new Set(listed.all) : null,
     };
   }
 }

package/src/modules/access/access.routes.ts

@@ -128,6 +128,18 @@ export function createAccessRoutes(
     return { roles, groups, plugins: plugins ?? [] };
   };
 
+  /**
+   * The groups `email` may be offered as a grantee, or name in a grant: the
+   * resolver's ONE answer to who sees which group (`visibleGroups`: every
+   * group for an admin, only their own for anyone else), the same the
+   * Library's Groups tab lists. Read on the default branch, where the active
+   * group source lives. The picker never names a group the caller has no
+   * part in, and the grant route refuses one with the same words as a group
+   * that does not exist.
+   */
+  const visibleGroups = (email: string, groups: string[]): Promise<string[]> =>
+    accessControl.visibleGroups(kb.defaultWorkspaceId(), email, groups);
+
   /**
    * The plugins `email` may DISCOVER — read the folder's access.md, the same
    * verdict the plugin index lists on. Both the suggest list and the grant
@@ -491,8 +503,9 @@ export function createAccessRoutes(
    * names — resolved from the DEFAULT branch, the authoritative source),
    * groups (the ACTIVE group source, same authority), and people (branch-local
    * to `:id`). Roles/groups come from the resolver's CACHED model — no fresh
-   * file reads per keystroke. Roles + groups are small + non-sensitive so they
-   * always show; PEOPLE are withheld until `q` is ≥ 2 chars, so an empty query
+   * file reads per keystroke. Roles are small + non-sensitive so they always
+   * show; GROUPS are the caller's own unless they are an admin (see
+   * `visibleGroups`); PEOPLE are withheld until `q` is ≥ 2 chars, so an empty query
    * can't dump the whole directory (email-harvesting guard). People are the
    * union of the KB-canonical set (roles.yaml + access.md grants) and the
    * `users` table (logged-in users). Results are capped. Each person carries
@@ -527,7 +540,7 @@ export function createAccessRoutes(
         .filter((g) => !q || g.toLowerCase().includes(q))
         .slice(0, CAP);
 
-      const matchedGroups = groups
+      const matchedGroups = (await visibleGroups(user.email, groups))
         .filter((g) => !q || g.toLowerCase().includes(q))
         .slice(0, CAP);
 
@@ -934,9 +947,12 @@ export function createAccessRoutes(
       } else if (principal.kind === 'group') {
         // A group grant must name a group in the ACTIVE source (IdP-synced or
         // manual) on the default branch — same authority the suggest list
-        // uses. No role-collision refusal: bare tokens resolve GROUP-FIRST,
-        // so the written bare name IS the group.
-        const { groups } = await defaultBranchPrincipals();
+        // uses — and one the caller may see (`visibleGroups`): a group hidden
+        // from the picker is refused here with the same words as one that
+        // does not exist, so the grant route is no oracle for group names.
+        // No role-collision refusal: bare tokens resolve GROUP-FIRST, so the
+        // written bare name IS the group.
+        const groups = await visibleGroups(user.email, (await defaultBranchPrincipals()).groups);
         const canonical = canonicalRoleName(principal.group);
         if (!groups.some((g) => canonicalRoleName(g) === canonical)) {
           throw new AccessMutationError(

package/src/modules/agent-instructions/shared-file-rules.ts

@@ -3,7 +3,7 @@
  *
  * They used to be appended, in full, to every tool description that they
  * covered: the content rule rode on all twelve file tools, the agent-guide
- * reminder on all of them plus the shell, the write-mode and escape-sequence
+ * reminder on all of them, the write-mode and escape-sequence
  * paragraphs on two or three apiece. A description then ran to two or three
  * thousand characters, most of it text the agent had already read on the tool
  * above — and clients cut long descriptions from the END, which is where the

package/src/modules/diff/__tests__/diff.service.seed-atomicity.test.ts

@@ -8,6 +8,7 @@ import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { WorkspaceMutex } from '../../kb-fs/mutex.js';
 import { DiffService } from '../diff.service.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
+import { newWorkspaceService } from '../../../__tests__/workspace-service.js';
 
 /**
  * Atomic-seed regression suite.
@@ -53,7 +54,7 @@ async function setup(): Promise<Fixture> {
   const workspaceDir = path.join(workspacesRoot, workspaceId);
   const repoDir = path.join(workspaceDir, 'knowledge-base');
   await fs.mkdir(path.join(repoDir, '.git'), { recursive: true });
-  const workspaceService = new WorkspaceService(
+  const workspaceService = newWorkspaceService(
     workspacesRoot,
     'https://github.com/Bevel-Software/knowledge-base.git',
     testKbContext(),

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

@@ -8,6 +8,7 @@ import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { WorkspaceMutex } from '../../kb-fs/mutex.js';
 import { DiffService } from '../diff.service.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
+import { newWorkspaceService } from '../../../__tests__/workspace-service.js';
 
 async function mkTmpRoot(prefix: string): Promise<string> {
   return fs.mkdtemp(path.join(os.tmpdir(), prefix));
@@ -39,7 +40,7 @@ async function setup(): Promise<Fixture> {
   const repoDir = path.join(workspaceDir, 'knowledge-base');
   // Inner `.git` dir is the marker `resolveWorkspaceDir` looks for.
   await fs.mkdir(path.join(repoDir, '.git'), { recursive: true });
-  const workspaceService = new WorkspaceService(
+  const workspaceService = newWorkspaceService(
     workspacesRoot,
     'https://github.com/Bevel-Software/knowledge-base.git',
     testKbContext(),

package/src/modules/diff/__tests__/diff.service.worktree.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import { WorkspaceMutex } from '../../kb-fs/mutex.js';
+import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+import { DiffService } from '../diff.service.js';
+import { newWorkspaceService } from '../../../__tests__/workspace-service.js';
+
+/**
+ * The review session names the branch the workspace is on, read from HEAD
+ * without spawning git. In a worktree `.git` is a FILE naming the worktree's
+ * folder in the repository, where its HEAD lives.
+ */
+
+const execFileAsync = promisify(execFile);
+
+async function git(cwd: string, args: string[]): Promise<void> {
+  await execFileAsync('git', args, {
+    cwd,
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: 'Test', GIT_AUTHOR_EMAIL: 't@x.com',
+      GIT_COMMITTER_NAME: 'Test', GIT_COMMITTER_EMAIL: 't@x.com',
+    },
+  });
+}
+
+let root: string;
+
+beforeEach(async () => {
+  root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-diff-worktree-'));
+});
+afterEach(async () => {
+  await fs.rm(root, { recursive: true, force: true });
+});
+
+describe('DiffService on a worktree', () => {
+  it("names the worktree's own branch in the review session", async () => {
+    const upstream = path.join(root, 'upstream.git');
+    await git(root, ['init', '--bare', '-b', 'main', upstream]);
+    const seed = path.join(root, '.seed');
+    await fs.mkdir(seed);
+    await git(seed, ['init', '-b', 'alice/draft']);
+    await fs.writeFile(path.join(seed, 'page.md'), 'before\n');
+    await git(seed, ['add', '-A']);
+    await git(seed, ['commit', '-m', 'init']);
+    await git(seed, ['push', '-q', upstream, 'alice/draft']);
+
+    const workspacesRoot = path.join(root, 'workspaces');
+    const workspaces = newWorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs());
+    const diff = new DiffService(
+      workspaces,
+      new WorkspaceMutex(),
+      workspacesRoot,
+      path.join(root, 'backups'),
+      'knowledge-base',
+      new NodeFs(),
+    );
+    workspaces.setDiffService(diff);
+    const workspaceId = workspaceIdForBranch('alice/draft');
+    const info = await workspaces.getOrCreateForBranch('alice/draft');
+    expect((await fs.stat(path.join(info.absolutePath, 'knowledge-base', '.git'))).isFile()).toBe(true);
+
+    // The first look seeds the ledger; a change made after it is pending.
+    expect(await diff.currentSession(workspaceId)).toBeNull();
+    await fs.writeFile(path.join(info.absolutePath, 'knowledge-base', 'page.md'), 'after\n');
+
+    const session = await diff.currentSession(workspaceId);
+    expect(session?.branchName).toBe('alice/draft');
+  });
+});

package/src/modules/diff/diff.service.ts

@@ -4,6 +4,7 @@ import type { FileDiffPayload, PendingChange, ReviewSession, ChangeKind } from '
 import type { IDiffService } from './diff.interface.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type { WorkspaceMutex } from '../kb-fs/mutex.js';
+import { gitDirOf } from '../kb-fs/index.js';
 import { isAbsence, type ITreeWalker, type TreeWalkOptions } from '../../shared/fs.contract.js';
 import { isDiffable } from './diff.config.js';
 import { assertWithinDirectory } from '../../shared/path-containment.js';
@@ -385,10 +386,11 @@ export class DiffService implements IDiffService {
   private async tryReadCurrentBranch(workspaceId: string): Promise<string> {
     const workspaceDir = await this.workspaceService.getWorkspacePath(workspaceId);
     try {
-      const head = await fs.readFile(
-        path.join(workspaceDir, this.kbDirName, '.git', 'HEAD'),
-        'utf-8',
-      );
+      // A worktree's `.git` is a FILE naming its folder in the repository,
+      // where its HEAD lives; a full clone's is the folder itself.
+      const gitDir = await gitDirOf(path.join(workspaceDir, this.kbDirName));
+      if (gitDir === null) return '';
+      const head = await fs.readFile(path.join(gitDir, 'HEAD'), 'utf-8');
       const m = head.match(/^ref:\s+refs\/heads\/(.+?)\s*$/);
       return m ? m[1] : '';
     } catch {

package/src/modules/kb-fs/__tests__/git-dir.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+import { gitDirOf, readGitfile } from '../git-dir.js';
+
+const execFileAsync = promisify(execFile);
+
+async function git(cwd: string, ...args: string[]): Promise<string> {
+  const { stdout } = await execFileAsync('git', ['-C', cwd, ...args], { encoding: 'utf-8' });
+  return stdout.trim();
+}
+
+/**
+ * The one resolver of a checkout's git directory, checked against what git
+ * itself answers (`rev-parse --absolute-git-dir`) for a clone and a worktree.
+ */
+describe('gitDirOf', () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), 'git-dir-')));
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it('is the .git folder of a clone and the folder a worktree .git file names, as git says', async () => {
+    const clone = path.join(root, 'clone');
+    await fs.mkdir(clone);
+    await git(clone, 'init', '-q');
+    await git(clone, '-c', 'user.name=T', '-c', 'user.email=t@x.com', 'commit', '-q', '--allow-empty', '-m', 'c');
+    const worktree = path.join(root, 'wt');
+    await git(clone, 'worktree', 'add', '-q', '-b', 'side', worktree);
+
+    for (const dir of [clone, worktree]) {
+      const fromGit = path.resolve(await git(dir, 'rev-parse', '--absolute-git-dir'));
+      expect(path.resolve((await gitDirOf(dir))!)).toBe(await fs.realpath(fromGit));
+    }
+  });
+
+  it('is null with no .git, and with a .git file that names no folder', async () => {
+    expect(await gitDirOf(root)).toBeNull();
+    await fs.writeFile(path.join(root, '.git'), 'not a gitfile\n');
+    expect(await gitDirOf(root)).toBeNull();
+  });
+
+  it('reads exactly what git reads: `gitdir: ` and a path, nothing before, after or around it', async () => {
+    const gitfile = path.join(root, '.git');
+    for (const text of [
+      'not a gitfile\ngitdir: ../elsewhere/wt\n', // a gitdir line further down
+      'gitdir: ../elsewhere/wt\njunk\n', // a second line after the path
+      'gitdir:../elsewhere/wt\n', // no space after the colon
+      'gitdir:  ../elsewhere/wt\n', // a path that starts with a space, which exists nowhere
+      '\ngitdir: ../elsewhere/wt\n', // a blank first line
+    ]) {
+      await fs.writeFile(gitfile, text);
+      const named = await readGitfile(gitfile);
+      // Git refuses each as a gitfile; what this reads of it names no folder
+      // git would open.
+      await expect(git(root, 'rev-parse', '--absolute-git-dir')).rejects.toThrow();
+      expect(named === null || named !== path.resolve(root, '../elsewhere/wt'), JSON.stringify(text)).toBe(true);
+    }
+    await fs.writeFile(gitfile, 'gitdir: ../elsewhere/wt\r\n');
+    expect(await readGitfile(gitfile)).toBe(path.resolve(root, '../elsewhere/wt'));
+  });
+
+  it('resolves a relative gitdir against the file’s own folder', async () => {
+    await fs.writeFile(path.join(root, '.git'), 'gitdir: ../elsewhere/wt\n');
+    expect(await readGitfile(path.join(root, '.git'))).toBe(path.resolve(root, '../elsewhere/wt'));
+    expect(await gitDirOf(root)).toBe(path.resolve(root, '../elsewhere/wt'));
+  });
+});