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

package/src/modules/audit/__tests__/audit.routes.test.ts

@@ -5,6 +5,7 @@ import { createAuditRoutes } from '../audit.routes.js';
 import {
   AuditPrincipalNotFoundError,
   InvalidCursorError,
+  pagePrincipalId,
   type AuditPrincipal,
   type IAgentAuditService,
 } from '../audit.contract.js';
@@ -31,7 +32,9 @@ const ALICE_KEY: AuditPrincipal = {
 };
 
 /** Who owns what, as the fake service answers `ownerOf`. */
-const OWNERS: Record<string, string> = { [KEY_ID]: ALICE.id, [AGENT_ID]: BOB.id, [ALICE_AGENT_ID]: ALICE.id };
+/** A page Alice's views have called tools from; its id names a person by uuid, so it is minted for one. */
+const ALICE_PAGE_ID = pagePrincipalId('33333333-4444-4555-8666-777777777777', 'Dashboards/Roadmap.html');
+const OWNERS: Record<string, string> = { [KEY_ID]: ALICE.id, [AGENT_ID]: BOB.id, [ALICE_AGENT_ID]: ALICE.id, [ALICE_PAGE_ID]: ALICE.id };
 
 const audit = {
   listPrincipals: vi.fn(async () => [ALICE_KEY]),
@@ -103,6 +106,24 @@ describe('audit routes — events', () => {
     expect(audit.listEvents).toHaveBeenCalledWith({ kind: 'key', id: KEY_ID }, { before: '123.e-9', limit: 200 });
   });
 
+  it("serves a page's events to its viewer, and 404s an id that names no page", async () => {
+    const base = await listen(makeApp({ admin: false }));
+    const res = await fetch(`${base}/api/audit/principals/page/${ALICE_PAGE_ID}/events`);
+    expect(res.status).toBe(200);
+    expect(audit.listEvents).toHaveBeenCalledWith({ kind: 'page', id: ALICE_PAGE_ID }, { before: undefined, limit: 50 });
+    const notAPage = await fetch(`${base}/api/audit/principals/page/not-a-page/events`);
+    expect(notAPage.status).toBe(404);
+    expect(await notAPage.json()).toEqual({ error: 'No such agent, key or page' });
+  });
+
+  it('404s a page id whose path carries a line break of any kind', async () => {
+    const base = await listen(makeApp({ admin: false }));
+    for (const brk of ['\n', '\r', '\u0085', '\u2028', '\u2029']) {
+      const id = pagePrincipalId('33333333-4444-4555-8666-777777777777', `Dashboards/Road${brk}map.html`);
+      expect((await fetch(`${base}/api/audit/principals/page/${id}/events`)).status).toBe(404);
+    }
+  });
+
   it('answers a cursor the service does not recognise with 400, not 500', async () => {
     const base = await listen(makeApp({ admin: false }));
     audit.listEvents.mockRejectedValueOnce(new InvalidCursorError());
@@ -110,9 +131,23 @@ describe('audit routes — events', () => {
     expect(res.status).toBe(400);
   });
 
-  it("refuses another person's principal to a member, and serves it to an admin", async () => {
-    const asAlice = await listen(makeApp({ admin: false }));
-    expect((await fetch(`${asAlice}/api/audit/principals/agent/${AGENT_ID}/events`)).status).toBe(403);
+  it("refuses another person's principal to a member exactly as one that does not exist, and serves it to an admin", async () => {
+    const asBob = await listen(makeApp({ admin: false, as: BOB }));
+    const missingPage = pagePrincipalId('33333333-4444-4555-8666-777777777777', 'Dashboards/Nothing.html');
+    const refusals = [];
+    const missing = '00000000-0000-4000-8000-000000000000';
+    for (const path of [
+      `page/${ALICE_PAGE_ID}`,
+      `page/${missingPage}`,
+      `key/${KEY_ID}`,
+      `key/${missing}`,
+      `agent/${ALICE_AGENT_ID}`,
+      `agent/${missing}`,
+    ]) {
+      const res = await fetch(`${asBob}/api/audit/principals/${path}/events`);
+      refusals.push({ status: res.status, body: await res.json() });
+    }
+    expect(refusals).toEqual(Array(6).fill({ status: 404, body: { error: 'No such agent, key or page' } }));
     expect(audit.listEvents).not.toHaveBeenCalled();
     server.close();
 
@@ -166,7 +201,10 @@ describe('audit routes — revoke an agent', () => {
   it('404s when the connection vanished between the ownership check and the revoke', async () => {
     const base = await listen(makeApp({ admin: false, as: BOB }));
     audit.revokeConnection.mockRejectedValueOnce(new AuditPrincipalNotFoundError());
-    expect((await fetch(`${base}/api/audit/agents/${AGENT_ID}`, { method: 'DELETE' })).status).toBe(404);
+    const res = await fetch(`${base}/api/audit/agents/${AGENT_ID}`, { method: 'DELETE' });
+    expect(res.status).toBe(404);
+    // Only an agent revoke throws it, so it names an agent, as the route's other 404s do.
+    expect(await res.json()).toEqual({ error: 'No such agent' });
   });
 });
 

package/src/modules/audit/agent-audit.service.ts

@@ -1,4 +1,4 @@
-import { and, count, desc, eq, isNotNull, isNull, lt, or, type SQL } from 'drizzle-orm';
+import { and, count, desc, eq, isNotNull, isNull, lt, max, min, or, type SQL } from 'drizzle-orm';
 import { logger } from '../../shared/logging.js';
 import type { Database } from '../database/connection.js';
 import { agentConnections, agentEvents, externalApiKeys, oauthTokens, users } from '../database/schema.js';
@@ -7,6 +7,8 @@ import {
   AuditPrincipalNotFoundError,
   InvalidCursorError,
   isUuid,
+  pagePrincipalId,
+  parsePagePrincipalId,
   parseRetentionWindow,
   type AgentEventInput,
   type AgentEventPage,
@@ -59,6 +61,7 @@ export class AgentAuditService implements IAgentAuditService, IAgentEventRecorde
         userId: event.userId,
         keyId: event.principal.kind === 'key' ? event.principal.id : null,
         connectionId: event.principal.kind === 'agent' ? event.principal.id : null,
+        pagePath: event.principal.kind === 'page' ? event.principal.path : null,
         kind: event.kind,
         manual: event.manual,
         name: event.name,
@@ -93,7 +96,7 @@ export class AgentAuditService implements IAgentAuditService, IAgentEventRecorde
 
   async listPrincipals(scope: AuditScope): Promise<AuditPrincipal[]> {
     const mine = scope === 'all' ? null : scope.userId;
-    const [keyRows, connectionRows, countRows] = await Promise.all([
+    const [keyRows, connectionRows, countRows, pageRows] = await Promise.all([
       mine === null ? this.keys.listForDeployment() : this.keysForUser(mine),
       this.db
         .select({
@@ -111,6 +114,22 @@ export class AgentAuditService implements IAgentAuditService, IAgentEventRecorde
         .from(agentEvents)
         .where(mine === null ? undefined : eq(agentEvents.userId, mine))
         .groupBy(agentEvents.keyId, agentEvents.connectionId),
+      // A page has no row of its own: it is every event recorded under one
+      // person and one path, so its "created" is its first call and its
+      // "last used" its latest.
+      this.db
+        .select({
+          userId: agentEvents.userId,
+          pagePath: agentEvents.pagePath,
+          n: count(),
+          first: min(agentEvents.at),
+          last: max(agentEvents.at),
+          user: { id: users.id, email: users.email, name: users.name },
+        })
+        .from(agentEvents)
+        .innerJoin(users, eq(agentEvents.userId, users.id))
+        .where(and(isNotNull(agentEvents.pagePath), mine === null ? undefined : eq(agentEvents.userId, mine)))
+        .groupBy(agentEvents.userId, agentEvents.pagePath, users.id, users.email, users.name),
     ]);
 
     const counts = new Map<string, number>();
@@ -144,6 +163,24 @@ export class AgentAuditService implements IAgentAuditService, IAgentEventRecorde
         eventCount: counts.get(c.id) ?? 0,
         user,
       })),
+      ...pageRows.flatMap((r) =>
+        r.pagePath
+          ? [
+              {
+                kind: 'page' as const,
+                id: pagePrincipalId(r.userId, r.pagePath),
+                label: r.pagePath,
+                createdAt: toMs(r.first),
+                lastUsedAt: r.last ? toMs(r.last) : null,
+                // A page cannot be revoked: it acts only while its viewer has it open.
+                revokedAt: null,
+                revokedBy: null,
+                eventCount: Number(r.n),
+                user: r.user,
+              },
+            ]
+          : [],
+      ),
     ];
     // Per account (by email), live before revoked, most recently used first,
     // newest first among the never-used — the order the page shows without
@@ -175,6 +212,17 @@ export class AgentAuditService implements IAgentAuditService, IAgentEventRecorde
   }
 
   async ownerOf(principal: AuditPrincipalRef): Promise<string | null> {
+    if (principal.kind === 'page') {
+      // The person is in the id; the page exists for them once it has called something.
+      const page = parsePagePrincipalId(principal.id);
+      if (!page) return null;
+      const [row] = await this.db
+        .select({ id: agentEvents.id })
+        .from(agentEvents)
+        .where(and(eq(agentEvents.userId, page.userId), eq(agentEvents.pagePath, page.path)))
+        .limit(1);
+      return row ? page.userId : null;
+    }
     if (principal.kind === 'agent') {
       const [row] = await this.db
         .select({ userId: agentConnections.userId })
@@ -192,10 +240,7 @@ export class AgentAuditService implements IAgentAuditService, IAgentEventRecorde
     page: { before?: string; limit: number },
   ): Promise<AgentEventPage> {
     const limit = Math.max(1, Math.min(MAX_EVENT_PAGE, Math.floor(page.limit)));
-    const byPrincipal =
-      principal.kind === 'key'
-        ? eq(agentEvents.keyId, principal.id)
-        : eq(agentEvents.connectionId, principal.id);
+    const byPrincipal = principalFilter(principal);
     // Keyset on (at, id): a page boundary between two events at the same
     // instant is still a boundary, and a row inserted while the reader pages
     // never shifts what the next page returns.
@@ -340,6 +385,21 @@ function formatCursor(at: Date, id: string): string {
  * compare it with anything else) and the instant a whole number of epoch
  * milliseconds a `timestamp` can hold.
  */
+/** The events of one principal. A page id that names no page matches nothing. */
+function principalFilter(principal: AuditPrincipalRef): SQL {
+  if (principal.kind === 'key') return eq(agentEvents.keyId, principal.id);
+  if (principal.kind === 'agent') return eq(agentEvents.connectionId, principal.id);
+  const page = parsePagePrincipalId(principal.id);
+  if (!page) return isNull(agentEvents.id);
+  return and(eq(agentEvents.userId, page.userId), eq(agentEvents.pagePath, page.path))!;
+}
+
+/** An aggregate's timestamp, which a driver may hand back as a Date or as the text Postgres sent. */
+function toMs(value: Date | string | null): number {
+  if (value === null) return 0;
+  return value instanceof Date ? value.getTime() : new Date(value).getTime();
+}
+
 function parseCursor(raw: string): { at: Date; id: string } | null {
   const dot = raw.indexOf('.');
   if (dot < 0) return null;

package/src/modules/audit/audit.contract.ts

@@ -24,19 +24,71 @@ declare global {
 /** What was called: the platform's own tool, a manual's tool, or a skill read. */
 export type AgentEventKind = 'capability' | 'tool' | 'skill';
 
-/** How the call ended. `denied`: the caller's sign-in for the tool was missing, so nothing ran. */
-export type AgentEventOutcome = 'ok' | 'error' | 'denied';
+/**
+ * How the call ended. `denied`: the caller's sign-in for the tool was
+ * missing, so nothing ran. `refused`: a page made a call that needs the
+ * viewer's approval (a writing tool, a tool the manual does not list, or a
+ * chain) and the person viewing it answered Deny, so nothing ran.
+ */
+export type AgentEventOutcome = 'ok' | 'error' | 'denied' | 'refused';
 
 /**
  * Who a call is attributed to: the connection key it was authenticated with,
- * or the agent connection behind its OAuth grant. Exactly one.
+ * the agent connection behind its OAuth grant, or the knowledge-base page
+ * whose script made it as the person viewing it. Exactly one.
+ *
+ * A page has no row of its own: it is a person and a path, and its `id` is
+ * both, encoded by {@link pagePrincipalId} so the Audit log's routes can name
+ * it like the other two.
+ */
+export type AuditPrincipalRef = { kind: 'key'; id: string } | { kind: 'agent'; id: string } | { kind: 'page'; id: string };
+
+/** Who a call is attributed to, as the recorder takes it: a page by its path, the recorder knows the person. */
+export type RecordedPrincipal = { kind: 'key'; id: string } | { kind: 'agent'; id: string } | { kind: 'page'; path: string };
+
+/** The longest page path a page principal may carry. A path is a file in the knowledge base, never longer. */
+export const MAX_PAGE_PATH_LENGTH = 1024;
+
+/**
+ * A page principal's id: the person and the page's path, encoded so it is one
+ * URL segment. Opaque to the client, which only ever echoes it back.
  */
-export type AuditPrincipalRef = { kind: 'key'; id: string } | { kind: 'agent'; id: string };
+export function pagePrincipalId(userId: string, path: string): string {
+  return Buffer.from(`${userId}\n${path}`, 'utf8').toString('base64url');
+}
+
+/** The person and the path a page principal's id names, or null when it names none. */
+export function parsePagePrincipalId(id: string): { userId: string; path: string } | null {
+  if (!/^[A-Za-z0-9_-]+$/.test(id)) return null;
+  const decoded = Buffer.from(id, 'base64url').toString('utf8');
+  const cut = decoded.indexOf('\n');
+  if (cut < 0) return null;
+  const userId = decoded.slice(0, cut);
+  const path = decoded.slice(cut + 1);
+  if (!isUuid(userId) || !isPagePath(path)) return null;
+  return { userId, path };
+}
+
+/**
+ * Whether `path` can be a page principal: a non-empty knowledge-base path of
+ * printable characters, bounded. A page names itself through a request
+ * header, so this is the check that keeps a line break or a control character
+ * out of the log and its listing — the C1 controls (NEL among them) and the
+ * Unicode line and paragraph separators included.
+ */
+export function isPagePath(path: string): boolean {
+  return (
+    path.length > 0 &&
+    path.length <= MAX_PAGE_PATH_LENGTH &&
+    // eslint-disable-next-line no-control-regex -- the point is to refuse control characters
+    !/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/.test(path)
+  );
+}
 
 /** One recorded call, as the recorder takes it. */
 export interface AgentEventInput {
   userId: string;
-  principal: AuditPrincipalRef;
+  principal: RecordedPrincipal;
   kind: AgentEventKind;
   /** The MCP server / `.tool` manual for a tool, the skill folder for a skill; null for a capability. */
   manual: string | null;
@@ -54,18 +106,18 @@ export interface IAgentEventRecorder {
   record(event: AgentEventInput): void;
 }
 
-/** One row of the Audit log: an agent connection or a connection key, with its owner. */
+/** One row of the Audit log: an agent connection, a connection key or a page, with its owner. */
 export interface AuditPrincipal {
-  kind: 'key' | 'agent';
+  kind: 'key' | 'agent' | 'page';
   id: string;
-  /** The key's label, or the agent's registered client name. */
+  /** The key's label, the agent's registered client name, or the page's knowledge-base path. */
   label: string;
   /**
    * For a key: what it was minted as (`key` by hand, `github-link` for a
    * Claude link). Absent for an agent.
    */
   keyKind?: string;
-  /** When the key was created / the agent connected. Epoch ms. */
+  /** When the key was created / the agent connected / the page first called a tool. Epoch ms. */
   createdAt: number;
   lastUsedAt: number | null;
   revokedAt: number | null;
@@ -149,7 +201,7 @@ export interface IAgentConnectionStatus {
 
 export class AuditPrincipalNotFoundError extends Error {
   constructor() {
-    super('No such agent or key');
+    super('No such agent');
     this.name = 'AuditPrincipalNotFoundError';
   }
 }

package/src/modules/audit/audit.routes.ts

@@ -7,6 +7,7 @@ import {
   AuditPrincipalNotFoundError,
   InvalidCursorError,
   isUuid,
+  parsePagePrincipalId,
   type AuditPrincipalRef,
   type IAgentAuditService,
 } from './audit.contract.js';
@@ -20,7 +21,7 @@ const DEFAULT_EVENT_PAGE = 50;
 /**
  * The Audit log's routes, JWT-only (mounted behind the session middleware):
  *
- *   GET    /api/audit/principals?scope=me|all           — agents + keys, with owners and event counts
+ *   GET    /api/audit/principals?scope=me|all           — agents, keys and pages, with owners and event counts
  *   GET    /api/audit/principals/:kind/:id/events        — one principal's events, newest first, cursor-paged
  *   DELETE /api/audit/agents/:id                         — revoke an agent (owner or admin)
  *   DELETE /api/audit/keys/:id                           — revoke a key (owner or admin)
@@ -44,14 +45,20 @@ export function createAuditRoutes(
   const principalOf = (req: express.Request): AuditPrincipalRef | null => {
     const kind = String(req.params.kind);
     const id = String(req.params.id);
+    if (kind === 'page') return parsePagePrincipalId(id) ? { kind, id } : null;
     if ((kind !== 'key' && kind !== 'agent') || !isUuid(id)) return null;
     return { kind, id };
   };
 
-  /** Whether the caller may read or revoke `principal`: its owner, or an admin. Null when there is no such principal. */
-  const mayAct = async (req: express.Request, principal: AuditPrincipalRef): Promise<boolean | null> => {
+  /**
+   * Whether the caller may read `principal`'s events: its owner, or an admin.
+   * False both when there is no such principal and when it is someone else's,
+   * so the refusal does not tell a member which of another person's pages,
+   * agents or keys exist.
+   */
+  const mayRead = async (req: express.Request, principal: AuditPrincipalRef): Promise<boolean> => {
     const owner = await audit.ownerOf(principal);
-    if (owner === null) return null;
+    if (owner === null) return false;
     if (owner === req.userId) return true;
     return isAdmin(req);
   };
@@ -74,17 +81,12 @@ export function createAuditRoutes(
   router.get('/audit/principals/:kind/:id/events', async (req, res) => {
     const principal = principalOf(req);
     if (!principal) {
-      res.status(404).json({ error: 'No such agent or key' });
+      res.status(404).json({ error: 'No such agent, key or page' });
       return;
     }
     try {
-      const allowed = await mayAct(req, principal);
-      if (allowed === null) {
-        res.status(404).json({ error: 'No such agent or key' });
-        return;
-      }
-      if (!allowed) {
-        res.status(403).json({ error: 'Not yours' });
+      if (!(await mayRead(req, principal))) {
+        res.status(404).json({ error: 'No such agent, key or page' });
         return;
       }
       const rawLimit = Number(req.query.limit);

package/src/modules/audit/request-audit.ts

@@ -1,6 +1,6 @@
 import type { CodeModeUtcpClient } from '@utcp/code-mode';
 import { logger } from '../../shared/logging.js';
-import type { AgentEventOutcome, AuditPrincipalRef, IAgentEventRecorder } from './audit.contract.js';
+import type { AgentEventOutcome, IAgentEventRecorder, RecordedPrincipal } from './audit.contract.js';
 import {
   classifyToolCall,
   skillReadPath,
@@ -13,11 +13,11 @@ const log = logger('audit');
 
 /**
  * The Audit log's view of ONE MCP request: who is calling (the user and the
- * key or agent connection the request arrived through), and how to name what
- * they call. The MCP proxy creates one per request that has a principal and
- * routes every call through it; a request with none (a browser JWT, an
- * internal token minted before connections existed) gets no instance and
- * records nothing.
+ * key, agent connection or page the request arrived through), and how to name
+ * what they call. The MCP proxy creates one per request that has a principal
+ * and routes every call through it; a request with none (a browser JWT that
+ * names no page, an internal token minted before connections existed) gets no
+ * instance and records nothing.
  *
  * Holds nothing that outlives the request. The skill catalog it may need to
  * tell a skill read from a file read is fetched at most once, and only when
@@ -29,7 +29,7 @@ export class RequestAudit {
   constructor(
     private readonly recorder: IAgentEventRecorder,
     private readonly userId: string,
-    private readonly principal: AuditPrincipalRef,
+    private readonly principal: RecordedPrincipal,
     private readonly ctx: {
       kbManualName: string;
       /** Read at classification time — the surface (and its catalog names) is built lazily. */
@@ -93,9 +93,13 @@ export class RequestAudit {
     }
   }
 
-  /** A call refused before it ran, because the caller's sign-in for its manual is missing. */
-  async denied(utcpName: string, args: Record<string, unknown>): Promise<void> {
-    this.emit(await this.classify(utcpName, args), 'denied', null);
+  /**
+   * A call refused before it ran: `denied` when the caller's sign-in for its
+   * manual is missing, `refused` when the person viewing a page answered its
+   * request to write with Deny.
+   */
+  async denied(utcpName: string, args: Record<string, unknown>, outcome: 'denied' | 'refused' = 'denied'): Promise<void> {
+    this.emit(await this.classify(utcpName, args), outcome, null);
   }
 
   /**
@@ -106,11 +110,22 @@ export class RequestAudit {
    * The direct MCP path (`callToolStreaming`) is deliberately NOT wrapped —
    * the proxy's tool handler records those itself, with the result's
    * `isError` in hand.
+   *
+   * Installed ONCE, when the client is built, because the client is shared by
+   * every request of its person: `current` names the request a call belongs
+   * to, at call time, and a call outside any request (or in one attributed to
+   * nothing) is recorded nowhere. Rebinding the client per request instead
+   * would hand one request's calls to another's audit, and stack a wrapper
+   * per request.
    */
-  instrumentChainCalls(client: CodeModeUtcpClient): void {
+  static instrumentChainCalls(client: CodeModeUtcpClient, current: () => RequestAudit | null | undefined): void {
     const callTool = client.callTool.bind(client);
-    client.callTool = (toolName: string, toolArgs: Record<string, unknown>) =>
-      this.call(toolName, toolArgs, () => callTool(toolName, toolArgs), isErrorShaped);
+    client.callTool = (toolName: string, toolArgs: Record<string, unknown>) => {
+      const audit = current();
+      return audit
+        ? audit.call(toolName, toolArgs, () => callTool(toolName, toolArgs), isErrorShaped)
+        : callTool(toolName, toolArgs);
+    };
   }
 
   private skillCatalog(): Promise<readonly SkillFolder[] | null> {

package/src/modules/database/core-schema.ts

@@ -589,22 +589,30 @@ export const oauthTokens = pgTable('oauth_tokens', {
  * which agent, when" — not "what was said".
  *
  * Exactly one principal per row (the CHECK): the connection key or the agent
- * connection the call arrived through. Both cascade, so deleting a key for
- * good, revoking-then-erasing a person, or dropping a connection takes its
- * events along — the same contract the LLM-usage rows already keep.
+ * connection the call arrived through, or the knowledge-base page whose
+ * script made the call as the person viewing it (`page_path`). Key and
+ * connection cascade, so deleting a key for good, revoking-then-erasing a
+ * person, or dropping a connection takes its events along — the same contract
+ * the LLM-usage rows already keep; a page's events go with the person.
  */
 export const agentEvents = pgTable('agent_events', {
   id: uuid('id').defaultRandom().primaryKey(),
   userId: uuid('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
   keyId: uuid('key_id').references(() => externalApiKeys.id, { onDelete: 'cascade' }),
   connectionId: uuid('connection_id').references(() => agentConnections.id, { onDelete: 'cascade' }),
+  /** The knowledge-base path of the HTML page that made the call, for a page's calls; null otherwise. */
+  pagePath: text('page_path'),
   /** `capability` | `tool` | `skill`. */
   kind: text('kind').notNull(),
   /** The MCP server / `.tool` manual (catalog name) for a tool, the skill folder for a skill; null for a capability. */
   manual: text('manual'),
   /** The tool's bare name, or the skill's name. */
   name: text('name').notNull(),
-  /** `ok` | `error` | `denied` (denied: the caller's sign-in for the tool was missing, so nothing ran). */
+  /**
+   * `ok` | `error` | `denied` | `refused`. Denied: the caller's sign-in for the
+   * tool was missing, so nothing ran. Refused: the viewer answered a page's
+   * request to write with Deny, so nothing ran.
+   */
   outcome: text('outcome').notNull(),
   durationMs: integer('duration_ms'),
   at: timestamp('at').defaultNow().notNull(),
@@ -612,14 +620,15 @@ export const agentEvents = pgTable('agent_events', {
   // The two read paths: one principal's events, newest first.
   byKey: index('agent_events_by_key').on(t.keyId, t.at),
   byConnection: index('agent_events_by_connection').on(t.connectionId, t.at),
+  byPage: index('agent_events_by_page').on(t.userId, t.pagePath, t.at),
   // The retention prune, and per-user counts.
   byAt: index('agent_events_by_at').on(t.at),
   byUser: index('agent_events_by_user').on(t.userId),
   kindCheck: check('agent_events_kind', sql`${t.kind} IN ('capability', 'tool', 'skill')`),
-  outcomeCheck: check('agent_events_outcome', sql`${t.outcome} IN ('ok', 'error', 'denied')`),
+  outcomeCheck: check('agent_events_outcome', sql`${t.outcome} IN ('ok', 'error', 'denied', 'refused')`),
   principalCheck: check(
     'agent_events_principal',
-    sql`(${t.keyId} IS NULL) <> (${t.connectionId} IS NULL)`,
+    sql`num_nonnulls(${t.keyId}, ${t.connectionId}, ${t.pagePath}) = 1`,
   ),
 }));
 

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 {