@bevel-software/platform-core-backend 0.25.2 → 0.27.0

package/src/modules/workflow/review-workflow/__tests__/merge-records-own-commit.test.ts

@@ -0,0 +1,407 @@
+import { describe, it, expect, vi } from 'vitest';
+
+import { PgDialect } from 'drizzle-orm/pg-core';
+import type { SQL } from 'drizzle-orm';
+import { ReviewWorkflowService } from '../review-workflow.service.js';
+import { changeRequests, prMergeLog } from '../../../database/schema.js';
+import type { Database } from '../../../database/connection.js';
+import type { WorkspaceService } from '../../../workspace/workspace.service.js';
+import type { GitService } from '../../git/git.service.js';
+import type { AppliedMergeResult, AuthUser, FileApprovalState } from '@bevel-software/platform-shared';
+import type { IAccessControl } from '../../../access/access-control.interface.js';
+
+/**
+ * What `mergePr` records as a change request's `merged_sha`, which is the only
+ * thing an applied request's files can later be read from.
+ *
+ * Two shas come back from the merge and they are not interchangeable: `sha` is
+ * the state the target is left at, `mergeCommit` is the commit this request
+ * owns. Recording the first publishes another request's files under this
+ * request's number (cubic P1 on #347); dropping the second when a retry finds
+ * nothing left to merge makes an already-merged request permanently fileless
+ * (cubic P2 on #347). The row must take `mergeCommit`, exactly.
+ */
+
+const USER: AuthUser = { id: 'u-alice', email: 'alice@bevel.software', name: 'Alice' };
+const BASE = 'current-company-state';
+const HEAD_SHA = 'head-sha-1';
+
+const CR_ROW = {
+  id: 'cr-1',
+  number: 12,
+  sourceBranch: 'alice/add',
+  targetBranch: BASE,
+  title: 'Add a note',
+  body: '',
+  authorEmail: 'alice@bevel.software',
+  authorName: 'Alice',
+  state: 'open',
+};
+
+/**
+ * One approved file, which is all the gate needs to let the merge through: an
+ * empty approval set is itself a hard block ("no file changes to approve"), so
+ * the "nothing to merge" cases below are about git finding the change already on
+ * the target, never about a request with no files.
+ */
+const APPROVED: FileApprovalState = {
+  path: 'Knowledge/Ops/note.md',
+  eligibleApprovers: { roles: ['Ops'], users: [] },
+  approvedBy: [
+    {
+      name: 'Olga',
+      email: 'olga@bevel.software',
+      approvedAt: '2026-10-02T10:00:00Z',
+      isStale: false,
+      isSelfApproval: false,
+    },
+  ],
+  eligibilityResolved: true,
+  isApproved: true,
+  inMergeGate: true,
+  viewerCanApprove: false,
+};
+
+/**
+ * Every write the merge performs, in order, with the table it targeted and
+ * whether it was an insert or an update — the ORDER is part of what one of the
+ * tests below pins.
+ */
+type Captured = { kind: 'insert' | 'update'; table: unknown; values: Record<string, unknown> };
+
+/**
+ * What the row says, and whether the CAS wins, are PARAMETERS, not constants.
+ * `mergePr` and `finalizeAlreadyApplied` both re-validate the lifecycle against
+ * the row rather than against the caller's `state` argument, and a stub that
+ * always answers `open` and always wins leaves those paths unreachable — a
+ * regression that dropped one would still pass (cubic P3 on #347).
+ *
+ * `rows` is consumed in order and its last entry repeats, so a test can say
+ * what the row looked like when the attempt started and what it says when the
+ * lost CAS is explained.
+ */
+function makeDb(
+  captured: Captured[],
+  {
+    rows = [CR_ROW],
+    casWon = true,
+    begunLog = true,
+  }: { rows?: Record<string, unknown>[]; casWon?: boolean; begunLog?: boolean } = {},
+): Database {
+  let crReads = 0;
+  const thenable = (data: unknown) => {
+    const p = Promise.resolve(data) as Promise<unknown> & { limit: () => Promise<unknown> };
+    p.limit = () => Promise.resolve(data);
+    return p;
+  };
+  /**
+   * What the CAS compares against: the row's state at the moment of the
+   * update. `casWon` says the row is still open then; a lost CAS means it is
+   * what the LAST row says (the terminal state the lost CAS is explained by).
+   */
+  const stateAtCas = casWon ? 'open' : String(rows[rows.length - 1]?.state ?? 'merged');
+  return {
+    select: () => ({
+      from: (table: unknown) => ({
+        where: () => {
+          // The merge log begun by the attempt that pushed and crashed —
+          // `succeeded: false`, no error — is what makes a retry look for its
+          // commit at all.
+          if (table === prMergeLog) return thenable(begunLog ? [{ id: 'merge-log-0' }] : []);
+          if (table !== changeRequests) return thenable([]);
+          const row = rows[Math.min(crReads, rows.length - 1)];
+          crReads += 1;
+          return thenable([row]);
+        },
+      }),
+    }),
+    insert: (table: unknown) => ({
+      values: (values: Record<string, unknown>) => {
+        captured.push({ kind: 'insert', table, values });
+        return { returning: async () => [{ id: 'merge-log-1' }] };
+      },
+    }),
+    update: (table: unknown) => ({
+      set: (values: Record<string, unknown>) => {
+        captured.push({ kind: 'update', table, values });
+        return {
+          where: (predicate: SQL) => {
+            const t = thenable(undefined) as unknown as Promise<unknown> & {
+              returning: () => Promise<unknown>;
+            };
+            // The CAS is answered FROM THE WHERE CLAUSE, not from a flag: the
+            // update of the change request row lands only if the row is in
+            // the state the predicate asks for. A predicate that no longer
+            // guards on `state = 'open'` would therefore land on a terminal
+            // row here — which is the race this test file exists to pin, so
+            // dropping the guard fails the lost-CAS tests below instead of
+            // passing them by a stub that answered from `casWon` alone.
+            const { sql, params } = new PgDialect().sqlToQuery(predicate);
+            const guardsOpen = /"state"/.test(sql) && params.includes('open');
+            const lands = table !== changeRequests || !guardsOpen || stateAtCas === 'open';
+            t.returning = () => Promise.resolve(lands ? [{ id: CR_ROW.id }] : []);
+            return t;
+          },
+        };
+      },
+    }),
+  } as unknown as Database;
+}
+
+function makeService(mergeResult: AppliedMergeResult) {
+  const captured: Captured[] = [];
+  // Typed by its signature rather than its body, so the recorded call keeps the
+  // arguments the assertion below reads out of it.
+  const mergeChangeRequest = vi.fn<(...args: unknown[]) => Promise<AppliedMergeResult>>(
+    async () => mergeResult,
+  );
+  const workspace = {
+    ensureRemotesFetched: vi.fn(async () => undefined),
+    getOrCreateForBranch: vi.fn(async () => ({ id: 'ws-base' })),
+  } as unknown as WorkspaceService;
+  const svc = new ReviewWorkflowService(
+    makeDb(captured),
+    {} as unknown as IAccessControl,
+    workspace,
+    { mergeChangeRequest } as unknown as GitService,
+  );
+  const merge = () =>
+    svc.mergePr(CR_ROW.number, USER, HEAD_SHA, [APPROVED], 'open', CR_ROW.title, BASE, 'ws-1');
+  /** The values written to the change request row (not the merge log). */
+  const crUpdate = () => captured.find((c) => c.kind === 'update' && c.table === changeRequests)?.values;
+  return { merge, crUpdate, mergeChangeRequest };
+}
+
+describe('mergePr — which commit the row records', () => {
+  it('records the merge commit this request owns, not the state the target is left at', async () => {
+    const { merge, crUpdate } = makeService({
+      kind: 'merged',
+      sha: 'target-tip-which-is-another-requests-merge',
+      mergeCommit: 'this-requests-own-merge',
+    });
+
+    const result = await merge();
+
+    expect(crUpdate()).toMatchObject({ state: 'merged', mergedSha: 'this-requests-own-merge' });
+    // The caller still hears the state the target is at, which is what "merged"
+    // means for the request even when it is not a commit of its own.
+    expect(result.sha).toBe('target-tip-which-is-another-requests-merge');
+  });
+
+  it('records nothing when the request owns no merge commit', async () => {
+    // The genuinely empty request: the target already contained its change, and
+    // no attempt of its own ever wrote a commit. It has no file list to lose, and
+    // the target tip it is merged at belongs to somebody else.
+    const { merge, crUpdate } = makeService({
+      kind: 'merged',
+      sha: 'target-tip-which-is-another-requests-merge',
+      mergeCommit: null,
+    });
+
+    await merge();
+
+    expect(crUpdate()).toMatchObject({ state: 'merged', mergedSha: null });
+  });
+
+  it('names the request to the merge, so a retry can recognise its own commit', async () => {
+    // Without the number, a merge that finds nothing to merge cannot tell an
+    // empty request from one whose merge commit a previous attempt pushed before
+    // the row update failed — and would record null for both.
+    const { merge, mergeChangeRequest } = makeService({
+      kind: 'merged',
+      sha: 'tip',
+      mergeCommit: 'own',
+    });
+
+    await merge();
+
+    expect(mergeChangeRequest).toHaveBeenCalledTimes(1);
+    const opts = mergeChangeRequest.mock.calls[0][5] as { appliedChangeNumber?: number };
+    expect(opts.appliedChangeNumber).toBe(CR_ROW.number);
+  });
+});
+
+/**
+ * The retry the row-recording fix is FOR, reached the way production reaches it.
+ *
+ * When an attempt pushes the merge commit and then fails to write the row, the
+ * request stays open with its change already on the target — so it differs from
+ * the target by nothing, its file list is empty, and the approval gate refuses
+ * the next attempt ("no file changes to approve") before any merge runs. The
+ * recovery inside `mergeChangeRequest` is therefore never reached from the app,
+ * and the request stays fileless and un-appliable for good. The gate has to ask
+ * the ownership question itself.
+ */
+function makeStuckService(
+  own: string | null,
+  // The two states a merge is decided against, kept APART because the service
+  // treats them apart: `gateState` is the caller's (what drove the gate it
+  // clicked), `rowState` is the authoritative row's. A stale caller passing
+  // 'open' for a row that is already terminal is exactly what the row-level
+  // guard is for.
+  {
+    gateState = 'open',
+    rowState = 'open',
+    casWon = true,
+    // What the row says when the lost CAS is explained — a cancel closes a
+    // request just as a merge does, and the audit line must not guess.
+    stateAfterCas = 'merged',
+    // Whether an earlier attempt left a begun, never-completed merge-log row —
+    // the only evidence that there may be a pushed commit to recover.
+    begunLog = true,
+  }: {
+    gateState?: string;
+    rowState?: string;
+    casWon?: boolean;
+    stateAfterCas?: string;
+    begunLog?: boolean;
+  } = {},
+) {
+  const rows = [{ ...CR_ROW, state: rowState }, { ...CR_ROW, state: stateAfterCas }];
+  const captured: Captured[] = [];
+  const mergeChangeRequest = vi.fn<(...args: unknown[]) => Promise<AppliedMergeResult>>(async () => ({
+    kind: 'merged',
+    sha: 'should-not-be-reached',
+    mergeCommit: null,
+  }));
+  const appliedMergeCommitOnTarget = vi.fn(async () => own);
+  const workspace = {
+    getOrCreateForBranch: vi.fn(async () => ({ id: 'ws-base' })),
+  } as unknown as WorkspaceService;
+  const svc = new ReviewWorkflowService(
+    makeDb(captured, { rows, casWon, begunLog }),
+    {} as unknown as IAccessControl,
+    workspace,
+    { mergeChangeRequest, appliedMergeCommitOnTarget } as unknown as GitService,
+  );
+  // NO approvals: an already-applied request has no file to approve, which is
+  // exactly what makes it indistinguishable from an empty one at the gate.
+  const merge = () =>
+    svc.mergePr(CR_ROW.number, USER, HEAD_SHA, [], gateState as 'open', CR_ROW.title, BASE, 'ws-1');
+  const crUpdate = () => captured.find((c) => c.kind === 'update' && c.table === changeRequests)?.values;
+  return { merge, crUpdate, captured, mergeChangeRequest, appliedMergeCommitOnTarget, workspace };
+}
+
+describe('mergePr — a request whose merge commit was pushed but never recorded', () => {
+  it('asks git only when the database shows an attempt that began and never completed', async () => {
+    // A genuinely empty request — nothing on the target, no attempt behind it
+    // — is refused as it always was, and the refusal touches no clone and no
+    // remote: the probe that fetches the target runs only behind the one
+    // piece of evidence a crashed attempt leaves, its begun merge-log row.
+    const { merge, appliedMergeCommitOnTarget, workspace } = makeStuckService('a-commit', { begunLog: false });
+    await expect(merge()).rejects.toThrow(/no file changes to approve/i);
+    expect(appliedMergeCommitOnTarget).not.toHaveBeenCalled();
+    expect((workspace as unknown as { getOrCreateForBranch: ReturnType<typeof vi.fn> }).getOrCreateForBranch).not.toHaveBeenCalled();
+  });
+
+  it('hands the stored title to the probe, so a merge commit in the old message format is recognised', async () => {
+    const { merge, appliedMergeCommitOnTarget } = makeStuckService('a-commit');
+    await merge();
+    expect(appliedMergeCommitOnTarget).toHaveBeenCalledWith('ws-base', BASE, CR_ROW.number, CR_ROW.title);
+  });
+
+  it('records that commit instead of refusing, and merges nothing', async () => {
+    const { merge, crUpdate, mergeChangeRequest, appliedMergeCommitOnTarget } =
+      makeStuckService('the-commit-the-first-attempt-pushed');
+
+    const result = await merge();
+
+    expect(crUpdate()).toMatchObject({
+      state: 'merged',
+      mergedSha: 'the-commit-the-first-attempt-pushed',
+    });
+    expect(result.sha).toBe('the-commit-the-first-attempt-pushed');
+    // Asked of the TARGET branch's own workspace, for this request's number.
+    expect(appliedMergeCommitOnTarget).toHaveBeenCalledWith('ws-base', BASE, CR_ROW.number, CR_ROW.title);
+    // Nothing was merged, committed or pushed: the merge already happened.
+    expect(mergeChangeRequest).not.toHaveBeenCalled();
+  });
+
+  it('still refuses a request that owns no merge commit', async () => {
+    // The genuinely empty request. The hard block is the right answer for it,
+    // and the probe is what tells the two apart.
+    const { merge, crUpdate, mergeChangeRequest } = makeStuckService(null);
+
+    await expect(merge()).rejects.toThrow('no file changes to approve');
+
+    expect(crUpdate()).toBeUndefined();
+    expect(mergeChangeRequest).not.toHaveBeenCalled();
+  });
+
+  it('does not go looking when the hard block is the request\'s state', async () => {
+    // A closed or merged request earns its own refusal, and must keep it: the
+    // recovery is only ever about the empty-file-set block.
+    const { merge, appliedMergeCommitOnTarget, crUpdate } = makeStuckService('a-commit', { gateState: 'closed', rowState: 'closed' });
+
+    await expect(merge()).rejects.toThrow('This pull request is closed.');
+
+    expect(appliedMergeCommitOnTarget).not.toHaveBeenCalled();
+    expect(crUpdate()).toBeUndefined();
+  });
+
+  it('refuses when the AUTHORITATIVE row is already terminal, whatever the caller passed', async () => {
+    // The caller's gate inputs were resolved before a concurrent apply landed,
+    // so it still says `open` while the row says `merged`. The recovery runs
+    // ahead of `mergePr`'s own lifecycle re-check, so its own row-state guard is
+    // the only thing between a stale click and a second finalization.
+    const { merge, crUpdate, appliedMergeCommitOnTarget } = makeStuckService('a-commit', {
+      gateState: 'open',
+      rowState: 'merged',
+    });
+
+    await expect(merge()).rejects.toThrow('no file changes to approve');
+
+    expect(appliedMergeCommitOnTarget).not.toHaveBeenCalled();
+    expect(crUpdate()).toBeUndefined();
+  });
+
+  it('logs the attempt before it finalizes the row, and completes the log after', async () => {
+    // Order matters: a log write that failed after the CAS would leave a request
+    // recorded as merged with no attempt behind it, and the caller erroring on a
+    // request that IS merged. The attempt goes in first, carrying the commit it
+    // is about, and is completed once the row is won.
+    const { merge, captured } = makeStuckService('the-commit-the-first-attempt-pushed');
+
+    await merge();
+
+    const inserted = captured.find((c) => c.kind === 'insert');
+    expect(inserted?.values).toMatchObject({ succeeded: false, mergeMethod: 'merge' });
+    expect(String(inserted?.values.error)).toContain('the-commit-the-first-attempt-pushed');
+    // The log's completion comes AFTER the change request row is finalized.
+    const order = captured.map((c) => (c.kind === 'insert' ? 'log-insert' : c.table === changeRequests ? 'cr' : 'log-update'));
+    expect(order).toEqual(['log-insert', 'cr', 'log-update']);
+    expect(captured[2].values).toMatchObject({ succeeded: true });
+  });
+  it('names the state the row actually ended in when the CAS is lost to a CANCEL', async () => {
+    // A cancel closes a request exactly as a merge does, and both lose this CAS.
+    // Filing a cancellation as "a concurrent merge won" sends whoever reads
+    // pr_merge_log afterwards to the wrong cause (cubic P2 on #347).
+    const { merge, captured } = makeStuckService('a-commit', {
+      casWon: false,
+      stateAfterCas: 'closed',
+    });
+
+    await expect(merge()).rejects.toThrow('This change request is closed.');
+
+    const logUpdate = captured.filter((c) => c.kind === 'update' && c.table !== changeRequests).pop();
+    expect(logUpdate?.values).toMatchObject({ succeeded: false });
+    expect(String(logUpdate?.values.error)).toBe(
+      'Change request was no longer open (closed); this attempt did not finalize it.',
+    );
+    expect(String(logUpdate?.values.error)).not.toContain('concurrent');
+  });
+
+  it('says merged, and refuses as merged, when the CAS is lost to another merge', async () => {
+    const { merge, captured } = makeStuckService('a-commit', {
+      casWon: false,
+      stateAfterCas: 'merged',
+    });
+
+    await expect(merge()).rejects.toThrow('This change request has already been merged.');
+
+    const logUpdate = captured.filter((c) => c.kind === 'update' && c.table !== changeRequests).pop();
+    expect(String(logUpdate?.values.error)).toBe(
+      'Change request was no longer open (merged); this attempt did not finalize it.',
+    );
+  });
+});

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

@@ -1,4 +1,4 @@
-import { and, asc, eq } from 'drizzle-orm';
+import { and, asc, eq, isNull } from 'drizzle-orm';
 import { logger } from '../../../shared/logging.js';
 
 const log = logger('review-workflow');
@@ -18,6 +18,7 @@ import { changeRequests, prComments, prFileApprovals, prMergeLog, users } from '
 import { AccessUnreadableError } from '../../access-model/access-errors.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { GitService } from '../git/git.service.js';
+import { mergeCommitSubject } from '../git/merge-commit.js';
 import { redactSecret } from '../../../shared/redact-secret.js';
 import {
   ChangeRequestConflictsError,
@@ -44,6 +45,14 @@ import {
 // trail — squashing would collapse them into one. A merge commit preserves every
 // commit on the branch.
 const MERGE_METHOD = 'merge' as const;
+
+/**
+ * The hard block an empty file set earns — named, because two places have to
+ * agree on it: the gate that raises it, and `finalizeAlreadyApplied`, which
+ * recognises it as the one refusal that can mean "already applied" rather than
+ * "nothing to apply".
+ */
+const NOTHING_TO_APPROVE = 'This pull request has no file changes to approve.';
 const EVERYONE_CANONICAL = 'everyone';
 
 /**
@@ -239,7 +248,7 @@ function evaluateGateParts(input: MergeGateInput): { hardReasons: string[]; warn
   // mergeable either — a PR that touches no files shouldn't be opened in
   // the first place, let alone merged.
   if (input.approvals.length === 0 && input.state === 'open') {
-    reasons.push('This pull request has no file changes to approve.');
+    reasons.push(NOTHING_TO_APPROVE);
   }
 
   // Ownership enforcement binds every file with an eligible approver,
@@ -469,7 +478,8 @@ export class ReviewWorkflowService implements IReviewWorkflowService {
           if (batch) viewerCanApproveByPath = batch;
         } catch (err) {
           if (err instanceof AccessUnreadableError) throw err;
-          log.warn(`canWriteBatchAtRef failed for PR #${prNumber} viewer=${viewerEmail}:`, { err });
+          // The viewer is not named: log lines carry no email addresses.
+          log.warn(`canWriteBatchAtRef failed for PR #${prNumber} (for the viewer):`, { err });
         }
       }
     }
@@ -671,7 +681,17 @@ export class ReviewWorkflowService implements IReviewWorkflowService {
     // opted into bypass; with bypass, the bypassed warnings get inlined in the
     // merge commit body so git history captures the decision.
     const gate = evaluateGateParts({ prNumber, state, approvals });
-    if (gate.hardReasons.length > 0) throw new MergeBlockedError(gate.hardReasons);
+    if (gate.hardReasons.length > 0) {
+      // One of those reasons can mean the opposite of what it says. "No file
+      // changes to approve" is also what an ALREADY APPLIED request looks like:
+      // its change is on the target, so it differs from it by nothing. That is
+      // the state a request is left in when an attempt pushed its merge commit
+      // and then failed to record the row — and refusing the retry here is what
+      // kept the recovery inside the merge from ever running (cubic P2 on #347).
+      const recovered = await this.finalizeAlreadyApplied(prNumber, user, headSha, gate.hardReasons);
+      if (recovered) return recovered;
+      throw new MergeBlockedError(gate.hardReasons);
+    }
     if (gate.warnings.length > 0 && !opts.bypass) {
       throw new MergeBlockedError(gate.warnings);
     }
@@ -730,7 +750,9 @@ export class ReviewWorkflowService implements IReviewWorkflowService {
     // Attribution lives on the merge commit itself (authored as the human
     // triggerer). When bypass is used, the bypassed warnings are appended so the
     // decision survives in git history — no separate audit table needed.
-    const subject = `${prTitle} (#${prNumber})`;
+    // One place builds this, one place reads it back — `merge-commit.ts` says
+    // why an applied request's reader has to verify the subject at all.
+    const subject = mergeCommitSubject(prTitle, prNumber);
     const bypassFooter =
       opts.bypass && gate.warnings.length > 0
         ? `\n\nApproval requirements bypassed:\n${gate.warnings.map((w) => `- ${w}`).join('\n')}`
@@ -750,6 +772,10 @@ export class ReviewWorkflowService implements IReviewWorkflowService {
         cr.targetBranch,
         { subject, body },
         user,
+        // Named so a merge that finds nothing to merge can tell an empty request
+        // apart from one a previous attempt already merged and failed to record
+        // (see `ownMergeCommitOn`).
+        { appliedChangeNumber: prNumber, appliedChangeTitle: cr.title },
       );
     } catch (err) {
       const redacted = redactTokens(err instanceof Error ? err.message : String(err), this.git.credentials?.token());
@@ -780,16 +806,35 @@ export class ReviewWorkflowService implements IReviewWorkflowService {
     const completedAt = new Date();
     const [updatedCr] = await this.db
       .update(changeRequests)
-      .set({ state: 'merged', mergedSha: mergeResult.sha, closedAt: completedAt, updatedAt: completedAt })
+      .set({
+        state: 'merged',
+        // Only the commit this request OWNS, never `sha`. With nothing to merge
+        // `sha` is the target tip — usually another request's merge commit — and
+        // recording it here would let this request be read back with that other
+        // request's files under its number (cubic P1 on #347).
+        //
+        // `mergeCommit` is also what makes a retry after a failed finalization
+        // idempotent: the merge commit a previous attempt pushed is found and
+        // recorded instead of being dropped as "nothing was merged" (cubic P2 on
+        // #347). It is null only when the request has no merge commit at all,
+        // and such a request has no file list to lose.
+        mergedSha: mergeResult.mergeCommit,
+        closedAt: completedAt,
+        updatedAt: completedAt,
+      })
       .where(and(eq(changeRequests.id, cr.id), eq(changeRequests.state, 'open')))
       .returning({ id: changeRequests.id });
     if (!updatedCr) {
-      // A concurrent merge won the CAS between our lifecycle re-check and here.
-      // Our own git merge was a harmless idempotent no-op, but this attempt did
-      // NOT finalize the CR. Finalize this log row with an explanatory error and
-      // a completedAt so it doesn't linger as a phantom `succeeded=false,
-      // error=null` entry that a "failed merges" audit query would misread.
-      const raceError = 'Change request was merged by a concurrent request; this attempt did not finalize it.';
+      // Something else moved the row out of `open` between our lifecycle
+      // re-check and here. Our own git merge was a harmless idempotent no-op,
+      // but this attempt did NOT finalize the CR. Finalize this log row with an
+      // explanatory error and a completedAt so it doesn't linger as a phantom
+      // `succeeded=false, error=null` entry that a "failed merges" audit query
+      // would misread — and say only what the lost CAS proves, which is that the
+      // row was no longer open: a cancel closes it too, and naming a concurrent
+      // MERGE would file that cancellation under the wrong cause (cubic P2 on
+      // #347, raised against the copy of this line in `finalizeAlreadyApplied`).
+      const raceError = 'Change request was no longer open; this attempt did not finalize it.';
       await this.db
         .update(prMergeLog)
         .set({ succeeded: false, completedAt, error: raceError })
@@ -808,6 +853,140 @@ export class ReviewWorkflowService implements IReviewWorkflowService {
     };
   }
 
+  /**
+   * Record a change request that is ALREADY applied — its merge commit is on the
+   * target — and that the gate was about to refuse for having nothing to merge.
+   * Null when the request owns no such commit, which is every other reason an
+   * approval set can be empty.
+   *
+   * The case this exists for: an attempt pushed the merge commit and then failed
+   * to write the row (a transient database fault in between). The request stays
+   * `open` while its change is on the target, so the diff that produces its file
+   * list — and with it every approval the gate reads — is empty. The retry is
+   * then refused BEFORE the merge runs, which is where the recovery inside
+   * `mergeChangeRequest` sits, so the request can never be finalized: it is
+   * fileless, author-only, and un-appliable for good, with the commit holding
+   * its files sitting on the target unreferenced (cubic P2 on #347).
+   *
+   * Nothing is merged, committed or pushed here. The only write is the row that
+   * should have been written by the attempt that pushed, and the merge-log entry
+   * that says this caller finalized it.
+   *
+   * Narrow on purpose:
+   *   • exactly ONE hard reason, and it is the empty-file-set one. A request that
+   *     is already `merged` or `closed` has its own reason and must keep it.
+   *   • the row must still be `open`, read here and re-checked by the CAS below.
+   *   • the commit must be the request's OWN, by the same subject predicate the
+   *     reader verifies with (`mergeCommitSubjectNames`), so this records only
+   *     what `appliedChangeShas` will accept. No branch name a user can choose
+   *     can produce that subject — `assertValidBranchName` forbids both the space
+   *     and the `#` the agent `merge_branch` subject would need.
+   *
+   * Who may trigger it needs no extra check: the app resolves the request's
+   * detail for the caller first and refuses when it answers nothing, and a
+   * request with no readable file list is visible to its author alone. So the
+   * author is the one who can finalize their own stuck request.
+   */
+  private async finalizeAlreadyApplied(
+    prNumber: number,
+    user: AuthUser,
+    headSha: string,
+    hardReasons: string[],
+  ): Promise<MergePrResult | null> {
+    if (hardReasons.length !== 1 || hardReasons[0] !== NOTHING_TO_APPROVE) return null;
+
+    const [cr] = await this.db
+      .select()
+      .from(changeRequests)
+      .where(eq(changeRequests.number, prNumber))
+      .limit(1);
+    if (!cr || cr.state !== 'open' || !cr.targetBranch) return null;
+
+    // The cheap question first, of the database alone: did an attempt on this
+    // request push and then crash before recording? Such an attempt leaves its
+    // log row begun and never completed — `succeeded: false` with no error,
+    // the shape no finished attempt has. Without one there is nothing to
+    // recover, and a genuinely empty request is refused here as it always
+    // was, without a clone being created or a remote fetched on its behalf.
+    const [begun] = await this.db
+      .select({ id: prMergeLog.id })
+      .from(prMergeLog)
+      .where(and(eq(prMergeLog.prNumber, prNumber), eq(prMergeLog.succeeded, false), isNull(prMergeLog.error)))
+      .limit(1);
+    if (!begun) return null;
+
+    const baseWorkspace = await this.workspaceService.getOrCreateForBranch(cr.targetBranch);
+    const own = await this.git.appliedMergeCommitOnTarget(baseWorkspace.id, cr.targetBranch, prNumber, cr.title);
+    if (!own) return null;
+
+    // The attempt is logged BEFORE the row is finalized, in the same order the
+    // merge path logs its own: a log write that fails must not leave a request
+    // recorded as merged with no attempt behind it, and failing here fails
+    // before anything is committed, so the retry is clean (cubic P2 on #347).
+    const triggeredByEmail = canonicalEmail(user.email);
+    const [logRow] = await this.db
+      .insert(prMergeLog)
+      .values({
+        prNumber,
+        triggeredByEmail,
+        triggeredByEmailBidx: triggeredByEmail,
+        triggeredByName: user.name,
+        headShaAtMerge: headSha,
+        mergeMethod: MERGE_METHOD,
+        succeeded: false,
+        // Not an error — the one thing a reader of this row has to know is that
+        // no merge was performed under it, because it had already been
+        // performed. Written at the start so it survives a crash in between.
+        error: `Finalizing an earlier attempt's merge commit ${own}; nothing is merged by this one.`,
+      })
+      .returning({ id: prMergeLog.id });
+
+    // Same CAS as the merge path: a concurrent finalization wins and we say so
+    // rather than overwriting its terminal state.
+    const completedAt = new Date();
+    const [updated] = await this.db
+      .update(changeRequests)
+      .set({ state: 'merged', mergedSha: own, closedAt: completedAt, updatedAt: completedAt })
+      .where(and(eq(changeRequests.id, cr.id), eq(changeRequests.state, 'open')))
+      .returning({ id: changeRequests.id });
+    if (!updated) {
+      // The CAS loses to ANY terminal transition, not just a merge: `cancelPr`
+      // closes a request the same way. So the row is re-read and the reason it
+      // actually carries is what goes into the audit line and into the refusal
+      // — a cancellation filed as "a concurrent merge won" sends whoever reads
+      // pr_merge_log after the fact to the wrong cause (cubic P2 on #347).
+      const [current] = await this.db
+        .select({ state: changeRequests.state })
+        .from(changeRequests)
+        .where(eq(changeRequests.id, cr.id))
+        .limit(1);
+      const raceError =
+        `Change request was no longer open (${current?.state ?? 'row missing'}); this attempt did not finalize it.`;
+      await this.db
+        .update(prMergeLog)
+        .set({ succeeded: false, completedAt, error: raceError })
+        .where(eq(prMergeLog.id, logRow.id));
+      throw new MergeBlockedError([
+        current?.state === 'merged'
+          ? 'This change request has already been merged.'
+          : 'This change request is closed.',
+      ]);
+    }
+    await this.db
+      .update(prMergeLog)
+      .set({
+        succeeded: true,
+        completedAt,
+        error: `Finalized an earlier attempt's merge commit ${own}; nothing was merged by this one.`,
+      })
+      .where(eq(prMergeLog.id, logRow.id));
+    log.warn(
+      `change request #${prNumber} was already merged as ${own} but its row was never updated; recorded it now.`,
+    );
+
+    return { prNumber, sha: own, mergedAt: completedAt.toISOString() };
+  }
+
   async cancelPr(
     prNumber: number,
     user: AuthUser,