@bevel-software/platform-core-backend 0.21.0 → 0.23.0

package/src/modules/workflow/workflow.service.ts

@@ -43,6 +43,7 @@ import type {
   ChangeRequestApplyFailureKind,
   ChangeRequestComment,
   ChangeRequestDetail,
+  ChangeRequestUpdateResult,
   ChangeRequestState,
   ChangedFile,
   FileApproval,
@@ -62,7 +63,7 @@ import {
   isPlatformRestoreShape,
 } from '@bevel-software/platform-shared';
 import type { KbContext } from '../../shared/kb-context.js';
-import { and, eq, inArray, isNotNull, isNull, lt, or } from 'drizzle-orm';
+import { and, desc, eq, inArray, isNotNull, isNull, lt, ne, or, sql } from 'drizzle-orm';
 import type { Database } from '../database/connection.js';
 import { changeRequests } from '../database/schema.js';
 import type { GitService } from './git/git.service.js';
@@ -323,9 +324,9 @@ export class WorkflowService implements IWorkflowService {
      * the composition root registers module-owned behavior against it
      * (`core.workflowService.hooks.onCommitValidation(…)` /
      * `.onPreWrite(…)`) after `createCoreServices` returns. The composition
-     * root passes the SAME instance `GitService` and the session-ontology
-     * gate consult; the default keeps test constructions (which don't
-     * exercise hooks) unchanged.
+     * root passes the SAME instance `GitService` and the agent-access gate
+     * consult; the default keeps test constructions (which don't exercise
+     * hooks) unchanged.
      */
     public readonly hooks: WorkflowHooks = new WorkflowHooks(),
   ) {
@@ -576,8 +577,11 @@ export class WorkflowService implements IWorkflowService {
    * and nothing else. The pull itself reports the change, since it is the
    * only code that can observe it under the workspace mutex.
    */
-  private async pullWorkspace(workspaceId: string): Promise<boolean> {
-    const { treeChanged } = await this.git.pull(workspaceId);
+  private async pullWorkspace(
+    workspaceId: string,
+    opts: { preserveMerges?: boolean } = {},
+  ): Promise<boolean> {
+    const { treeChanged } = await this.git.pull(workspaceId, opts);
     const defaultBranch = this.kb.defaultBranch;
     if (treeChanged && branchForWorkspaceId(workspaceId) === defaultBranch) {
       this.events?.emit({ kind: 'fs-tree-changed', workspaceId, branch: defaultBranch });
@@ -906,6 +910,22 @@ export class WorkflowService implements IWorkflowService {
     return this.git.fileContentsAtCommit(workspaceId, path, sha);
   }
 
+  /**
+   * The BYTES of one file at a change — what the file page's byte-reading
+   * viewers (pdf, image, docx, pptx, xlsx, email) need to show a past save,
+   * and what "Download this version" hands over. `fileAtChange` above cannot
+   * serve them: it decodes to UTF-8, which ruins every format that is not
+   * text.
+   */
+  fileBytesAtChange(
+    workspaceId: string,
+    path: string,
+    sha: string,
+    side: 'after' | 'before',
+  ): Promise<{ bytes: Buffer; blobId: string } | null> {
+    return this.git.fileBytesAtCommit(workspaceId, path, sha, side);
+  }
+
   /**
    * Resolve write permission for `targetPath` against the access tree at
    * `HEAD` of `branch`. Throws `AccessDeniedError` on denial with the
@@ -1729,6 +1749,38 @@ export class WorkflowService implements IWorkflowService {
     return this.prs.getPr(number);
   }
 
+  /**
+   * The newest non-open change request from `sourceBranch` by `authorEmail`.
+   *
+   * Read straight off `change_requests` rather than through the PR listing,
+   * which serves OPEN requests only: the whole point here is the closed ones.
+   * `author_email` is stored lowercased at insert, so the needle is too.
+   * Ordered by `closed_at` with `created_at` as the tiebreak, because a row
+   * closed before the column existed (or by a path that forgot to stamp it)
+   * still has a creation time and must not sort as the oldest.
+   */
+  async latestClosedChangeRequest(
+    authorEmail: string,
+    sourceBranch: string,
+  ): Promise<{ number: number; state: ChangeRequestState } | null> {
+    const email = authorEmail.trim().toLowerCase();
+    if (!email || !sourceBranch) return null;
+    const [row] = await this.db
+      .select({ number: changeRequests.number, state: changeRequests.state })
+      .from(changeRequests)
+      .where(
+        and(
+          eq(changeRequests.authorEmail, email),
+          eq(changeRequests.sourceBranch, sourceBranch),
+          ne(changeRequests.state, 'open'),
+        ),
+      )
+      .orderBy(desc(changeRequests.closedAt), desc(changeRequests.createdAt))
+      .limit(1);
+    if (!row) return null;
+    return { number: row.number, state: row.state as ChangeRequestState };
+  }
+
   getChangeRequestDetail(
     number: number,
     opts?: { fresh?: boolean; workspaceId?: string; viewerEmail?: string; patches?: boolean },
@@ -1953,13 +2005,29 @@ export class WorkflowService implements IWorkflowService {
    * the enforcement read one predicate. A conflicting merge is aborted
    * inside `mergeFromOrigin`: nothing is committed or pushed, and the branch
    * is exactly what it was.
+   *
+   * ONE detail read after the merge. The read before it exists only to
+   * decide authority and to name the two branches, so it asks for no patches
+   * — that is one git subprocess per changed file it does not spend. The
+   * approvals carry-forward runs BEFORE the final read rather than after it,
+   * against a head resolved with `resolvePrShas` (two rev-parses) instead of
+   * a whole second detail, so the detail that goes back already describes the
+   * approvals it carried. What used to be three detail reads is now one.
    */
   async updateFromTarget(
     workspaceId: string,
     user: AuthUser,
     number: number,
-  ): Promise<ChangeRequestDetail> {
-    const detail = await this.prs.getPrDetail(number, { fresh: true, workspaceId, viewerEmail: user.email });
+  ): Promise<ChangeRequestUpdateResult> {
+    // No patches: all this read decides is authority, state and the two
+    // branch names. Asking for patch text here would diff every changed file
+    // in a request that is about to be merged and read in full anyway.
+    const detail = await this.prs.getPrDetail(number, {
+      fresh: true,
+      workspaceId,
+      viewerEmail: user.email,
+      patches: false,
+    });
     if (!detail) {
       throw new WorkflowValidationError(
         `Change request #${number} not found.`,
@@ -1987,8 +2055,15 @@ export class WorkflowService implements IWorkflowService {
     // merge commit that then cannot push, stranding it in the workspace. A
     // rebase conflict hands the stranded saves to recovery, as every other
     // pull does, before the refusal reaches the caller.
+    //
+    // `preserveMerges`: this is the one pull whose unpushed commit may be a
+    // MERGE — the update that ran before this one and could not push. A plain
+    // rebase replays it as cherry-picks of the target's commits, which drops
+    // the target as a parent, so the branch never contains the target's head
+    // however many times the update runs. Replayed with `--rebase-merges` it
+    // stays a merge and the next push ends the loop.
     try {
-      await this.pullWorkspace(workspaceId);
+      await this.pullWorkspace(workspaceId, { preserveMerges: true });
     } catch (err) {
       if (err instanceof PullRebaseConflictError) {
         await this.queuePullConflictRecovery(workspaceId, err, user);
@@ -2026,24 +2101,53 @@ export class WorkflowService implements IWorkflowService {
     if (outcome.kind === 'conflicts') {
       throw new ChangeRequestConflictsError(detail.branch, detail.base, outcome.paths);
     }
-    // If a new merge commit landed, push so the CR picks it up. When
-    // already up to date there's nothing to share — short-circuit the push.
-    if (!outcome.alreadyUpToDate) {
+    // Push whenever the CLONE holds a commit origin has not seen — not when
+    // THIS merge authored one. The two differ in exactly the case that keeps
+    // a request behind for good: an earlier update merged, its push failed,
+    // and the merge is sitting in the workspace. That merge already contains
+    // the target, so this call's `mergeFromOrigin` reports
+    // `alreadyUpToDate` and the old gate skipped the push — leaving the
+    // request behind on the remote, and the next open with the same work to
+    // do. Asking git what is unpushed retries it instead.
+    //
+    // A failed probe falls back to the old gate rather than to "push
+    // anyway": `trackedPush` on a clone with nothing to push is a wasted
+    // round trip on every single update.
+    const hasUnpushed = await this.git
+      .hasUnpushedCommits(workspaceId)
+      .catch((err: unknown) => {
+        log.warn(
+          `could not tell whether change request #${number} has unpushed commits; falling back to whether this merge authored one`,
+          { err },
+        );
+        return !outcome.alreadyUpToDate;
+      });
+    if (hasUnpushed) {
       await this.trackedPush(workspaceId, user);
-      // The source head moved: the refusal described a revision that is gone.
-      await this.clearApplyFailure(number, { recordedBefore: headMovedAfter });
     }
-    this.prs.invalidateDetailCache(number);
-    const refreshed = await this.prs.getPrDetail(number, {
-      fresh: true,
-      workspaceId,
-      viewerEmail: user.email,
-    });
-    if (!refreshed) {
-      throw new WorkflowValidationError(
-        `Refreshed change request #${number} but could not re-fetch its detail.`,
+    // Where the branch ended up, as PUBLISHED — two rev-parses, not a second
+    // detail read. Everything below needs only the sha, and the detail that
+    // goes back to the caller is read once, at the end, after the approvals
+    // it should describe have been carried.
+    let headAfterMerge = headBeforeMerge;
+    try {
+      const at = await this.git.resolvePrShas(workspaceId, detail.base, detail.branch);
+      headAfterMerge = at.headSha;
+    } catch (err) {
+      log.warn(
+        `could not resolve the published head of change request #${number} after updating it from target`,
+        { err },
       );
     }
+    const headMoved = Boolean(headBeforeMerge) && headAfterMerge !== headBeforeMerge;
+    // The source head moved: the refusal described a revision that is gone.
+    // `hasUnpushed` counts as well as the sha comparison, and deliberately —
+    // a push that just landed moved the published head by definition, and
+    // reading the sha to confirm it is a call that can fail. A refusal left
+    // standing over a revision nobody can apply any more is the worse error.
+    if (headMoved || hasUnpushed) {
+      await this.clearApplyFailure(number, { recordedBefore: headMovedAfter });
+    }
     // The merge is a commit the APPROVERS did not make. Re-pin their
     // approvals onto the new head for every file whose bytes it left alone —
     // git's own two-dot diff between the two heads is the verdict on which
@@ -2051,45 +2155,61 @@ export class WorkflowService implements IWorkflowService {
     // than the bookkeeping, so a failure here is logged and the fresh detail
     // still goes back.
     //
-    // `alreadyUpToDate` is the real gate: no merge commit, no head to compare,
-    // nothing moved under anyone. The other two conditions are belt-and-braces
-    // over a sha that is not a sha — a resolve that failed onto a detail with
-    // no head, or two heads that somehow read equal — both of which
-    // `pathsChangedBetween` and `carryApprovalsForward` would refuse anyway.
-    // A merge that authored a commit cannot leave the head where it was.
-    if (!outcome.alreadyUpToDate && headBeforeMerge && refreshed.headSha !== headBeforeMerge) {
+    // The head moving is the real gate: nothing moved, nothing moved under
+    // anyone. It also covers the sha that is not a sha — a resolve that
+    // failed onto a detail with no head — which `pathsChangedBetween` and
+    // `carryApprovalsForward` would refuse anyway.
+    //
+    // This runs BEFORE the detail read, not after it. The rows it writes are
+    // what the caller's `approvals` must describe, so doing it first means
+    // the one read at the end is already correct — where carrying afterwards
+    // needed a THIRD read to correct a detail assembled before the rows
+    // existed.
+    //
+    // The same list answers the caller's `updatedPaths`: "which files did
+    // this merge change" is one question, and the two answers must not be
+    // allowed to differ — a file whose approval was carried (so: untouched)
+    // that the dialog then re-read would be the dialog discarding content the
+    // server just called unchanged.
+    let updatedPaths: string[] = [];
+    if (headMoved) {
       try {
-        const changedPaths = await this.git.pathsChangedBetween(
+        updatedPaths = await this.git.pathsChangedBetween(
           workspaceId,
           headBeforeMerge,
-          refreshed.headSha,
+          headAfterMerge,
         );
-        const carried = await this.reviewWorkflow.carryApprovalsForward(
+        await this.reviewWorkflow.carryApprovalsForward(
           number,
           headBeforeMerge,
-          refreshed.headSha,
-          changedPaths,
+          headAfterMerge,
+          updatedPaths,
         );
-        // The detail above was assembled before those rows existed, so its
-        // `approvals` (and the merge gate derived from them) still describe
-        // the pre-merge head. Only re-read when something actually carried.
-        if (carried > 0) {
-          this.prs.invalidateDetailCache(number);
-          const withApprovals = await this.prs.getPrDetail(number, {
-            fresh: true,
-            workspaceId,
-            viewerEmail: user.email,
-          });
-          if (withApprovals) return withApprovals;
-        }
       } catch (err) {
         log.warn(
           `could not carry approvals forward on change request #${number} after updating from target`,
           { err },
         );
+        // The diff is what failed, so which files moved is unknown. Say so as
+        // "every file this request had", which is every file a caller can
+        // already be showing: slow beats a dialog that goes on presenting
+        // pre-merge text as current. Anything the merge ADDED is not on the
+        // list and does not need to be — no caller has read it yet.
+        updatedPaths = (detail.files ?? []).map((f) => f.path);
       }
     }
-    return refreshed;
+    this.prs.invalidateDetailCache(number);
+    const refreshed = await this.prs.getPrDetail(number, {
+      fresh: true,
+      workspaceId,
+      viewerEmail: user.email,
+    });
+    if (!refreshed) {
+      throw new WorkflowValidationError(
+        `Refreshed change request #${number} but could not re-fetch its detail.`,
+      );
+    }
+    return { ...refreshed, updatedPaths };
   }
 
   listComments(number: number): Promise<ChangeRequestComment[]> {
@@ -2651,11 +2771,16 @@ export class WorkflowService implements IWorkflowService {
   /**
    * DELETE a change request outright: close it (whatever its diff says) and
    * retire its source branch — the request, its proposal, and the branch that
-   * carried it are gone in one verb. Admin-only, resolved the same way every
-   * other admin check here is (write on `roles.yaml` at `origin/<base>`,
-   * never a local ref): this is the moderation verb for a shared deployment,
-   * stronger than reject (which the author or the files' owners can do, and
-   * which leaves the branch for a second round).
+   * carried it are gone in one verb. The request's AUTHOR or an admin, and
+   * nobody else: it is the author's own proposal and their own branch to throw
+   * away, and it is the moderation verb for a shared deployment. Admin rights
+   * resolve the same way every other admin check here does (write on
+   * `roles.yaml` at `origin/<base>`, never a local ref); authorship is the
+   * STORED `authorId` hash, never anything the caller sends.
+   *
+   * Stronger than reject, which the changed files' owners may also do and which
+   * leaves the branch for a second round. They keep reject and do not get this:
+   * an owner must not be able to destroy someone else's text and branch.
    */
   async deleteChangeRequest(number: number, user: AuthUser): Promise<void> {
     const summary = await this.prs.getPr(number);
@@ -2714,8 +2839,17 @@ export class WorkflowService implements IWorkflowService {
         409,
       );
     }
-    if (isAdmin !== true) {
-      throw new WorkflowDomainError('Only an admin can delete a change request.', 403);
+    // Authorship is decided from the STORED author hash, never from anything
+    // the caller sends. Note what is deliberately NOT short-circuited for an
+    // author: the strict fetch and the `null` check above still run. An
+    // author's grant needs no `roles.yaml` read, so skipping them would look
+    // free — but it would let a delete close the request while the branch
+    // removal silently failed against an unreachable origin, and "the shared
+    // repository was down, so nothing changed" is the one refusal that has to
+    // stay honest.
+    const callerIsAuthor = !!(summary.authorId && summary.authorId === hashEmail(user.email));
+    if (!callerIsAuthor && isAdmin !== true) {
+      throw new WorkflowDomainError("Only the request's author or an admin can delete it.", 403);
     }
 
     // Close first (idempotent: an already-closed request just skips to the
@@ -2906,6 +3040,107 @@ export class WorkflowService implements IWorkflowService {
     return closed;
   }
 
+  /**
+   * How many change requests are open right now.
+   *
+   * Read by the setup screen's repository-change confirmation, which has to
+   * say how many requests the admin is deciding about BEFORE the address is
+   * saved. A plain count — nothing here reaches the repository, so it answers
+   * just as well for a repository that is already gone.
+   */
+  async countOpenChangeRequests(): Promise<number> {
+    const [row] = await this.db
+      .select({ open: sql<number>`count(*)::int` })
+      .from(changeRequests)
+      .where(eq(changeRequests.state, 'open'));
+    return row?.open ?? 0;
+  }
+
+  /**
+   * Close every open change request because the knowledge-base REPOSITORY was
+   * replaced, and answer how many were closed.
+   *
+   * The admin's own choice on the setup screen: a repository that merely
+   * MOVED keeps its requests (the branches came along), while a repository
+   * that was REPLACED has none of those branches, so every request points at
+   * something this deployment can no longer fetch. Nothing is deleted — the
+   * rows stay, closed, carrying `closed_reason = 'repository-replaced'` so
+   * the reason survives the person who chose it.
+   *
+   * Locks held on those branches go with them. Their holder cannot publish
+   * the bytes (the branch is not in the new repository) and cannot release
+   * the lock by finishing (the request is closed), so the row would sit there
+   * refusing the path until its TTL ran out — and a still-connected client's
+   * heartbeat keeps pushing that out.
+   *
+   * The close is ONE statement per pass — `update … where state = 'open'
+   * returning` — not a count followed by a row-at-a-time loop. Read first and
+   * then written, every request opened while the loop ran would be missed and
+   * left open against a branch the new repository does not have. One
+   * set-shaped statement cannot miss a row that exists when it runs, and the
+   * guard is the statement's own `where`, so a merge or a withdrawal racing it
+   * wins and its request is simply not in the returned set.
+   *
+   * Repeated while a pass still finds something, because a request can be
+   * opened BETWEEN passes: the caller has not saved the new address yet, so
+   * the deployment is still live and `POST /change-requests` is still being
+   * served. Bounded, so a client opening requests in a loop cannot hold the
+   * save open forever — what survives the last pass is a request opened after
+   * the repository was replaced, which the deleted-branch sweep closes on its
+   * own terms.
+   */
+  async closeOpenChangeRequestsAsRepositoryReplaced(): Promise<number> {
+    let closed = 0;
+    for (let pass = 0; pass < 5; pass++) {
+      const now = new Date();
+      const justClosed = await this.db
+        .update(changeRequests)
+        .set({ state: 'closed', closedAt: now, updatedAt: now, closedReason: 'repository-replaced' })
+        .where(eq(changeRequests.state, 'open'))
+        .returning({ number: changeRequests.number, sourceBranch: changeRequests.sourceBranch });
+      if (justClosed.length === 0) break;
+      for (const cr of justClosed) {
+        // Best effort, per branch: a lock table that will not answer must not
+        // leave the requests half closed — the close is the decision the admin
+        // made, and the locks expire on their own within the minute.
+        try {
+          const released = await this.fileLocks.releaseAllOnBranch(cr.sourceBranch);
+          if (released > 0) {
+            crLog.info(`released ${released} file lock(s) held on "${cr.sourceBranch}"`);
+          }
+        } catch (err) {
+          crLog.warn(`could not release the file locks on "${cr.sourceBranch}":`, { err });
+        }
+        // The bytes a release already enqueued belong to the repository that
+        // is gone — see `markNeedsAttentionOnBranch`. Taken out of the
+        // worker's reach in the same breath as the locks, because dropping a
+        // lock is precisely what leaves a row behind.
+        try {
+          const quarantined = await this.pendingCommits.markNeedsAttentionOnBranch(
+            cr.sourceBranch,
+            'The knowledge-base repository was replaced while this commit was still queued, so it was never ' +
+              'written. The bytes are kept here: the branch it was meant for belongs to the previous repository.',
+          );
+          if (quarantined > 0) {
+            crLog.warn(
+              `${quarantined} queued commit(s) on "${cr.sourceBranch}" need attention: the repository was replaced ` +
+                'before they landed, so they were not written to the new one.',
+            );
+          }
+        } catch (err) {
+          crLog.warn(`could not set aside the queued commits on "${cr.sourceBranch}":`, { err });
+        }
+        this.prs.invalidateDetailCache(cr.number);
+        this.events?.emit({ kind: 'change-request-rejected', number: cr.number });
+        closed++;
+      }
+    }
+    if (closed > 0) {
+      crLog.info(`closed ${closed} change request(s): the knowledge-base repository was replaced`);
+    }
+    return closed;
+  }
+
   /**
    * The sweep above, on demand. Boot runs it once (`create-core-server`),
    * which clears requests stranded BEFORE the process started; a branch that

package/src/modules/workspace/__tests__/agent-access.gate.test.ts

@@ -0,0 +1,208 @@
+import { describe, expect, it, beforeEach } from 'vitest';
+import {
+  notifyAgentRead,
+  assertAgentWriteAllowed,
+  SESSION_ID_DESCRIPTION,
+  SESSION_ID_INPUT,
+  ToolDescriptionNotes,
+  type AgentAccessGate,
+} from '../agent-access.gate.js';
+import { WorkflowHooks, type AgentOperationContext } from '../../workflow/workflow-hooks.js';
+import { ToolError, type ToolContext } from '../../tool-helpers/tool.contract.js';
+
+const RECOVERY_EMAIL = 'recovery-bot@bevel.local';
+const P_FILE = 'knowledge-base/KnowledgeBase/Product/Knowledge/Roadmap.md';
+
+function ctx(over: Partial<ToolContext> = {}): ToolContext {
+  return {
+    user: { id: 'u1', email: 'a@b.c', name: 'A' },
+    scope: 'write',
+    source: 'external',
+    sessionId: 's1',
+    abortSignal: new AbortController().signal,
+    workspaceService: {} as never,
+    workflowService: {} as never,
+    events: {} as never,
+    getFilesystem: async () => ({}) as never,
+    ...over,
+  } as ToolContext;
+}
+
+/** A gate with a fresh hook registry, plus the two lists of what the hooks saw. */
+function makeGate(): { gate: AgentAccessGate; reads: AgentOperationContext[]; writes: AgentOperationContext[] } {
+  const hooks = new WorkflowHooks();
+  const reads: AgentOperationContext[] = [];
+  const writes: AgentOperationContext[] = [];
+  hooks.onAgentRead(async (op) => {
+    reads.push(op);
+  });
+  hooks.onPreWrite(async (op) => {
+    writes.push(op);
+  });
+  return { gate: { recoveryBotEmail: RECOVERY_EMAIL, hooks, notes: new ToolDescriptionNotes() }, reads, writes };
+}
+
+describe('notifyAgentRead', () => {
+  it('calls the read hook once with the session, path, branch, user and source', async () => {
+    const { gate, reads, writes } = makeGate();
+    await notifyAgentRead(gate, ctx(), 'draft-1', P_FILE);
+    expect(reads).toEqual([
+      {
+        sessionId: 's1',
+        wsPath: P_FILE,
+        branch: 'draft-1',
+        user: { id: 'u1', email: 'a@b.c', name: 'A' },
+        source: 'external',
+      },
+    ]);
+    expect(writes).toEqual([]);
+  });
+
+  it('carries the in-app agent as source `internal`', async () => {
+    const { gate, reads } = makeGate();
+    await notifyAgentRead(gate, ctx({ source: 'internal' }), 'main', P_FILE);
+    expect(reads[0].source).toBe('internal');
+  });
+
+  it('calls the hook with no session id when the call carried none — the hook decides', async () => {
+    const { gate, reads } = makeGate();
+    await notifyAgentRead(gate, ctx({ sessionId: undefined }), 'main', P_FILE);
+    expect(reads).toHaveLength(1);
+    expect(reads[0].sessionId).toBeUndefined();
+  });
+
+  it('never reaches the hooks for a caller that is not an agent', async () => {
+    const { gate, reads } = makeGate();
+    await notifyAgentRead(gate, ctx({ source: 'session' }), 'main', P_FILE);
+    expect(reads).toEqual([]);
+  });
+
+  it('never reaches the hooks for the recovery bot, whatever the case of its address', async () => {
+    const { gate, reads } = makeGate();
+    await notifyAgentRead(gate, ctx({ user: { id: 'bot', email: 'Recovery-Bot@Bevel.local', name: 'bot' } }), 'main', P_FILE);
+    expect(reads).toEqual([]);
+  });
+
+  it('refuses the read with the hook\'s own message and status', async () => {
+    const hooks = new WorkflowHooks();
+    hooks.onAgentRead(async () => {
+      throw new ToolError('Not in this conversation.', 403);
+    });
+    const gate: AgentAccessGate = { recoveryBotEmail: RECOVERY_EMAIL, hooks, notes: new ToolDescriptionNotes() };
+    await expect(notifyAgentRead(gate, ctx(), 'main', P_FILE)).rejects.toMatchObject({
+      message: 'Not in this conversation.',
+      status: 403,
+    });
+  });
+
+  it('is a no-op with no hook registered', async () => {
+    const gate: AgentAccessGate = {
+      recoveryBotEmail: RECOVERY_EMAIL,
+      hooks: new WorkflowHooks(),
+      notes: new ToolDescriptionNotes(),
+    };
+    await expect(notifyAgentRead(gate, ctx({ sessionId: undefined }), 'main', P_FILE)).resolves.toBeUndefined();
+  });
+});
+
+describe('assertAgentWriteAllowed', () => {
+  it('calls the write hook with the path, and never the read hook', async () => {
+    const { gate, reads, writes } = makeGate();
+    await assertAgentWriteAllowed(gate, ctx(), 'draft-1', P_FILE);
+    expect(reads).toEqual([]);
+    expect(writes).toHaveLength(1);
+    expect(writes[0]).toMatchObject({ sessionId: 's1', wsPath: P_FILE, branch: 'draft-1', source: 'external' });
+  });
+
+  it('calls the write hook with NO path for a write-capable call that has none', async () => {
+    const { gate, writes } = makeGate();
+    await assertAgentWriteAllowed(gate, ctx(), 'main');
+    expect(writes).toHaveLength(1);
+    expect(writes[0].wsPath).toBeUndefined();
+    expect(writes[0].branch).toBe('main');
+  });
+
+  it('refuses the write with the hook\'s own message and status', async () => {
+    const hooks = new WorkflowHooks();
+    hooks.onPreWrite(async () => {
+      throw new ToolError('Not in this conversation.', 403);
+    });
+    const gate: AgentAccessGate = { recoveryBotEmail: RECOVERY_EMAIL, hooks, notes: new ToolDescriptionNotes() };
+    await expect(assertAgentWriteAllowed(gate, ctx(), 'main', P_FILE)).rejects.toMatchObject({
+      message: 'Not in this conversation.',
+      status: 403,
+    });
+  });
+
+  it('runs every registered write hook, in registration order, until one throws', async () => {
+    const hooks = new WorkflowHooks();
+    const seen: string[] = [];
+    hooks.onPreWrite(async () => {
+      seen.push('first');
+    });
+    hooks.onPreWrite(async () => {
+      seen.push('second');
+      throw new ToolError('no', 403);
+    });
+    hooks.onPreWrite(async () => {
+      seen.push('third');
+    });
+    const gate: AgentAccessGate = { recoveryBotEmail: RECOVERY_EMAIL, hooks, notes: new ToolDescriptionNotes() };
+    await expect(assertAgentWriteAllowed(gate, ctx(), 'main', P_FILE)).rejects.toThrow('no');
+    expect(seen).toEqual(['first', 'second']);
+  });
+
+  it('never reaches the hooks for a person in the app or for the recovery bot', async () => {
+    const { gate, writes } = makeGate();
+    await assertAgentWriteAllowed(gate, ctx({ source: 'session' }), 'main', P_FILE);
+    await assertAgentWriteAllowed(gate, ctx({ user: { id: 'bot', email: RECOVERY_EMAIL, name: 'bot' } }), 'main', P_FILE);
+    expect(writes).toEqual([]);
+  });
+
+  it('is a no-op with no hook registered, with or without a session id', async () => {
+    const gate: AgentAccessGate = {
+      recoveryBotEmail: RECOVERY_EMAIL,
+      hooks: new WorkflowHooks(),
+      notes: new ToolDescriptionNotes(),
+    };
+    await expect(assertAgentWriteAllowed(gate, ctx(), 'main', P_FILE)).resolves.toBeUndefined();
+    await expect(assertAgentWriteAllowed(gate, ctx({ sessionId: undefined }), 'main', P_FILE)).resolves.toBeUndefined();
+  });
+});
+
+describe('ToolDescriptionNotes', () => {
+  let notes: ToolDescriptionNotes;
+  beforeEach(() => {
+    notes = new ToolDescriptionNotes();
+  });
+
+  it('has no note registered by default, which is every Hexis-only deployment', () => {
+    expect(notes.gatedToolNote()).toBe('');
+    expect(notes.sessionIdDescription()).toBe(SESSION_ID_DESCRIPTION);
+  });
+
+  it('appends a registered gated-tool note and a registered sessionId note', () => {
+    notes.registerGatedToolNote(' Stay put.');
+    notes.registerSessionIdNote(' It also pins the boundary.');
+    expect(notes.gatedToolNote()).toBe(' Stay put.');
+    expect(notes.sessionIdDescription()).toBe(`${SESSION_ID_DESCRIPTION} It also pins the boundary.`);
+  });
+
+  it('tells its subscribers on every registration, so mounted tools re-describe', () => {
+    let calls = 0;
+    notes.onChange(() => {
+      calls++;
+    });
+    notes.registerGatedToolNote(' a');
+    notes.registerSessionIdNote(' b');
+    expect(calls).toBe(2);
+  });
+
+  it('the default sessionId input says what the id is, and mentions no ontology', () => {
+    expect(SESSION_ID_INPUT.description).toBe(SESSION_ID_DESCRIPTION);
+    expect(SESSION_ID_DESCRIPTION).toMatch(/conversation/i);
+    expect(SESSION_ID_DESCRIPTION).toMatch(/start_session/);
+    expect(SESSION_ID_DESCRIPTION).toMatch(/ask/);
+    expect(SESSION_ID_DESCRIPTION.toLowerCase()).not.toContain('ontolog');
+  });
+});