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

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

@@ -35,10 +35,12 @@ import {
   ProtectedBranchError,
   PullRebaseConflictError,
   RemoteBranchGoneError,
+  VersionNotOnBranchError,
   isMissingRemoteBranchFailure,
 } from '../../../shared/domain-errors.js';
 import {
   GitRunError,
+  assertOneSpecPerLine,
   isGitTimeout,
   redactGitToken,
   type GitCredentials,
@@ -1760,7 +1762,12 @@ export class GitService implements IGitService {
    * conflict into the typed error the workflow layer queues recovery for.
    * Shared by `pull` and `syncFromRemote` so the two cannot drift.
    */
-  private async rebaseOntoRemote(cwd: string, branch: string, remoteRef: string): Promise<void> {
+  private async rebaseOntoRemote(
+    cwd: string,
+    branch: string,
+    remoteRef: string,
+    opts: { preserveMerges?: boolean } = {},
+  ): Promise<void> {
     // An UNBORN HEAD (a clone of an upstream that was empty when cloned) has
     // no commit to replay and `git rebase` refuses to start from it, so the
     // branch is moved to the remote commit instead. That is only safe while
@@ -1798,7 +1805,20 @@ export class GitService implements IGitService {
       // the local commits onto origin, then reapplies them, so the retry
       // push can fast-forward. Untracked files don't block rebase and are
       // left untouched.
-      await this.git(cwd, ['rebase', '--autostash', remoteRef]);
+      // `--rebase-merges` is what keeps an unpushed MERGE a merge. Plain
+      // rebase replays `--no-merges upstream..HEAD`, which turns a merge
+      // commit the clone holds but origin has not seen into cherry-picks of
+      // the commits it merged — the merged branch stops being a parent, so
+      // "does the published head contain the target's head" answers no
+      // however many times the update runs. Only the change-request update
+      // asks for it; every other pull replays plain saves, where the two
+      // spellings produce the same history.
+      await this.git(cwd, [
+        'rebase',
+        '--autostash',
+        ...(opts.preserveMerges ? ['--rebase-merges'] : []),
+        remoteRef,
+      ]);
     } catch (err) {
       // Capture the contested paths BEFORE the abort wipes the rebase
       // state — `--diff-filter=U` lists exactly the files whose replay
@@ -1922,7 +1942,10 @@ export class GitService implements IGitService {
     });
   }
 
-  async pull(workspaceId: string): Promise<{ treeChanged: boolean }> {
+  async pull(
+    workspaceId: string,
+    opts: { preserveMerges?: boolean } = {},
+  ): Promise<{ treeChanged: boolean }> {
     return this.mutex.run(workspaceId, async () => {
       const cwd = await this.repoDir(workspaceId);
       const branch = await this.checkedOutBranch(cwd);
@@ -1935,7 +1958,7 @@ export class GitService implements IGitService {
       // Refresh WITHOUT `git pull`, and without touching `FETCH_HEAD` — see
       // `refreshRemoteBranchRef` for why both halves are load-bearing.
       const remoteRef = await this.refreshRemoteBranchRef(cwd, branch);
-      await this.rebaseOntoRemote(cwd, branch, remoteRef);
+      await this.rebaseOntoRemote(cwd, branch, remoteRef, opts);
       this.accessControl?.invalidate(workspaceId);
       const treeAfter = (await this.revParseOrNull(cwd, 'HEAD^{tree}')) ?? '';
       return { treeChanged: treeAfter !== treeBefore };
@@ -2310,6 +2333,10 @@ export class GitService implements IGitService {
     const repoRelativePath = this.stripRepoPrefix(relativePath);
     return this.mutex.run(workspaceId, async () => {
       const cwd = await this.repoDir(workspaceId);
+      // Branch-scoped, like the bytes route: a patch is a past version too,
+      // and leaving this route open would let a sha refused there be read
+      // here instead.
+      await this.assertOnBranchHistory(cwd, sha);
       // BOTH sides: at a commit that DELETES a directory the path is absent
       // at `sha` but a tree at `sha^` — and the diff of that deletion is
       // every child's content, exactly what the per-file gate never checked.
@@ -2361,6 +2388,10 @@ export class GitService implements IGitService {
     const repoRelativePath = this.stripRepoPrefix(relativePath);
     return this.mutex.run(workspaceId, async () => {
       const cwd = await this.repoDir(workspaceId);
+      // Same branch rule as the patch and the bytes: this route serves the
+      // FULL text of both sides, so it is the most generous of the three and
+      // the least safe one to leave ungated.
+      await this.assertOnBranchHistory(cwd, sha);
       await this.assertNotTreeAtRef(cwd, sha, repoRelativePath, relativePath);
       await this.assertNotTreeAtRef(cwd, `${sha}^`, repoRelativePath, relativePath);
       const current = await this.readFileAtRef(workspaceId, sha, repoRelativePath);
@@ -3248,6 +3279,143 @@ export class GitService implements IGitService {
     }
   }
 
+  /**
+   * A repo-relative file's BYTES at an arbitrary git ref — the binary sibling
+   * of {@link readFileAtRef}, with the blob's object id alongside them.
+   *
+   * `readFileAtRef` decodes stdout as UTF-8, which for a PNG or a PDF is not a
+   * lossless round trip: every byte sequence that is not valid UTF-8 comes
+   * back as U+FFFD and the file is ruined. A past version has to be delivered
+   * byte for byte, so this reads through `cat-file --batch`, whose framing is
+   * in BYTES (`<oid> <type> <size>\n<size bytes>\n`) rather than characters.
+   *
+   * One invocation, and absence is a PROTOCOL answer (`<spec> missing`) rather
+   * than a parsed error message — which also covers `<sha>^` of a root commit,
+   * where there is no "before" side at all. `null` therefore means exactly
+   * "nothing is at that path on that side".
+   *
+   * The `oid` is the content's own hash, so it is what the HTTP route uses as
+   * an ETag: cheaper than hashing the body again, and stable for a version
+   * that by definition can never change.
+   */
+  private async blobAtRef(
+    cwd: string,
+    ref: string,
+    repoRelativePath: string,
+  ): Promise<{ bytes: Buffer; blobId: string } | null> {
+    // The spec has to be ONE line: the path is refused a control character
+    // twice over before it gets here (at the route's normaliser and again at
+    // `assertValidRelativePath`), and this is the fence at the protocol —
+    // `--batch` would otherwise read `<sha>:Docs/x.md\nzzz` as two object
+    // names and answer about the first, under the gates of the second.
+    const spec = `${ref}:${repoRelativePath}`;
+    assertOneSpecPerLine([spec]);
+    const { stdout } = await this.gitBytes(cwd, ['cat-file', '--batch'], {
+      input: `${spec}\n`,
+    });
+    const nl = stdout.indexOf(0x0a);
+    if (nl < 0) throw new Error('unexpected end of git cat-file output');
+    // The spec may itself contain spaces (a KB file routinely does), hence the
+    // endsWith checks rather than a split — same protocol reading as the
+    // access resolver's `catFileBatch`.
+    const header = stdout.subarray(0, nl).toString('utf-8');
+    if (header.endsWith(' missing') || header.endsWith(' ambiguous')) return null;
+    const [blobId, type, rawSize] = header.split(' ');
+    // A tree here would be the per-file gate bypassed, and `assertNotTreeAtRef`
+    // is what refuses it before this runs; anything else non-blob (a tag, a
+    // commit) is not a file either. Nothing to serve in either case.
+    if (type !== 'blob' || blobId === undefined) return null;
+    const size = Number(rawSize);
+    if (!Number.isSafeInteger(size) || size < 0) {
+      throw new Error(`unexpected git cat-file header: ${header}`);
+    }
+    return { bytes: stdout.subarray(nl + 1, nl + 1 + size), blobId };
+  }
+
+  /**
+   * Refuse a sha that is not in the history of the branch this workspace has
+   * checked out.
+   *
+   * A file's past is served per BRANCH: the history panel lists what `git log`
+   * on this workspace's own branch touched, and every read of a past save has
+   * to stay inside that list. Without this, a sha lifted from another branch —
+   * or from a change request nobody approved — would be readable through the
+   * workspace of a branch whose history never contained it, which is the
+   * access rules of the viewed branch bypassed by a query parameter.
+   *
+   * `merge-base --is-ancestor` is the exact question, and a commit is its own
+   * ancestor, so the branch head passes. Exit 1 is git's answer for "resolved,
+   * and not an ancestor". An unresolvable object name — a made-up id — gets
+   * the SAME refusal on purpose (see {@link VersionNotOnBranchError}), but only
+   * when git's complaint NAMES that id; every other failure propagates, a
+   * broken repository included. A guard that fails open on its own errors is
+   * not a guard, and one that reports them as a refusal is worse than no
+   * message at all.
+   */
+  private async assertOnBranchHistory(cwd: string, sha: string): Promise<void> {
+    try {
+      await this.git(cwd, ['merge-base', '--is-ancestor', sha, 'HEAD']);
+    } catch (err) {
+      if (err instanceof GitRunError && !err.timedOut) {
+        if (err.exitCode === 1) throw new VersionNotOnBranchError();
+        const stderr = err.stderr ?? err.message;
+        if (
+          // The complaint has to be about THE SHA WE ASKED FOR. `HEAD` is the
+          // other argument, and git spells its own failures the same way: a
+          // repository with no commits answers "ambiguous argument 'HEAD'",
+          // which is a broken workspace, not a version off the branch.
+          // Refusing it as "not in this file's history" would hide an
+          // infrastructure failure behind a sentence about access.
+          stderr.toLowerCase().includes(sha.toLowerCase()) &&
+          // git's wording for "I cannot resolve that" varies by subcommand and
+          // by version — `merge-base` says "Not a valid commit name", others
+          // "not a valid object name" / "unknown revision" — so every spelling
+          // that means the same thing is listed rather than one guessed at.
+          /not a valid (object|commit) name|no such commit|bad object|unknown revision|malformed object name|ambiguous argument/i.test(
+            stderr,
+          )
+        ) {
+          throw new VersionNotOnBranchError();
+        }
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * One file's BYTES at a save, exactly as they were — the `after` side of
+   * `sha`, or the `before` side (`<sha>^`) for the save that deleted it.
+   *
+   * Every guard the text history surfaces apply, in the same order: the sha is
+   * a sha, the save is on this branch, and the pathspec is not a directory at
+   * that ref (a per-file gate upstream authorized one path, and a tree read
+   * would hand over every child). `null` means the file was not there on the
+   * side asked for.
+   *
+   * Runs inside the workspace's git turn — one turn for the whole read, so the
+   * ancestry check and the bytes it authorizes cannot be separated by another
+   * caller's checkout.
+   */
+  async fileBytesAtCommit(
+    workspaceId: string,
+    relativePath: string,
+    sha: string,
+    side: 'after' | 'before',
+  ): Promise<{ bytes: Buffer; blobId: string } | null> {
+    assertValidRelativePath(relativePath);
+    if (!/^[a-f0-9]{7,40}$/i.test(sha)) {
+      throw new WorkflowValidationError('invalid commit sha');
+    }
+    const repoRelativePath = this.stripRepoPrefix(relativePath);
+    return this.mutex.run(workspaceId, async () => {
+      const cwd = await this.repoDir(workspaceId);
+      await this.assertOnBranchHistory(cwd, sha);
+      const ref = side === 'before' ? `${sha}^` : sha;
+      await this.assertNotTreeAtRef(cwd, ref, repoRelativePath, relativePath);
+      return this.blobAtRef(cwd, ref, repoRelativePath);
+    });
+  }
+
   /**
    * The commits on `ref` that touched `repoRelativePath`, newest first, at
    * most `limit` of them. What a skill's `version` is looked up through: each
@@ -3356,6 +3524,27 @@ export class GitService implements IGitService {
       env: { GIT_LITERAL_PATHSPECS: '1', ...opts?.env },
     });
   }
+
+  /**
+   * {@link git}, with stdout as raw BYTES.
+   *
+   * A sibling rather than an `encoding` option on `git()` itself: every other
+   * caller in this service reads text, and the two return types (`string` vs
+   * `Buffer`) are not interchangeable at any call site. Same
+   * `GIT_LITERAL_PATHSPECS` and same runner deadline — the only difference is
+   * that the bytes are not decoded.
+   */
+  private gitBytes(
+    cwd: string,
+    args: string[],
+    opts?: Omit<GitRunOptions, 'encoding'>,
+  ): Promise<GitRunResult<Buffer>> {
+    return this.gitRunner.run(cwd, args, {
+      ...opts,
+      encoding: 'buffer',
+      env: { GIT_LITERAL_PATHSPECS: '1', ...opts?.env },
+    });
+  }
 }
 
 /** Map a git status letter (`git diff --name-status`) to the DTO's `PrFileStatus`. */

package/src/modules/workflow/git/node-git-runner.ts

@@ -250,6 +250,12 @@ export class NodeGitRunner implements IGitRunner {
     const timers: NodeJS.Timeout[] = [];
     let timedOut = false;
 
+    // A credential that expires is renewed before it is read. Renewing is
+    // the credential's own business and its failure is not this call's:
+    // plenty of git never leaves the disk, and a call that does is told by
+    // the host what the token in hand is worth.
+    await this.credentials.prepare?.().catch(() => undefined);
+
     try {
       const { promise: pending, child } = spawnGit(args, {
         cwd,

package/src/modules/workflow/git/pull-request.service.ts

@@ -366,6 +366,60 @@ export class PullRequestService implements IPullRequestService {
     return this.summaryOf(row, workspaceId);
   }
 
+  /**
+   * Did the target change, since the fork point, any file this request also
+   * changes? The question behind `needsUpdate`.
+   *
+   * The intersection is taken over BOTH names of every rename on both sides,
+   * because a wrong "no" is the expensive answer: it would open a request on
+   * a diff read against text that has since moved, with Approve live. So
+   * `pathsChangedBetween` runs without rename detection (a rename on the
+   * TARGET reports the path it left as well as the one it arrived at), and
+   * the request's own side contributes each file's `previousPath` alongside
+   * its `path`.
+   *
+   * Answers true without asking git in the two cases where nothing may be
+   * assumed: no fork point (the branches share no history, so there is no
+   * range to diff) and a failed diff (an infra error must not read as "this
+   * request is fine"). Answers false without asking git when the request is
+   * not behind at all, or changes no files — the common case, and the one
+   * that must stay free.
+   */
+  private async targetTouchesRequestFiles(
+    workspaceId: string,
+    forkPoint: { mergeBaseSha: string | null; behind: boolean },
+    baseSha: string,
+    files: PullRequestFile[],
+  ): Promise<boolean> {
+    if (!forkPoint.behind) return false;
+    if (files.length === 0) return false;
+    // Diverged with no common ancestor: the target's whole history is
+    // "changed since the fork point", so anything this request touches is
+    // touched. Nothing to intersect against, and nothing to skip for.
+    if (!forkPoint.mergeBaseSha) return true;
+    const requestPaths = new Set<string>();
+    for (const f of files) {
+      requestPaths.add(f.path);
+      if (f.previousPath) requestPaths.add(f.previousPath);
+    }
+    try {
+      const onTarget = await this.gitService.pathsChangedBetween(
+        workspaceId,
+        forkPoint.mergeBaseSha,
+        // The target tip the WHOLE detail is pinned to, so this range ends
+        // exactly where `behind` and the file list were computed.
+        baseSha,
+      );
+      return onTarget.some((path) => requestPaths.has(path));
+    } catch (err) {
+      log.warn(
+        'could not compare the target against a change request\'s files; treating it as needing an update',
+        { err },
+      );
+      return true;
+    }
+  }
+
   async getPrDetail(
     prNumber: number,
     opts: { fresh?: boolean; workspaceId?: string; viewerEmail?: string; patches?: boolean } = {},
@@ -392,6 +446,8 @@ export class PullRequestService implements IPullRequestService {
       mergeBaseSha: null,
       behind: false,
     };
+    /** Did the target change, since the fork point, a file this request changes? */
+    let targetChangedShared = false;
     if (workspaceId) {
       const shas = await this.gitService.resolvePrShas(
         workspaceId,
@@ -417,6 +473,17 @@ export class PullRequestService implements IPullRequestService {
       // Pinned to the same two commits as the file list, so "needs updating"
       // and the diff it qualifies can never describe different heads.
       forkPoint = await this.gitService.forkPointForPr(workspaceId, { baseSha, headSha });
+      // Only a target that moved in a file THIS request also changes makes the
+      // proposal's diff describe text that has moved. One extra
+      // `diff --name-only` (and only when the branches have diverged at all)
+      // buys the difference between opening instantly and paying for a merge,
+      // a push and a second detail read.
+      targetChangedShared = await this.targetTouchesRequestFiles(
+        workspaceId,
+        forkPoint,
+        baseSha,
+        files,
+      );
     }
 
     // Validated cache hit: TTL fresh AND head SHA unchanged since we cached.
@@ -511,6 +578,22 @@ export class PullRequestService implements IPullRequestService {
       approvals,
     });
 
+    // Hashed here, not on the client: the detail carries an author HASH and no
+    // author email, so the comparison can only happen where the viewer's email
+    // is already known.
+    const viewerIsAuthor = !!(
+      opts.viewerEmail &&
+      summary.authorId &&
+      summary.authorId === hashEmail(opts.viewerEmail)
+    );
+
+    const viewerCanDelete = computeViewerCanDelete({
+      state: summary.state,
+      authorId: summary.authorId,
+      viewerEmail: opts.viewerEmail,
+      viewerCanBypassMerge,
+    });
+
     const detail: PullRequestDetail = {
       ...summary,
       body: row.body,
@@ -526,7 +609,12 @@ export class PullRequestService implements IPullRequestService {
       viewerCanCancel,
       mergeBaseSha: forkPoint.mergeBaseSha,
       behind: summary.state === 'open' && forkPoint.behind,
+      // `behind` AND the divergence actually reaches this request's files.
+      // Both halves, in this order, so a closed request is never either.
+      needsUpdate: summary.state === 'open' && forkPoint.behind && targetChangedShared,
       viewerCanUpdate,
+      viewerIsAuthor,
+      viewerCanDelete,
     };
 
     // A patch-less detail is an internal read; it must not be served to the
@@ -631,7 +719,38 @@ export function computeViewerCanUpdate(input: {
   return viewerIsAuthor || input.viewerCanBypassMerge || viewerMayApply;
 }
 
+/**
+ * Pure predicate for the `viewerCanDelete` hint — who may delete a request
+ * outright, closing it AND retiring its branch. The author (their own
+ * proposal and their own branch) or an admin (`viewerCanBypassMerge` is the
+ * proxy — the same `canWriteAtRef('roles.yaml')` predicate the DELETE route
+ * enforces). Mirrors `deleteChangeRequest` exactly, which is why it differs
+ * from its two siblings in both directions:
+ *
+ * - It does NOT grant the owner of every changed file, as
+ *   `computeViewerCanCancel` does. Declining someone else's request leaves
+ *   their branch to rework; deleting it destroys their text.
+ * - It bars only `merged`, not everything that is not `open`. A request
+ *   withdrawn in another tab is `closed` and still has a leftover branch the
+ *   server will retire, so the button must survive it. Applied history is
+ *   nobody's to delete.
+ *
+ * Fail-closed: no viewer email → false, whatever the grants say.
+ */
+export function computeViewerCanDelete(input: {
+  state: PullRequestState;
+  authorId: string | undefined;
+  viewerEmail: string | undefined;
+  viewerCanBypassMerge: boolean;
+}): boolean {
+  if (input.state === 'merged') return false;
+  if (!input.viewerEmail) return false;
+  const viewerIsAuthor = !!(input.authorId && input.authorId === hashEmail(input.viewerEmail));
+  return viewerIsAuthor || input.viewerCanBypassMerge;
+}
+
 export const __testing = {
   computeViewerCanCancel,
   computeViewerCanUpdate,
+  computeViewerCanDelete,
 };

package/src/modules/workflow/pending-commits.service.ts

@@ -34,7 +34,7 @@
  *                                                    (status='needs_attention')
  */
 
-import { and, eq, inArray, isNull, min, or, sql } from 'drizzle-orm';
+import { and, eq, inArray, isNull, min, or, sql, type SQL } from 'drizzle-orm';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('pending-commits');
@@ -384,6 +384,64 @@ export class PendingCommitsService {
       .where(eq(pendingCommits.id, id));
   }
 
+  /**
+   * Take every commit still queued for `branch` out of the worker's reach and
+   * onto the admin surface, and answer how many moved.
+   *
+   * The one caller is the knowledge-base repository being REPLACED. A release
+   * ENQUEUES the bytes and only then drops its lock, so the moment the locks
+   * on a branch are dropped there may be rows already waiting — bytes that
+   * were written against a working copy of the repository that is gone. Left
+   * `pending`, the worker would pick them up after the re-clone and commit
+   * them onto a same-named branch of a DIFFERENT repository: someone else's
+   * file, overwritten by a change nobody made to it.
+   *
+   * `needs_attention`, not deleted — the same rule as everything else about a
+   * replacement. The bytes are still in the row, the reason is on it, and they
+   * show up on the pending-commit admin surface for a person to decide about.
+   * `running` rows go too: the worker checks the row back in when it finishes,
+   * and a row it is mid-flight with is exactly one whose destination just
+   * changed under it.
+   */
+  async markNeedsAttentionOnBranch(branch: string, error: string): Promise<number> {
+    return this.escalateQueued(eq(pendingCommits.branch, branch), error);
+  }
+
+  /** Every commit still queued that `which` selects goes to a person, with the reason. Answers how many. */
+  private async escalateQueued(which: SQL, error: string): Promise<number> {
+    const moved = await this.db
+      .update(pendingCommits)
+      .set({
+        status: 'needs_attention',
+        lastError: error,
+        lastAttemptedAt: new Date(),
+      })
+      .where(and(which, inArray(pendingCommits.status, ['pending', 'running'])))
+      .returning({ id: pendingCommits.id });
+    return moved.length;
+  }
+
+  /**
+   * The same, for every commit still queued against ONE WORKING COPY, and
+   * answer how many moved.
+   *
+   * The caller is the startup phase setting a working copy aside: a clone of
+   * a repository the configured one shares no history with. Whatever was
+   * queued for it was written against that clone, on any branch, the default
+   * one included, and the directory the worker would write to is now a fresh
+   * clone of another repository. Closing change requests covers the branches
+   * of the requests that were closed and nothing else, which is why this is
+   * keyed on the working copy: it is the thing that was replaced.
+   *
+   * A working copy that was only pointed at a new address (the same
+   * repository, moved) keeps its queue, and is never passed here.
+   */
+  async markNeedsAttentionInWorkspace(workspaceId: string, error: string): Promise<number> {
+    // The canonical form `enqueue` stores (see `canonicalWorkspaceId`), so the
+    // caller's spelling of the id cannot make this match nothing.
+    return this.escalateQueued(eq(pendingCommits.workspaceId, canonicalWorkspaceId(workspaceId)), error);
+  }
+
   /**
    * When the oldest commit still waiting to land was queued, or null when
    * nothing waits — the readiness answer's one number. `pending` and

package/src/modules/workflow/workflow-hooks.ts

@@ -1,14 +1,13 @@
-import type { ValidationReport } from '@bevel-software/platform-shared';
+import type { AuthUser, ValidationReport } from '@bevel-software/platform-shared';
 
 /**
  * Workflow lifecycle hooks — the generic seam that replaced the
- * constructor-injected KB validator (and the core-owned ontology write block).
- * Core code invokes the hooks at fixed lifecycle points; the modules that OWN
- * the behavior (the enterprise kb/kb-graph modules today) register handlers in
- * the composition root, right after `createCoreServices` returns. Core
- * registers none, so a core-only deployment runs every hook point as a no-op.
+ * constructor-injected KB validator. Core code invokes the hooks at fixed
+ * lifecycle points; the modules that OWN the behavior register handlers in the
+ * composition root, right after `createCoreServices` returns. Core registers
+ * none, so a core-only deployment runs every hook point as a no-op.
  *
- * Two hook kinds with deliberately different failure semantics:
+ * Three hook kinds, with deliberately different failure semantics:
  *
  *   - `commitValidation` — ADVISORY. Runs at commit time in `GitService`
  *     (`commit` / `commitFile`), exactly where the injected `IKbValidator`
@@ -18,12 +17,18 @@ import type { ValidationReport } from '@bevel-software/platform-shared';
  *     `runValidation(workspaceId)` shape so `KbValidatorService` registers
  *     with a one-line adapter.
  *
- *   - `preWrite` — BLOCKING. Runs before a gated agent write (file-write
- *     tools) or a write-capable shell command; a hook that throws REJECTS the
- *     operation (the error propagates to the tool caller). This is where the
- *     enterprise ontology-session block registers; core registers nothing, so
- *     core never blocks (touch TRACKING stays core — see
- *     `session-ontology.gate.ts`).
+ *   - `agentRead` — BLOCKING. Runs before a gated agent READ of a
+ *     knowledge-base path (reads, `delete_file`, `delete_folder`, and each
+ *     file a `grep` walk opens). A hook that throws REFUSES the read.
+ *
+ *   - `preWrite` — BLOCKING. Runs before a gated agent WRITE (the file-write
+ *     tools, once per path) or a write-capable shell command, which carries no
+ *     path. A hook that throws REFUSES the operation, and the caller sees the
+ *     hook's own message and status.
+ *
+ * The two blocking hooks are the seam a deployment builds a per-conversation
+ * rule on: they carry the session id the call named, and core itself neither
+ * decides nor records anything (see `workspace/agent-access.gate.ts`).
  */
 
 /** What `GitService` knows at the advisory commit-validation point. */
@@ -47,19 +52,35 @@ export type CommitValidationHook = (
 ) => Promise<ValidationReport | void>;
 
 /**
- * What the pre-write gate knows when it consults the blocking hooks. The core
- * gate has already resolved all skip conditions (boundary flag off, neutral
- * path, non-agent caller, recovery bot, missing session id — see
- * `resolveGatedSession`), so by hook time there is always a session id.
+ * What an agent operation looks like to the blocking hooks. The core gate has
+ * already resolved the only two skips it owns (the caller is not an agent, or
+ * is the recovery bot), so every hook call describes a real agent operation.
+ *
+ * `sessionId` is present only when the call carried one — core does NOT fail
+ * closed on its absence, because whether a path needs a session is the
+ * registering deployment's rule, not core's.
  */
-export type PreWriteContext =
-  /** A path-addressed content write (write_file/edit_file/mkdir/move/copy/unzip…). */
-  | { kind: 'file-write'; sessionId: string; wsPath: string }
-  /** A write-capable operation with no resolvable target path (execute_command). */
-  | { kind: 'shell'; sessionId: string };
+export interface AgentOperationContext {
+  /** The conversation the call belongs to, when it named one. */
+  sessionId?: string;
+  /**
+   * The workspace-relative path the operation targets. Absent for a
+   * write-capable operation with no resolvable target (`execute_command`).
+   */
+  wsPath?: string;
+  /** The branch (draft) whose workspace the operation acts on. */
+  branch: string;
+  /** The calling user. */
+  user: AuthUser;
+  /** Whether the caller is the in-app agent (`internal`) or an external one. */
+  source: 'internal' | 'external';
+}
 
-/** Blocking pre-write hook: throw to reject the write; return to allow. */
-export type PreWriteHook = (ctx: PreWriteContext) => Promise<void>;
+/** Blocking pre-read hook: throw to refuse the read; return to allow. */
+export type AgentReadHook = (ctx: AgentOperationContext) => Promise<void>;
+
+/** Blocking pre-write hook: throw to refuse the write; return to allow. */
+export type PreWriteHook = (ctx: AgentOperationContext) => Promise<void>;
 
 /**
  * The registry instance. ONE per composition (created in
@@ -68,6 +89,7 @@ export type PreWriteHook = (ctx: PreWriteContext) => Promise<void>;
  */
 export class WorkflowHooks {
   private readonly commitValidation: CommitValidationHook[] = [];
+  private readonly agentRead: AgentReadHook[] = [];
   private readonly preWrite: PreWriteHook[] = [];
 
   /** Register an advisory commit-time validation hook. */
@@ -75,6 +97,11 @@ export class WorkflowHooks {
     this.commitValidation.push(hook);
   }
 
+  /** Register a blocking pre-read hook. */
+  onAgentRead(hook: AgentReadHook): void {
+    this.agentRead.push(hook);
+  }
+
   /** Register a blocking pre-write hook. */
   onPreWrite(hook: PreWriteHook): void {
     this.preWrite.push(hook);
@@ -88,12 +115,23 @@ export class WorkflowHooks {
     return this.commitValidation;
   }
 
+  /**
+   * Run every blocking pre-read hook in registration order. The first throw
+   * propagates and refuses the read; with no hooks registered (core-only)
+   * this resolves immediately.
+   */
+  async runAgentRead(ctx: AgentOperationContext): Promise<void> {
+    for (const hook of this.agentRead) {
+      await hook(ctx);
+    }
+  }
+
   /**
    * Run every blocking pre-write hook in registration order. The first throw
-   * propagates and rejects the write; with no hooks registered (core-only)
+   * propagates and refuses the write; with no hooks registered (core-only)
    * this resolves immediately.
    */
-  async runPreWrite(ctx: PreWriteContext): Promise<void> {
+  async runPreWrite(ctx: AgentOperationContext): Promise<void> {
     for (const hook of this.preWrite) {
       await hook(ctx);
     }

package/src/modules/workflow/workflow.routes.ts

@@ -790,7 +790,9 @@ export function createWorkflowRoutes(
 
   /**
    * Delete a change request outright — close it and retire its source
-   * branch. Admin-only; the moderation verb for a shared deployment.
+   * branch. The request's author or an admin: their own proposal to throw
+   * away, and the moderation verb for a shared deployment. The changed files'
+   * owners are NOT included — they keep reject, which leaves the branch.
    */
   router.delete('/workflow/change-requests/:number', async (req, res) => {
     const num = parsePrNumber(req.params.number);