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

package/src/modules/workflow/__tests__/workflow.service.facade.test.ts

@@ -17,6 +17,7 @@ import { PullRebaseConflictError, WorkflowDomainError } from '../../../shared/do
 import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import type { Database } from '../../database/connection.js';
 import { openChangeGate } from '../../../__tests__/open-change-gate.js';
+import { hashEmail } from '../../../shared/email-identity.js';
 
 // `deleteBranch`'s open-request guard is the only DB touch these tests
 // exercise. The stub ANSWERS FROM THE WHERE-CLAUSE rather than returning the
@@ -375,7 +376,7 @@ describe('WorkflowService — change request delegation + cache invalidation', (
     expect(outcome).toEqual({ kind: 'merged', result: mergeResult });
     // The target branch's workspace is pulled so it doesn't fall behind origin.
     expect(workspaceService.getOrCreateForBranch).toHaveBeenCalledWith('main');
-    expect(git.pull).toHaveBeenCalledWith('main');
+    expect(git.pull).toHaveBeenCalledWith('main', {});
     expect(reviewWorkflow.mergePr).toHaveBeenCalledWith(
       4,
       expect.objectContaining({ email: 'alice@example.com' }),
@@ -784,8 +785,13 @@ describe('WorkflowService — revertChangeRequestFile / closeEmptyChangeRequest'
   });
 });
 
-describe('WorkflowService — deleteChangeRequest (admin moderation verb)', () => {
-  function makeDeleteHarness(opts: { isAdmin?: boolean; prState?: string } = {}) {
+describe('WorkflowService — deleteChangeRequest (the author’s and the admin’s verb)', () => {
+  const AUTHOR_EMAIL = 'alice@example.com'; // makeUser()'s default caller
+  const STRANGER_AUTHOR = 'mallory@example.com';
+
+  function makeDeleteHarness(
+    opts: { isAdmin?: boolean; prState?: string; authorEmail?: string | null } = {},
+  ) {
     const git = Object.assign(makeGit(), {
       changedPathsForPr: vi.fn().mockResolvedValue(['Docs/a.md']),
     }) as unknown as GitService;
@@ -795,26 +801,83 @@ describe('WorkflowService — deleteChangeRequest (admin moderation verb)', () =
       base: 'main',
       branch: 'mallory/spam',
       state: opts.prState ?? 'open',
+      // Authorship as the server reads it: the stored hash, never the caller's
+      // claim. Defaults to someone OTHER than makeUser(), so a test that says
+      // nothing about authorship is testing the admin grant alone.
+      // `null` means a request with no stored author (opened outside this
+      // backend); undefined means "someone, just not the caller".
+      authorId:
+        opts.authorEmail === null ? undefined : hashEmail(opts.authorEmail ?? STRANGER_AUTHOR),
     });
     const access = makeAccessControl();
     (access.canWriteAtRef as ReturnType<typeof vi.fn>).mockResolvedValue(opts.isAdmin ?? false);
     const chain: Record<string, unknown> = {};
+    // Two different selects run under one chain mock: the branch-retirement
+    // lookup asks for `{ sourceBranch }`, and `openChangeRequestOn` asks for
+    // `{ number, sourceBranch }`. Answer by projection rather than call order,
+    // so the retirement path is exercised (a branch to retire, and no other
+    // open request holding it) without the test depending on call sequence.
+    let projection: Record<string, unknown> = {};
     Object.assign(chain, {
-      select: vi.fn(() => chain),
+      select: vi.fn((proj?: Record<string, unknown>) => {
+        projection = proj ?? {};
+        return chain;
+      }),
       from: vi.fn(() => chain),
       where: vi.fn(() => chain),
-      limit: vi.fn(async () => []),
+      limit: vi.fn(async () =>
+        'number' in projection ? [] : [{ sourceBranch: 'mallory/spam' }],
+      ),
       update: vi.fn(() => chain),
       set: vi.fn(() => chain),
       returning: vi.fn(async () => [{ id: 1 }]),
     });
     const workspaces = makeWorkspaceService();
     const svc = new WorkflowService(chain as unknown as Database, git, prs, makeReviewWorkflow(), workspaces, access, makeFileLockService(), makePendingCommits(), testKbContext(), openChangeGate());
-    return { svc, prs, db: chain, access, workspaces };
+    return { svc, prs, db: chain, access, workspaces, git };
   }
 
-  it('refuses a non-admin with 403 and touches nothing', async () => {
-    const { svc, db } = makeDeleteHarness({ isAdmin: false });
+  it('refuses a non-admin who is not the author, with 403 and the author-or-admin message', async () => {
+    const { svc, db, git } = makeDeleteHarness({ isAdmin: false });
+    await expect(svc.deleteChangeRequest(9, makeUser())).rejects.toMatchObject({
+      status: 403,
+      message: "Only the request's author or an admin can delete it.",
+    });
+    // "Changes nothing" is the whole promise of the refusal: no row flipped,
+    // no branch removed.
+    expect(db.update).not.toHaveBeenCalled();
+    expect(git.deleteBranch).not.toHaveBeenCalled();
+  });
+
+  it('lets the AUTHOR delete their own request without admin rights: closes it and retires the branch', async () => {
+    const { svc, prs, db, git } = makeDeleteHarness({
+      isAdmin: false,
+      authorEmail: AUTHOR_EMAIL,
+    });
+    await svc.deleteChangeRequest(9, makeUser());
+    expect(db.update).toHaveBeenCalled();
+    expect(prs.invalidateDetailCache).toHaveBeenCalledWith(9);
+    expect(git.deleteBranch).toHaveBeenCalledWith(
+      expect.any(String),
+      'mallory/spam',
+      expect.objectContaining({ email: AUTHOR_EMAIL }),
+      expect.objectContaining({ systemCleanup: true }),
+    );
+  });
+
+  it('matches the author case-insensitively, as hashEmail does', async () => {
+    // The stored hash is of the normalized address; a caller signed in as
+    // `Alice@Example.com` is the same person and must not be refused.
+    const { svc, db } = makeDeleteHarness({ isAdmin: false, authorEmail: AUTHOR_EMAIL });
+    await svc.deleteChangeRequest(9, makeUser({ email: '  Alice@Example.com  ' }));
+    expect(db.update).toHaveBeenCalled();
+  });
+
+  it('refuses a request with no stored author to a non-admin', async () => {
+    // Opened outside this backend: nobody can claim authorship of it, so the
+    // admin grant is the only one left. An absent hash must never read as a
+    // match.
+    const { svc, db } = makeDeleteHarness({ isAdmin: false, authorEmail: null });
     await expect(svc.deleteChangeRequest(9, makeUser())).rejects.toMatchObject({ status: 403 });
     expect(db.update).not.toHaveBeenCalled();
   });
@@ -832,6 +895,94 @@ describe('WorkflowService — deleteChangeRequest (admin moderation verb)', () =
     expect(db.update).not.toHaveBeenCalled();
   });
 
+  it('refuses the AUTHOR on an applied request with 422 and the applied message', async () => {
+    // Applied between opening the dialog and confirming. The author's new
+    // grant does not reach applied history either.
+    const { svc, db, git } = makeDeleteHarness({
+      isAdmin: false,
+      prState: 'merged',
+      authorEmail: AUTHOR_EMAIL,
+    });
+    await expect(svc.deleteChangeRequest(9, makeUser())).rejects.toMatchObject({
+      status: 422,
+      message: 'This change request has already been applied.',
+    });
+    expect(db.update).not.toHaveBeenCalled();
+    expect(git.deleteBranch).not.toHaveBeenCalled();
+  });
+
+  it('refuses the AUTHOR with 409 when the base cannot be verified, and changes nothing', async () => {
+    // The strict base fetch is NOT skipped for an author, even though their
+    // grant needs no roles.yaml read: an unreachable origin means the branch
+    // removal would fail silently, and the delete must refuse whole rather
+    // than close the request and leave the branch.
+    const { svc, db, git, workspaces } = makeDeleteHarness({
+      isAdmin: false,
+      authorEmail: AUTHOR_EMAIL,
+    });
+    (workspaces.ensureRemotesFetched as ReturnType<typeof vi.fn>).mockRejectedValue(
+      new Error('origin unreachable'),
+    );
+    await expect(svc.deleteChangeRequest(9, makeUser())).rejects.toMatchObject({
+      status: 409,
+      message: expect.stringContaining('Retry in a moment.'),
+    });
+    expect(db.update).not.toHaveBeenCalled();
+    expect(git.deleteBranch).not.toHaveBeenCalled();
+  });
+
+  it('refuses the AUTHOR with 409 when the base ref does not resolve', async () => {
+    const { svc, db, access } = makeDeleteHarness({
+      isAdmin: false,
+      authorEmail: AUTHOR_EMAIL,
+    });
+    (access.canWriteAtRef as ReturnType<typeof vi.fn>).mockResolvedValue(null);
+    await expect(svc.deleteChangeRequest(9, makeUser())).rejects.toMatchObject({ status: 409 });
+    expect(db.update).not.toHaveBeenCalled();
+  });
+
+  it('a request already closed elsewhere still has its branch retired', async () => {
+    // Withdrawn in another tab: the guarded update flips no row, the request
+    // is not merged, so the delete finishes the job the withdraw left undone.
+    const { svc, db, git } = makeDeleteHarness({
+      isAdmin: false,
+      prState: 'closed',
+      authorEmail: AUTHOR_EMAIL,
+    });
+    // The update is guarded on `state = 'open'`, so it flips nothing here.
+    (db.returning as ReturnType<typeof vi.fn>).mockResolvedValue([]);
+    await expect(svc.deleteChangeRequest(9, makeUser())).resolves.toBeUndefined();
+    expect(git.deleteBranch).toHaveBeenCalledWith(
+      expect.any(String),
+      'mallory/spam',
+      expect.anything(),
+      expect.objectContaining({ systemCleanup: true }),
+    );
+  });
+
+  it('keeps a branch another open request still uses, and closes the request silently', async () => {
+    const { svc, db, git } = makeDeleteHarness({
+      isAdmin: false,
+      authorEmail: AUTHOR_EMAIL,
+    });
+    // `openChangeRequestOn` finds a live request on the branch (the
+    // `{ number, sourceBranch }` projection), so retirement backs off.
+    let projection: Record<string, unknown> = {};
+    (db.select as ReturnType<typeof vi.fn>).mockImplementation((proj?: Record<string, unknown>) => {
+      projection = proj ?? {};
+      return db;
+    });
+    (db.limit as ReturnType<typeof vi.fn>).mockImplementation(async () =>
+      'number' in projection
+        ? [{ number: 11, sourceBranch: 'mallory/spam' }]
+        : [{ sourceBranch: 'mallory/spam' }],
+    );
+    // No throw, no message: the request closes and the branch survives.
+    await expect(svc.deleteChangeRequest(9, makeUser())).resolves.toBeUndefined();
+    expect(db.update).toHaveBeenCalled();
+    expect(git.deleteBranch).not.toHaveBeenCalled();
+  });
+
   it('kicks the deleted-branch sweep when the base workspace cannot be resolved', async () => {
     const { svc, db, workspaces } = makeDeleteHarness({ isAdmin: true });
     (workspaces.getOrCreateForBranch as ReturnType<typeof vi.fn>).mockRejectedValue(

package/src/modules/workflow/__tests__/workflow.service.update-from-target.test.ts

@@ -45,17 +45,26 @@ function detail(overrides: Partial<PullRequestDetail> = {}): PullRequestDetail {
     branch: 'alice/deal',
     base: 'current-company-state',
     behind: true,
+    needsUpdate: true,
     viewerCanUpdate: true,
     headSha: HEAD,
     mergeBaseSha: 'c'.repeat(40),
+    // The pre-flight read asks for no patches, but it still names the files —
+    // which is what the fallback for a failed diff answers with.
+    files: [{ path: 'Sales/Deal.md' }],
     ...overrides,
-  } as PullRequestDetail;
+  } as unknown as PullRequestDetail;
 }
 
 function harness(opts: {
   first?: PullRequestDetail | null;
   /** The published head of the proposal branch as resolved just before the merge. */
   publishedHead?: string;
+  /**
+   * The published head AFTER the merge. Defaults to the merge commit; set it
+   * equal to the pre-merge head to describe a merge that moved nothing.
+   */
+  headAfterMerge?: string;
   resolveError?: Error;
   merge?: { kind: 'clean'; alreadyUpToDate: boolean } | { kind: 'conflicts'; paths: string[] };
   pullError?: Error;
@@ -64,31 +73,42 @@ function harness(opts: {
   changedPathsError?: Error;
   /** How many approval rows the carry-forward wrote. */
   carried?: number;
-  /** The detail the extra read after a carry-forward answers with. */
-  withApprovals?: PullRequestDetail;
+  /** Does the clone hold commits origin has not seen? */
+  unpushed?: boolean;
+  unpushedError?: Error;
 }) {
+  // Two resolves per update: once after the pull (where the branch IS), once
+  // after the merge (where it ended up). One mock that answers in order, so a
+  // test can describe a head that moved without stubbing call indices.
+  const preMergeHead = opts.publishedHead ?? HEAD;
+  const postMergeHead = opts.headAfterMerge ?? MERGED_HEAD;
+  const resolvePrShas = opts.resolveError
+    ? vi.fn().mockRejectedValue(opts.resolveError)
+    : vi
+        .fn()
+        .mockResolvedValueOnce({ baseSha: 'b'.repeat(40), headSha: preMergeHead })
+        .mockResolvedValue({ baseSha: 'b'.repeat(40), headSha: postMergeHead });
   const git = {
     pull: opts.pullError
       ? vi.fn().mockRejectedValue(opts.pullError)
       : vi.fn().mockResolvedValue({ treeChanged: false }),
     mergeFromOrigin: vi.fn().mockResolvedValue(opts.merge ?? { kind: 'clean', alreadyUpToDate: false }),
     push: vi.fn().mockResolvedValue(undefined),
+    hasUnpushedCommits: opts.unpushedError
+      ? vi.fn().mockRejectedValue(opts.unpushedError)
+      : vi.fn().mockResolvedValue(opts.unpushed ?? true),
     pathsChangedBetween: opts.changedPathsError
       ? vi.fn().mockRejectedValue(opts.changedPathsError)
       : vi.fn().mockResolvedValue(opts.changedPaths ?? []),
-    resolvePrShas: opts.resolveError
-      ? vi.fn().mockRejectedValue(opts.resolveError)
-      : vi.fn().mockResolvedValue({
-          baseSha: 'b'.repeat(40),
-          headSha: opts.publishedHead ?? HEAD,
-        }),
+    resolvePrShas,
   };
-  const refreshed = detail({ behind: false, headSha: MERGED_HEAD });
+  const refreshed = detail({ behind: false, needsUpdate: false, headSha: postMergeHead });
+  // Exactly two reads per update: the pre-flight (authority, branch names)
+  // and the one that goes back. A third would be the cost this ticket removed.
   const getPrDetail = vi
     .fn()
     .mockResolvedValueOnce(opts.first === undefined ? detail() : opts.first)
-    .mockResolvedValueOnce(refreshed)
-    .mockResolvedValue(opts.withApprovals ?? refreshed);
+    .mockResolvedValue(refreshed);
   const prs = { getPrDetail, invalidateDetailCache: vi.fn() };
   const pendingCommits = { enqueueIfAbsent: vi.fn().mockResolvedValue(true) };
   const reviewWorkflow = {
@@ -111,14 +131,19 @@ function harness(opts: {
 
 describe('WorkflowService.updateFromTarget', () => {
   it('merges the target into the proposal, pushes, and returns the refreshed detail', async () => {
-    const h = harness({});
-    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toBe(h.refreshed);
+    const h = harness({ changedPaths: ['Sales/Deal.md'] });
+    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toEqual({
+      ...h.refreshed,
+      updatedPaths: ['Sales/Deal.md'],
+    });
 
-    // The permission read is computed for THIS caller.
+    // The permission read is computed for THIS caller — and asks for no
+    // patches: all it decides is authority, state and the two branch names.
     expect(h.prs.getPrDetail).toHaveBeenNthCalledWith(1, 7, {
       fresh: true,
       workspaceId: WS,
       viewerEmail: USER.email,
+      patches: false,
     });
     expect(h.git.mergeFromOrigin).toHaveBeenCalledWith(WS, 'alice/deal', 'current-company-state', USER);
     expect(h.git.push).toHaveBeenCalledWith(WS, USER);
@@ -126,6 +151,29 @@ describe('WorkflowService.updateFromTarget', () => {
     expect(h.refreshed.behind).toBe(false);
   });
 
+  it('costs ONE detail read after the merge', async () => {
+    // The whole point of the ticket on the server side. Two reads total: the
+    // pre-flight that decides authority, and the one that goes back. The
+    // carry-forward runs BEFORE that second read rather than correcting it
+    // with a third.
+    const h = harness({ changedPaths: ['Sales/Deal.md'], carried: 2 });
+    await h.svc.updateFromTarget(WS, USER, 7);
+    expect(h.prs.getPrDetail).toHaveBeenCalledTimes(2);
+    const carriedAt = h.reviewWorkflow.carryApprovalsForward.mock.invocationCallOrder[0];
+    const lastReadAt = h.prs.getPrDetail.mock.invocationCallOrder[1];
+    expect(carriedAt).toBeLessThan(lastReadAt);
+  });
+
+  it('replays the pull with --rebase-merges, so an unpushed merge stays a merge', async () => {
+    // A plain rebase flattens a merge commit origin has not seen into
+    // cherry-picks of the target's commits, which drops the target as a
+    // parent — and the request never contains the target's head however many
+    // times the update runs.
+    const h = harness({});
+    await h.svc.updateFromTarget(WS, USER, 7);
+    expect(h.git.pull).toHaveBeenCalledWith(WS, { preserveMerges: true });
+  });
+
   it('refuses a viewer who is neither the author nor able to apply — nothing is merged', async () => {
     const h = harness({ first: detail({ viewerCanUpdate: false }) });
     const err = await h.svc.updateFromTarget(WS, USER, 7).catch((e: unknown) => e);
@@ -157,13 +205,54 @@ describe('WorkflowService.updateFromTarget', () => {
     expect(h.git.push).not.toHaveBeenCalled();
   });
 
-  it('an already up-to-date merge pushes nothing but still returns the refreshed detail', async () => {
-    const h = harness({ merge: { kind: 'clean', alreadyUpToDate: true } });
-    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toBe(h.refreshed);
+  it('an already up-to-date merge with nothing unpushed pushes nothing', async () => {
+    const h = harness({
+      merge: { kind: 'clean', alreadyUpToDate: true },
+      unpushed: false,
+      headAfterMerge: HEAD,
+    });
+    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toEqual({
+      ...h.refreshed,
+      updatedPaths: [],
+    });
     expect(h.git.push).not.toHaveBeenCalled();
     expect(h.prs.invalidateDetailCache).toHaveBeenCalledWith(7);
   });
 
+  it('retries a push that failed last time, even though this merge has nothing to do', async () => {
+    // The loop this ticket closes. An earlier update merged the target in and
+    // its push failed, so the merge is sitting in the clone. This update's
+    // merge is therefore ALREADY up to date — and the old gate, which pushed
+    // only when the merge authored a commit, skipped the push and left the
+    // request behind on the remote for the next open to find.
+    const h = harness({
+      merge: { kind: 'clean', alreadyUpToDate: true },
+      unpushed: true,
+      publishedHead: HEAD,
+      headAfterMerge: MERGED_HEAD,
+      changedPaths: ['Sales/Deal.md'],
+    });
+    await h.svc.updateFromTarget(WS, USER, 7);
+    expect(h.git.hasUnpushedCommits).toHaveBeenCalledWith(WS);
+    expect(h.git.push).toHaveBeenCalledWith(WS, USER);
+  });
+
+  it('falls back to "did this merge author a commit" when git cannot say what is unpushed', async () => {
+    // Never "push anyway": a push on a clone with nothing to push is a wasted
+    // round trip on every update.
+    const clean = harness({ unpushedError: new Error('git exploded') });
+    await clean.svc.updateFromTarget(WS, USER, 7);
+    expect(clean.git.push).toHaveBeenCalledWith(WS, USER);
+
+    const nothingToDo = harness({
+      unpushedError: new Error('git exploded'),
+      merge: { kind: 'clean', alreadyUpToDate: true },
+      headAfterMerge: HEAD,
+    });
+    await nothingToDo.svc.updateFromTarget(WS, USER, 7);
+    expect(nothingToDo.git.push).not.toHaveBeenCalled();
+  });
+
   it('a rebase conflict refreshing the checkout queues recovery for the saves, then refuses', async () => {
     const conflict = new PullRebaseConflictError('alice/deal', ['Sales/Deal.md'], 'rebase stopped');
     const h = harness({ pullError: conflict });
@@ -183,15 +272,13 @@ describe('WorkflowService.updateFromTarget', () => {
 });
 
 describe('WorkflowService.updateFromTarget: the approvals the merge did not touch', () => {
-  it('carries them onto the new head, and re-reads the detail so the gate sees them', async () => {
-    const withApprovals = detail({ behind: false, headSha: MERGED_HEAD, mergeableInBevel: true });
-    const h = harness({
-      changedPaths: ['Sales/Deal.md'],
-      carried: 2,
-      withApprovals,
-    });
+  it('carries them onto the new head, before the one detail read that goes back', async () => {
+    const h = harness({ changedPaths: ['Sales/Deal.md'], carried: 2 });
 
-    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toBe(withApprovals);
+    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toEqual({
+      ...h.refreshed,
+      updatedPaths: ['Sales/Deal.md'],
+    });
 
     // What moved is git's answer between the two heads — never a guess, and
     // never the request's own three-dot diff against the target.
@@ -202,23 +289,33 @@ describe('WorkflowService.updateFromTarget: the approvals the merge did not touc
       MERGED_HEAD,
       ['Sales/Deal.md'],
     );
-    // The first refreshed detail was assembled before the rows existed, so it
-    // is not the one that goes back.
-    expect(h.prs.getPrDetail).toHaveBeenCalledTimes(3);
   });
 
-  it('does not re-read the detail when nothing carried', async () => {
-    const h = harness({ changedPaths: ['Sales/Deal.md'], carried: 0 });
-    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toBe(h.refreshed);
-    expect(h.reviewWorkflow.carryApprovalsForward).toHaveBeenCalledTimes(1);
-    expect(h.prs.getPrDetail).toHaveBeenCalledTimes(2);
+  it('answers the same list as updatedPaths — carried and re-read cannot disagree', async () => {
+    // A file whose approval was carried (so: untouched by the merge) that the
+    // dialog then re-read would be the dialog discarding content the server
+    // just called unchanged.
+    const h = harness({ changedPaths: ['Sales/Deal.md', 'Sales/Terms.md'], carried: 1 });
+    const result = await h.svc.updateFromTarget(WS, USER, 7);
+    expect(result.updatedPaths).toEqual(['Sales/Deal.md', 'Sales/Terms.md']);
+    expect(h.reviewWorkflow.carryApprovalsForward).toHaveBeenCalledWith(
+      7,
+      HEAD,
+      MERGED_HEAD,
+      result.updatedPaths,
+    );
   });
 
-  it('touches nothing when the merge had nothing to do', async () => {
-    const h = harness({ merge: { kind: 'clean', alreadyUpToDate: true } });
-    await h.svc.updateFromTarget(WS, USER, 7);
+  it('touches nothing when the head did not move', async () => {
+    const h = harness({
+      merge: { kind: 'clean', alreadyUpToDate: true },
+      unpushed: false,
+      headAfterMerge: HEAD,
+    });
+    const result = await h.svc.updateFromTarget(WS, USER, 7);
     expect(h.git.pathsChangedBetween).not.toHaveBeenCalled();
     expect(h.reviewWorkflow.carryApprovalsForward).not.toHaveBeenCalled();
+    expect(result.updatedPaths).toEqual([]);
   });
 
   it('touches nothing when the merge conflicted — the rows describe a head that still stands', async () => {
@@ -250,10 +347,12 @@ describe('WorkflowService.updateFromTarget: the approvals the merge did not touc
   it('falls back to the head the detail reported when that head cannot be resolved', async () => {
     // Bookkeeping never costs the update: an unresolvable ref leaves the
     // carry-forward working off the detail's head, exactly as it did before.
+    // Both resolves fail, so the head reads as unmoved from the detail's own
+    // — there is no pair of shas to diff, and the update still lands.
     const h = harness({ resolveError: new Error('no such ref'), carried: 1 });
     await h.svc.updateFromTarget(WS, USER, 7);
     expect(h.git.push).toHaveBeenCalledWith(WS, USER);
-    expect(h.reviewWorkflow.carryApprovalsForward).toHaveBeenCalledWith(7, HEAD, MERGED_HEAD, []);
+    expect(h.reviewWorkflow.carryApprovalsForward).not.toHaveBeenCalled();
   });
 
   it('carries nothing when there is no head to compare at all', async () => {
@@ -266,7 +365,10 @@ describe('WorkflowService.updateFromTarget: the approvals the merge did not touc
       resolveError: new Error('no such ref'),
       carried: 1,
     });
-    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toBe(h.refreshed);
+    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toEqual({
+      ...h.refreshed,
+      updatedPaths: [],
+    });
     expect(h.git.push).toHaveBeenCalledWith(WS, USER);
     expect(h.git.pathsChangedBetween).not.toHaveBeenCalled();
     expect(h.reviewWorkflow.carryApprovalsForward).not.toHaveBeenCalled();
@@ -276,7 +378,11 @@ describe('WorkflowService.updateFromTarget: the approvals the merge did not touc
     // A request that IS up to date is worth more than the carry-forward: the
     // approvals simply go stale, exactly as they did before this existed.
     const h = harness({ changedPathsError: new Error('git exploded') });
-    await expect(h.svc.updateFromTarget(WS, USER, 7)).resolves.toBe(h.refreshed);
+    const result = await h.svc.updateFromTarget(WS, USER, 7);
+    expect(result).toMatchObject({ number: 7, behind: false });
     expect(h.reviewWorkflow.carryApprovalsForward).not.toHaveBeenCalled();
+    // Which files moved is unknown, so every file the request had is named:
+    // slow beats a dialog that goes on presenting pre-merge text as current.
+    expect(result.updatedPaths).toEqual(['Sales/Deal.md']);
   });
 });

package/src/modules/workflow/agent-tools/__tests__/workflow.tools.test.ts

@@ -278,9 +278,149 @@ describe('registerWorkflowTools', () => {
     expect(calls.filter((c) => c[0] === 'createBranch')).toHaveLength(0);
   });
 
+  /**
+   * These tools address their workspace by ID — `workspaceIdForBranch(branch)`
+   * straight from the argument — so they never pass the `getFilesystem` choke
+   * point that guards the file tools. A branch-less call used to commit to a
+   * workspace id that was literally the string "undefined" — and `create_branch`
+   * used to fork from one, cloning a branch of that name and answering "There is
+   * no branch named undefined." The guard sits on the mount and is keyed on
+   * whether the tool's declared inputs REQUIRE `branch`, so it covers the
+   * injected input and a tool's own alike, without any of them remembering it.
+   */
+  describe('a branch-less call to a tool that declares `branch`', () => {
+    /**
+     * Every tool whose DECLARED inputs require `branch`, read off the mounted
+     * registry — not a list written by hand. The hand-written list is how the
+     * gap that failed Local Testing stayed invisible: it named the three tools
+     * that take the injected input and missed `create_branch`, whose `branch`
+     * is its own (the fork base) and is just as required. Anything mounted
+     * later is swept in without this file being touched.
+     */
+    const branchTakingTools = async (): Promise<string[]> =>
+      (await registryRef!.listInternal())
+        .filter((t) => {
+          const body = (t.inputs as { properties?: { body?: { required?: string[] } } }).properties?.body;
+          return (body?.required ?? []).includes('branch');
+        })
+        .map((t) => t.name);
+
+    // The inputs each tool needs BESIDES `branch`, so the only thing wrong with
+    // every call below is the missing branch.
+    const bodyFor = (tool: string): Record<string, unknown> =>
+      ({
+        commit_change: { summary: 's' },
+        save_file: { path: 'KnowledgeBase/x.md', content: 'c' },
+        create_branch: { name: 'alice/new-draft' },
+        write_file: { path: 'KnowledgeBase/x.md', content: 'c' },
+      })[tool] ?? {};
+
+    it('400s branch-required on every mounted tool that declares `branch`, and acts on nothing', async () => {
+      const base = await start();
+      const tools = await branchTakingTools();
+      // Both kinds are in here: the injected input and a tool's own required
+      // `branch`. `create_branch` is the one the reported bug survived on.
+      expect(tools).toContain('commit_change');
+      expect(tools).toContain('create_branch');
+      expect(tools).toContain('switch_branch');
+
+      for (const tool of tools) {
+        const res = await post(`${base}/api/agent/tools/${tool}`, writeTok(), bodyFor(tool));
+
+        expect(res.status, `${tool} must 400 on a branch-less call`).toBe(400);
+        expect(await res.json(), `${tool} must answer the shared refusal`).toEqual({
+          kind: 'branch-required',
+          error: '`branch` is required: pass the branch (draft) you are working on.',
+        });
+      }
+      // No workflow call was made at all — least of all one naming a workspace
+      // id built out of the missing value, or a branch forked from it.
+      expect(calls).toEqual([]);
+    });
+
+    /**
+     * The exact shapes Local Testing drove over MCP against `create_branch`:
+     * a missing branch answered 404 `There is no branch named undefined.`
+     * (a clone of that "branch" was attempted), an empty one 500 'Invalid
+     * workspace ID', and `["main"]` — which `encodeURIComponent` stringifies
+     * straight back to `main` — answered 200 and really created and pushed a
+     * branch off the default. All four are one refusal now.
+     */
+    it('refuses every absent shape on create_branch, and forks from nothing', async () => {
+      const base = await start();
+      const absent: Array<[string, Record<string, unknown>]> = [
+        ['missing', { name: 'alice/new-draft' }],
+        ['empty', { name: 'alice/new-draft', branch: '' }],
+        ['null', { name: 'alice/new-draft', branch: null }],
+        ['a number', { name: 'alice/new-draft', branch: 42 }],
+        ['an array (stringifies to a real branch name)', { name: 'alice/new-draft', branch: ['main'] }],
+        ['the literal "undefined"', { name: 'alice/new-draft', branch: 'undefined' }],
+        ['the literal "null"', { name: 'alice/new-draft', branch: 'null' }],
+      ];
+
+      for (const [label, body] of absent) {
+        const res = await post(`${base}/api/agent/tools/create_branch`, writeTok(), body);
+        expect(res.status, `branch ${label} must 400`).toBe(400);
+        const answered = await res.json();
+        expect(answered.kind, `branch ${label} must answer branch-required`).toBe('branch-required');
+        expect(JSON.stringify(answered), `branch ${label} must not echo an absent value`).not.toContain('undefined');
+      }
+      // Nothing was forked, from any workspace id.
+      expect(calls).toEqual([]);
+    });
+
+    /**
+     * `create_branch` compares `branch` (the fork base) to `name` and refuses
+     * the two being equal, QUOTING the name. A call that sent neither compared
+     * undefined to undefined, matched, and answered "not 'undefined', the draft
+     * being created" — an absent value presented as a draft name. `name` is
+     * refused by name instead, so no such sentence can be produced.
+     */
+    it('refuses a missing `name` without quoting it back', async () => {
+      const base = await start();
+
+      const res = await post(`${base}/api/agent/tools/create_branch`, writeTok(), { branch: 'main' });
+
+      expect(res.status).toBe(400);
+      const answered = await res.json();
+      expect(answered).toEqual({ kind: 'name-required', error: '`name` is required: pass the name of the draft to create.' });
+      expect(JSON.stringify(answered)).not.toContain('undefined');
+      expect(calls).toEqual([]);
+    });
+
+    it('still forks from a named base once both inputs are given', async () => {
+      const base = await start();
+      // The guards refuse absent inputs, not the tool.
+      const res = await post(`${base}/api/agent/tools/create_branch`, writeTok(), { name: 'alice/new-draft', branch: 'main' });
+
+      expect(res.status).toBe(200);
+      expect(calls).toContainEqual(['createBranch', 'main', 'alice/new-draft']);
+    });
+
+    it('refuses the stringified absent values the same way', async () => {
+      const base = await start();
+      for (const literal of ['undefined', 'null']) {
+        const res = await post(`${base}/api/agent/tools/commit_change`, writeTok(), { summary: 's', branch: literal });
+        expect(res.status, `branch "${literal}" must 400`).toBe(400);
+        expect((await res.json()).kind).toBe('branch-required');
+      }
+      expect(calls).toEqual([]);
+    });
+
+    it('leaves a tool that declares no `branch` alone', async () => {
+      const base = await start();
+      // `list_branches` is repo-global and deliberately takes no branch: the
+      // guard must not start demanding one from the tools that opted out.
+      expect((await post(`${base}/api/agent/tools/list_branches`, writeTok(), {})).status).toBe(200);
+    });
+  });
+
   it('works under a connection key too (both surface)', async () => {
     const base = await start();
-    expect((await post(`${base}/api/agent/tools/commit_change`, 'bevel_key', { summary: 's' })).status).toBe(200);
+    // `branch` is named because every caller must name it — this test is about
+    // the connection-key SURFACE, and an external key is precisely the caller
+    // that carries no focused branch to fall back on.
+    expect((await post(`${base}/api/agent/tools/commit_change`, 'bevel_key', { summary: 's', branch: WS })).status).toBe(200);
   });
 
   it('switch_branch validates + pre-warms + emits a user-scoped event (internal-only)', async () => {