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

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

@@ -11,9 +11,16 @@ import type { IReviewWorkflowService } from '../review-workflow/review-workflow.
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import { FileLockService } from '../file-lock.service.js';
-import { PendingCommitsService } from '../pending-commits.service.js';
+import { PendingCommitsService, type PendingCommit } from '../pending-commits.service.js';
+import { PendingCommitsWorker } from '../pending-commits.worker.js';
+import { HttpCommunicationProtocol } from '@utcp/http';
 import { WorkflowService } from '../workflow.service.js';
-import { PullRebaseConflictError, WorkflowDomainError } from '../../../shared/domain-errors.js';
+import {
+  PullRebaseConflictError,
+  PushNeedsAgentResolutionError,
+  WorkflowDomainError,
+} from '../../../shared/domain-errors.js';
+import type { WorkflowEventBus } from '../event-bus.js';
 import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import type { Database } from '../../database/connection.js';
 import { openChangeGate } from '../../../__tests__/open-change-gate.js';
@@ -121,6 +128,7 @@ function makePendingCommits(): PendingCommitsService {
     markNeedsAttention: vi.fn().mockResolvedValue(undefined),
     listNeedsAttention: vi.fn().mockResolvedValue([]),
     countPending: vi.fn().mockResolvedValue(0),
+    queuedOnBranch: vi.fn().mockResolvedValue({ queued: 0, stuck: 0, needsAttention: null }),
     hasAnyForWorkspace: vi.fn().mockResolvedValue(false),
     startupReconcile: vi.fn().mockResolvedValue(undefined),
   } as unknown as PendingCommitsService;
@@ -182,7 +190,7 @@ function makeGit(): GitService {
     listBranches: vi.fn(),
     createBranch: vi.fn(),
     switchBranch: vi.fn(),
-    deleteBranch: vi.fn(),
+    deleteBranch: vi.fn(async () => ({ lastCommit: null })),
     forkCurrentToDraft: vi.fn(),
     discardChanges: vi.fn(),
     commit: vi.fn(),
@@ -529,8 +537,8 @@ describe('WorkflowService — file lock delegation', () => {
     let releaseFirst!: () => void;
     const gate = new Promise<void>((resolve) => { releaseFirst = resolve; });
     vi.mocked(git.deleteBranch)
-      .mockImplementationOnce(async () => { order.push('first:start'); await gate; order.push('first:end'); })
-      .mockImplementationOnce(async () => { order.push('second'); });
+      .mockImplementationOnce(async () => { order.push('first:start'); await gate; order.push('first:end'); return { lastCommit: null }; })
+      .mockImplementationOnce(async () => { order.push('second'); return { lastCommit: null }; });
     const svc = new WorkflowService(makeDb(), git, makePrs(), makeReviewWorkflow(), makeWorkspaceService(), makeAccessControl(), makeFileLockService(), makePendingCommits(), testKbContext(), openChangeGate());
     const first = svc.deleteBranch('w1', 'feat/x', makeUser());
     const second = svc.deleteBranch('w1', 'feat/x', makeUser());
@@ -581,6 +589,7 @@ describe('WorkflowService — revertChangeRequestFile / closeEmptyChangeRequest'
     canWriteAtRef?: boolean | null;
     prState?: string;
     updateRows?: unknown[];
+    events?: WorkflowEventBus;
   } = {}) {
     const git = opts.git ?? makeRevertGit();
     const prs = makePrs();
@@ -607,7 +616,7 @@ describe('WorkflowService — revertChangeRequestFile / closeEmptyChangeRequest'
       returning: vi.fn(async () => updateRows),
     });
     const db = chain as unknown as Database;
-    const svc = new WorkflowService(db, git, prs, makeReviewWorkflow(), makeWorkspaceService(), access, fileLocks, makePendingCommits(), testKbContext(), openChangeGate());
+    const svc = new WorkflowService(db, git, prs, makeReviewWorkflow(), makeWorkspaceService(), access, fileLocks, makePendingCommits(), testKbContext(), openChangeGate(), opts.events);
     return { svc, git, prs, access, fileLocks, db: chain };
   }
 
@@ -744,6 +753,130 @@ describe('WorkflowService — revertChangeRequestFile / closeEmptyChangeRequest'
     expect(fileLocks.release).toHaveBeenCalledTimes(2);
   });
 
+  describe('when the repository host refuses the push', () => {
+    // What GitHub answered during its 2026-10-07 incident, credential and all.
+    const REFUSED = new Error(
+      "git push failed: remote: Internal Server Error\nTo https://x-access-token:ghp_abc123@github.com/acme/kb.git\n ! [remote rejected] ali/x -> ali/x (Internal Server Error)",
+    );
+    const kindsOf = (emit: ReturnType<typeof vi.fn>) =>
+      emit.mock.calls
+        .map((c) => (c[0] as { kind: string }).kind)
+        .filter((k) => k.startsWith('git-sync-'));
+
+    it('keeps the revert committed locally, answers 409 with the saved-locally sentence, and raises the banner', async () => {
+      const emit = vi.fn();
+      const git = makeRevertGit({
+        push: vi.fn().mockRejectedValue(REFUSED),
+        // A refused push is not a divergence — but "rejected" reads like one,
+        // so the cooperative pull runs first; it changes nothing here.
+        pull: vi.fn().mockResolvedValue({ treeChanged: false }),
+      });
+      const { svc, fileLocks, prs, db } = makeHarness({ git, events: { emit } as unknown as WorkflowEventBus });
+
+      const err = await svc.revertChangeRequestFile(7, makeUser(), 'Docs/a.md').catch((e: unknown) => e);
+      expect(err).toBeInstanceOf(PushNeedsAgentResolutionError);
+      const refusal = err as PushNeedsAgentResolutionError;
+      expect(refusal.status).toBe(409);
+      expect(refusal.message).toContain('Saved locally on "ali/x"');
+      expect(refusal.message).toContain('the repository host refused the push');
+      // The browser receives message + payload: neither carries git output.
+      const body = JSON.stringify({ ...refusal.payload, error: refusal.message });
+      expect(body).not.toMatch(/Internal Server Error|remote rejected|ghp_|github\.com/);
+
+      // The local result stays: restored, committed, locks dropped, caches fresh.
+      expect(git.restorePathFromRef).toHaveBeenCalledWith('ali%2Fx', 'mb-sha', 'Docs/a.md');
+      expect(git.commitFile).toHaveBeenCalled();
+      expect(fileLocks.release).toHaveBeenCalled();
+      expect(prs.invalidateDetailCache).toHaveBeenCalledWith(7);
+      // Nothing is closed on the strength of a branch the host never received:
+      // the remaining files (read from the published refs) are not even asked.
+      expect(git.changedPathsForPr).toHaveBeenCalledTimes(1);
+      // Nor is a recorded apply failure erased: the published head it
+      // describes did not move.
+      expect(db.update).not.toHaveBeenCalled();
+
+      // The banner, on the request's source branch, in words — not git's.
+      const failed = emit.mock.calls.map((c) => c[0] as Record<string, unknown>).find((e) => e.kind === 'git-sync-failed');
+      expect(failed).toMatchObject({ workspaceId: 'ali/x', branch: 'ali/x' });
+      expect(String(failed?.reason)).not.toMatch(/Internal Server Error|remote|ghp_/);
+    });
+
+    it('clears the banner on the next push of that branch that lands', async () => {
+      const emit = vi.fn();
+      const push = vi.fn().mockRejectedValueOnce(REFUSED).mockRejectedValueOnce(REFUSED).mockResolvedValue(undefined);
+      const git = makeRevertGit({ push, pull: vi.fn().mockResolvedValue({ treeChanged: false }) });
+      const { svc } = makeHarness({ git, events: { emit } as unknown as WorkflowEventBus });
+
+      await expect(svc.revertChangeRequestFile(7, makeUser(), 'Docs/a.md')).rejects.toBeInstanceOf(
+        PushNeedsAgentResolutionError,
+      );
+      // The host is back; the next push of the branch carries the revert.
+      await svc.shareCurrentBranch('ali%2Fx', makeUser());
+      expect(kindsOf(emit)).toEqual(['git-sync-failed', 'git-sync-recovered']);
+      expect(emit).toHaveBeenLastCalledWith(
+        expect.objectContaining({ kind: 'git-sync-recovered', workspaceId: 'ali/x' }),
+      );
+    });
+
+    it('a divergence whose retry push the host then refuses is answered as a refusal, not a divergence', async () => {
+      const push = vi
+        .fn()
+        .mockRejectedValueOnce(new Error('! [rejected] ali/x -> ali/x (non-fast-forward)'))
+        .mockRejectedValueOnce(REFUSED);
+      const git = makeRevertGit({ push, pull: vi.fn().mockResolvedValue({ treeChanged: true }) });
+      const { svc } = makeHarness({ git });
+
+      const err = await svc.revertChangeRequestFile(7, makeUser(), 'Docs/a.md').catch((e: unknown) => e);
+      expect(err).toBeInstanceOf(PushNeedsAgentResolutionError);
+      expect((err as PushNeedsAgentResolutionError).message).toContain('the repository host refused the push');
+      expect(push).toHaveBeenCalledTimes(2);
+    });
+
+    it('a recovery whose PULL the host refuses says the credentials cannot reach the repository, not "push"', async () => {
+      const emit = vi.fn();
+      const push = vi.fn().mockRejectedValue(new Error('! [rejected] ali/x -> ali/x (non-fast-forward)'));
+      const pull = vi
+        .fn()
+        // The freshen pull is best-effort; the recovery pull is the one that counts.
+        .mockResolvedValueOnce({ treeChanged: false })
+        .mockRejectedValue(
+          new Error("fatal: unable to access 'https://github.com/acme/kb.git/': The requested URL returned error: 403"),
+        );
+      const git = makeRevertGit({ push, pull });
+      const { svc } = makeHarness({ git, events: { emit } as unknown as WorkflowEventBus });
+
+      await expect(svc.revertChangeRequestFile(7, makeUser(), 'Docs/a.md')).rejects.toBeInstanceOf(
+        PushNeedsAgentResolutionError,
+      );
+      const failed = emit.mock.calls.map((c) => c[0] as Record<string, unknown>).find((e) => e.kind === 'git-sync-failed');
+      expect(failed?.reason).toBe(
+        "The repository host did not give this server's credentials access to this repository.",
+      );
+      expect(push).toHaveBeenCalledTimes(1);
+    });
+
+    it('a non-fast-forward still takes the cooperative pull-rebase, then lands', async () => {
+      const emit = vi.fn();
+      const push = vi
+        .fn()
+        .mockRejectedValueOnce(new Error('! [rejected] ali/x -> ali/x (non-fast-forward)'))
+        .mockResolvedValue(undefined);
+      const pull = vi.fn().mockResolvedValue({ treeChanged: true });
+      const git = makeRevertGit({ push, pull });
+      const { svc } = makeHarness({ git, events: { emit } as unknown as WorkflowEventBus });
+
+      await expect(svc.revertChangeRequestFile(7, makeUser(), 'Docs/a.md')).resolves.toMatchObject({ closed: false });
+      expect(push).toHaveBeenCalledTimes(2);
+      // Once to freshen the checkout, once as the cooperative recovery —
+      // both replay merges as merges, so a merge a refused open or update
+      // stranded on the branch is not flattened before this push publishes it.
+      expect(pull).toHaveBeenCalledTimes(2);
+      expect(pull).toHaveBeenNthCalledWith(1, 'ali%2Fx', { preserveMerges: true });
+      expect(pull).toHaveBeenNthCalledWith(2, 'ali%2Fx', { preserveMerges: true });
+      expect(kindsOf(emit)).not.toContain('git-sync-failed');
+    });
+  });
+
   it('never reverts a placeholder when that would leave the folder with nothing', async () => {
     const git = makeRevertGit({
       changedPathsForPr: vi
@@ -1019,7 +1152,7 @@ describe('WorkflowService.mergeBranch — an agent merges branches, never an ope
   // being published.
   const TARGET_TIP = 'target-tip-sha';
 
-  function harness(opts: { canWrite?: Map<string, boolean> | null } = {}) {
+  function harness(opts: { canWrite?: Map<string, boolean> | null; pending?: PendingCommitsService } = {}) {
     const git = makeGit();
     (git as unknown as Record<string, unknown>).remoteBranchExists = vi.fn().mockResolvedValue(true);
     (git as unknown as Record<string, unknown>).hasUnpushedCommits = vi.fn().mockResolvedValue(false);
@@ -1062,15 +1195,17 @@ describe('WorkflowService.mergeBranch — an agent merges branches, never an ope
           ).changedPathsForPr(workspaceId, target, source, { forAccessCheck: true });
           await mergeOpts.authorize({ sha: TARGET_TIP, changedPaths });
         }
-        return { kind: 'merged', sha: 'merge-sha' };
+        // The real contract: `mergeCommit` is the commit this merge made, null when it made none.
+        return { kind: 'merged', sha: 'merge-sha', mergeCommit: 'merge-sha' };
       },
     );
     const access = makeAccessControl();
     (access.canWriteBatchAtRef as ReturnType<typeof vi.fn>).mockResolvedValue(opts.canWrite === undefined ? null : opts.canWrite);
     const workspaceService = makeWorkspaceService();
-    const svc = new WorkflowService(makeDb([OPEN_REQUEST]), git, makePrs(), makeReviewWorkflow(), workspaceService, access, makeFileLockService(), makePendingCommits(), testKbContext(), openChangeGate());
+    const pending = opts.pending ?? makePendingCommits();
+    const svc = new WorkflowService(makeDb([OPEN_REQUEST]), git, makePrs(), makeReviewWorkflow(), workspaceService, access, makeFileLockService(), pending, testKbContext(), openChangeGate());
     const merge = (git as unknown as { mergeChangeRequest: ReturnType<typeof vi.fn> }).mergeChangeRequest;
-    return { svc, git, access, merge };
+    return { svc, git, access, merge, pending };
   }
 
   it('refuses to merge a source into the target of its open change request, naming the request', async () => {
@@ -1187,3 +1322,326 @@ describe('WorkflowService.mergeBranch — an agent merges branches, never an ope
     expect(merge.mock.calls[0][5]).toMatchObject({ requireCleanTarget: true });
   });
 });
+
+/**
+ * Opening a request pushes its source after the auto-merge. A push the host
+ * refuses must not undo the open: the merge is committed locally, the request
+ * is a DB row, and the next push of the branch carries the commits.
+ */
+describe('WorkflowService.openChangeRequest — when the repository host refuses the push', () => {
+  const INPUT = { sourceBranch: 'ali/x', targetBranch: 'main', title: 'Tidy the glossary' };
+
+  function makeOpenHarness(push: ReturnType<typeof vi.fn>) {
+    const emit = vi.fn();
+    const git = Object.assign(makeGit(), {
+      mergeFromOrigin: vi.fn().mockResolvedValue({ kind: 'clean', alreadyUpToDate: false }),
+      push,
+      pull: vi.fn().mockResolvedValue({ treeChanged: false }),
+    }) as unknown as GitService;
+    const prs = makePrs();
+    (prs.listOpenPrs as ReturnType<typeof vi.fn>).mockResolvedValue([]);
+    (prs.getPrDetail as ReturnType<typeof vi.fn>).mockResolvedValue({ number: 12, branch: 'ali/x', base: 'main' });
+    const values = vi.fn(() => ({ returning: vi.fn(async () => [{ number: 12 }]) }));
+    const db = { insert: vi.fn(() => ({ values })) } as unknown as Database;
+    const svc = new WorkflowService(
+      db, git, prs, makeReviewWorkflow(), makeWorkspaceService(), makeAccessControl(),
+      makeFileLockService(), makePendingCommits(), testKbContext(), openChangeGate(),
+      { emit } as unknown as WorkflowEventBus,
+    );
+    return { svc, git, prs, values, emit };
+  }
+
+  it('creates the request, then answers 409 with the saved-locally sentence and raises the banner', async () => {
+    const refused = new Error(
+      'git push failed: remote: Internal Server Error\n ! [remote rejected] ali/x -> ali/x (Internal Server Error)',
+    );
+    const h = makeOpenHarness(vi.fn().mockRejectedValue(refused));
+
+    const err = await h.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(PushNeedsAgentResolutionError);
+    const refusal = err as PushNeedsAgentResolutionError;
+    expect(refusal.status).toBe(409);
+    expect(refusal.message).toContain('Saved locally on "ali/x"');
+    expect(JSON.stringify({ ...refusal.payload, error: refusal.message })).not.toMatch(/Internal Server Error|remote rejected/);
+
+    // The request exists — the row was inserted and announced.
+    expect(h.values).toHaveBeenCalledWith(expect.objectContaining({ sourceBranch: 'ali/x', targetBranch: 'main' }));
+    expect(h.prs.invalidateDetailCache).toHaveBeenCalledWith(12);
+    const kinds = h.emit.mock.calls.map((c) => (c[0] as { kind: string }).kind);
+    expect(kinds).toContain('change-request-opened');
+    expect(h.emit).toHaveBeenCalledWith(
+      expect.objectContaining({ kind: 'git-sync-failed', workspaceId: 'ali/x', branch: 'ali/x' }),
+    );
+  });
+
+  it('a push that lands answers the detail as before, with no banner', async () => {
+    const h = makeOpenHarness(vi.fn().mockResolvedValue(undefined));
+    await expect(h.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT)).resolves.toMatchObject({ number: 12 });
+    expect(h.git.push).toHaveBeenCalledWith('ali%2Fx', expect.objectContaining({ email: 'alice@example.com' }));
+    const kinds = h.emit.mock.calls.map((c) => (c[0] as { kind: string }).kind);
+    expect(kinds).not.toContain('git-sync-failed');
+  });
+
+  it('a non-fast-forward recovers with a merge-preserving pull, and the request opens', async () => {
+    const push = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('! [rejected] ali/x -> ali/x (fetch first)'))
+      .mockResolvedValue(undefined);
+    const h = makeOpenHarness(push);
+    await expect(h.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT)).resolves.toMatchObject({ number: 12 });
+    expect(h.git.pull).toHaveBeenCalledWith('ali%2Fx', { preserveMerges: true });
+    expect(push).toHaveBeenCalledTimes(2);
+  });
+});
+
+/**
+ * Writes are committed asynchronously: a write tool answers once the bytes are
+ * on disk, and the pending-commits worker commits and pushes them seconds
+ * later. `mergeBranch` merges what the REMOTE holds of the source, so it waits
+ * for the source's queue first — bounded, outside the lifecycle locks — and
+ * says plainly when there was nothing to merge.
+ */
+describe('WorkflowService.mergeBranch — waits for the source branch\'s pending commits', () => {
+  const SOURCE = 'alice/other';
+  const TARGET = 'alice/feat';
+
+  function row(over: Partial<PendingCommit> = {}): PendingCommit {
+    return {
+      id: `row-${Math.random()}`,
+      workspaceId: encodeURIComponent(SOURCE),
+      branch: SOURCE,
+      path: 'knowledge-base/Notes/New.md',
+      authorEmail: 'alice@example.com',
+      authorName: 'Alice',
+      queuedAt: new Date(),
+      status: 'pending',
+      attempts: 0,
+      recoveryAgentRuns: 0,
+      lastAttemptedAt: null,
+      lastError: null,
+      ...over,
+    };
+  }
+
+  /**
+   * An in-memory `pending_commits` table with the methods the worker and
+   * `mergeBranch` use — the same rules as the SQL: `markSucceeded` deletes the
+   * row, `queuedOnBranch` counts `pending` + `running` and reports the first
+   * `needs_attention` row's message.
+   */
+  function memoryQueue(rows: PendingCommit[] = []) {
+    const table = [...rows];
+    const service = {
+      enqueue: vi.fn(async (input: { workspaceId: string; branch: string; path: string; authorEmail: string; authorName: string }) => {
+        table.push(row({ ...input }));
+      }),
+      claimNext: vi.fn(async (workspaceId: string) => {
+        const next = table.find((r) => r.workspaceId === workspaceId && r.status === 'pending');
+        if (next) next.status = 'running';
+        return next ?? null;
+      }),
+      hasReadyRow: vi.fn(async (workspaceId: string) => table.some((r) => r.workspaceId === workspaceId && r.status === 'pending')),
+      markSucceeded: vi.fn(async (id: string) => {
+        table.splice(table.findIndex((r) => r.id === id), 1);
+      }),
+      markTransientFailure: vi.fn(async () => undefined),
+      markRecoveryStarted: vi.fn(async () => undefined),
+      markNeedsAttention: vi.fn(async () => undefined),
+      queuedOnBranch: vi.fn(async (branch: string) => {
+        const mine = table.filter((r) => r.branch === branch);
+        const stuck = mine.filter((r) => r.status === 'needs_attention');
+        return {
+          queued: mine.filter((r) => r.status === 'pending' || r.status === 'running').length,
+          stuck: stuck.length,
+          needsAttention: stuck[0] ? stuck[0].lastError : null,
+        };
+      }),
+    };
+    return { service: service as unknown as PendingCommitsService & typeof service, table };
+  }
+
+  function harness(pending: PendingCommitsService, wait = { timeoutMs: 20_000, pollMs: 20 }) {
+    const git = makeGit();
+    (git as unknown as Record<string, unknown>).remoteBranchExists = vi.fn().mockResolvedValue(true);
+    const merge = vi.fn(async (): Promise<unknown> => ({ kind: 'merged', sha: 'merge-sha', mergeCommit: 'merge-sha' }));
+    (git as unknown as Record<string, unknown>).mergeChangeRequest = merge;
+    const svc = new WorkflowService(
+      makeDb([{ number: 12, sourceBranch: 'alice/feat', targetBranch: DEFAULT_BRANCH, state: 'open' }]),
+      git, makePrs(), makeReviewWorkflow(), makeWorkspaceService(), makeAccessControl(), makeFileLockService(),
+      pending, testKbContext(), openChangeGate(),
+    );
+    svc.mergeWaitForPendingCommits = wait;
+    return { svc, git, merge };
+  }
+
+  it('lands a write still queued on the source: the worker commits it while the merge waits, no retry', async () => {
+    // The shared remote, as `mergeChangeRequest` sees it: what each branch has
+    // been PUSHED with. The write below is on disk, not here yet.
+    const remote = new Map<string, Set<string>>([[SOURCE, new Set()], [TARGET, new Set()]]);
+    const { service } = memoryQueue();
+    const { svc, merge } = harness(service);
+    merge.mockImplementation(async () => {
+      const missing = [...remote.get(SOURCE)!].filter((p) => !remote.get(TARGET)!.has(p));
+      if (missing.length === 0) return { kind: 'merged', sha: 'target-tip', mergeCommit: null };
+      missing.forEach((p) => remote.get(TARGET)!.add(p));
+      return { kind: 'merged', sha: 'merge-commit', mergeCommit: 'merge-commit' };
+    });
+
+    // The REAL worker drains the queue; its commit driver pushes to the remote
+    // after a moment, the way a commit + push takes a few seconds.
+    const worker = new PendingCommitsWorker({
+      service,
+      workflow: {
+        runPendingCommit: async (_ws: string, branch: string, path: string) => {
+          await new Promise((r) => setTimeout(r, 150));
+          remote.get(branch)!.add(path);
+        },
+      },
+      recoveryAgent: { run: vi.fn() } as never,
+      feedback: { notify: vi.fn() } as never,
+      workspaces: { knownWorkspaces: () => [{ id: encodeURIComponent(SOURCE), branch: SOURCE }] },
+      recoveryBot: { id: 'bot', email: 'bot@example.com', name: 'Bot' },
+    });
+
+    // The write tool answered: the bytes are on disk and a row is queued.
+    await service.enqueue({
+      workspaceId: encodeURIComponent(SOURCE),
+      branch: SOURCE,
+      path: 'knowledge-base/Notes/New.md',
+      authorEmail: 'alice@example.com',
+      authorName: 'Alice',
+    });
+    worker.start();
+    try {
+      // …and the agent merges in the same breath.
+      const outcome = await svc.mergeBranch(makeUser(), SOURCE, TARGET);
+      expect(outcome).toEqual({ kind: 'merged', sha: 'merge-commit' });
+      expect(remote.get(TARGET)!.has('knowledge-base/Notes/New.md')).toBe(true);
+      // One merge, after the commit landed — not an empty one first.
+      expect(merge).toHaveBeenCalledTimes(1);
+      expect(service.queuedOnBranch.mock.calls.length).toBeGreaterThan(1);
+    } finally {
+      await worker.stop();
+    }
+  });
+
+  it('answers pending-commits after the bound when the source\'s commit cannot land, and merges nothing', async () => {
+    // The worker is stopped: the row stays queued.
+    const { service } = memoryQueue([row()]);
+    const { svc, merge, git } = harness(service, { timeoutMs: 200, pollMs: 20 });
+    const started = Date.now();
+    const outcome = await svc.mergeBranch(makeUser(), SOURCE, TARGET);
+    expect(Date.now() - started).toBeGreaterThanOrEqual(190);
+    expect(outcome).toEqual({
+      kind: 'pending-commits',
+      branch: SOURCE,
+      pending: 1,
+      message: expect.stringMatching(/still being committed.*Nothing was merged.*Retry the merge shortly/),
+    });
+    expect(merge).not.toHaveBeenCalled();
+    expect(git.pull).not.toHaveBeenCalled();
+  });
+
+  it('bounds the wait well inside the timeout an agent\'s call is forwarded under', () => {
+    const svc = new WorkflowService(
+      makeDb(), makeGit(), makePrs(), makeReviewWorkflow(), makeWorkspaceService(), makeAccessControl(),
+      makeFileLockService(), makePendingCommits(), testKbContext(), openChangeGate(),
+    );
+    // Over `/api/mcp` the call reaches the tool through `@utcp/http`, whose
+    // request timeout cannot be set per template. A wait that ran to that
+    // ceiling answered "timeout of 30000ms exceeded" instead of
+    // `pending-commits` (Local Testing, attempt 1). The wait and the merge after
+    // it must both fit, so the bound leaves ten seconds for the merge.
+    const forwarding = (new HttpCommunicationProtocol() as unknown as { _axiosInstance: { defaults: { timeout: number } } })
+      ._axiosInstance.defaults.timeout;
+    expect(forwarding).toBe(30_000);
+    expect(svc.mergeWaitForPendingCommits.timeoutMs).toBe(20_000);
+    expect(forwarding - svc.mergeWaitForPendingCommits.timeoutMs).toBeGreaterThanOrEqual(10_000);
+  });
+
+  it('answers pending-commits at once, with the worker\'s message, when a queued commit needs attention', async () => {
+    const { service } = memoryQueue([
+      row({ status: 'needs_attention', lastError: 'push rejected: protected ref' }),
+      row(),
+    ]);
+    // The default 20-second bound: an answer well inside it shows no wait.
+    const { svc, merge } = harness(service, { timeoutMs: 20_000, pollMs: 20 });
+    const started = Date.now();
+    const outcome = await svc.mergeBranch(makeUser(), SOURCE, TARGET);
+    expect(Date.now() - started).toBeLessThan(1_000);
+    expect(outcome).toEqual({
+      kind: 'pending-commits',
+      branch: SOURCE,
+      pending: 2,
+      needsAttention: 'push rejected: protected ref',
+      message: expect.stringContaining('push rejected: protected ref'),
+    });
+    expect(service.queuedOnBranch).toHaveBeenCalledTimes(1);
+    expect(merge).not.toHaveBeenCalled();
+  });
+
+  it('answers nothing-to-merge with the target\'s tip when the source has nothing the target lacks', async () => {
+    const { svc, merge } = harness(memoryQueue().service);
+    merge.mockResolvedValue({ kind: 'merged', sha: 'target-tip', mergeCommit: null });
+    expect(await svc.mergeBranch(makeUser(), SOURCE, TARGET)).toEqual({ kind: 'nothing-to-merge', sha: 'target-tip' });
+    expect(merge).toHaveBeenCalledTimes(1);
+  });
+
+  it('answers merged with the merge commit when the source has commits the target lacks and nothing is pending', async () => {
+    const { svc } = harness(memoryQueue().service);
+    expect(await svc.mergeBranch(makeUser(), SOURCE, TARGET)).toEqual({ kind: 'merged', sha: 'merge-sha' });
+  });
+
+  it('answers conflicts-need-resolution with the paths, as before', async () => {
+    const { svc, merge } = harness(memoryQueue().service);
+    merge.mockResolvedValue({ kind: 'conflicts', paths: ['A.md'] });
+    expect(await svc.mergeBranch(makeUser(), SOURCE, TARGET)).toEqual({
+      kind: 'conflicts-need-resolution',
+      conflictedPaths: ['A.md'],
+    });
+  });
+
+  it('refuses a merge an open change request proposes before any waiting', async () => {
+    // A queued commit that would hold the merge for the full bound.
+    const { service } = memoryQueue([row({ branch: 'alice/feat' })]);
+    const { svc, merge } = harness(service, { timeoutMs: 20_000, pollMs: 20 });
+    const started = Date.now();
+    const err = await svc.mergeBranch(makeUser(), 'alice/feat', DEFAULT_BRANCH).catch((e: unknown) => e);
+    expect(Date.now() - started).toBeLessThan(1_000);
+    expect(err).toMatchObject({ status: 409, payload: { kind: 'open-change-request-blocks-merge', number: 12 } });
+    expect(service.queuedOnBranch).not.toHaveBeenCalled();
+    expect(merge).not.toHaveBeenCalled();
+  });
+
+  it('holds neither branch\'s lifecycle lock while it waits', async () => {
+    const { service, table } = memoryQueue([row()]);
+    const { svc, git } = harness(service, { timeoutMs: 5_000, pollMs: 20 });
+    (git.createBranch as ReturnType<typeof vi.fn>).mockResolvedValue({ name: 'x' });
+    const merging = svc.mergeBranch(makeUser(), SOURCE, TARGET);
+    let mergeDone = false;
+    void merging.then(() => (mergeDone = true));
+    await new Promise((r) => setTimeout(r, 50));
+    // Both keys `runOnBranchPair` takes: work under either completes while
+    // the merge is still waiting on the source's queue.
+    await svc.createBranch(encodeURIComponent(TARGET), TARGET);
+    await svc.createBranch(encodeURIComponent(SOURCE), SOURCE);
+    expect(git.createBranch).toHaveBeenCalledTimes(2);
+    expect(mergeDone).toBe(false);
+    // The commit lands; the merge goes on.
+    table.splice(0, table.length);
+    expect(await merging).toEqual({ kind: 'merged', sha: 'merge-sha' });
+  });
+
+  it('leaves the app\'s change-request apply as it was: no wait, same outcome', async () => {
+    const { service } = memoryQueue([row({ branch: 'alice/feat' })]);
+    const prs = makePrs();
+    const reviewWorkflow = makeReviewWorkflow();
+    const mergeResult = { prNumber: 4, sha: 'abc', mergedAt: 't' };
+    (reviewWorkflow.mergePr as ReturnType<typeof vi.fn>).mockResolvedValue(mergeResult);
+    (prs.getPr as ReturnType<typeof vi.fn>).mockResolvedValue({ branch: 'alice/feat', base: 'main' });
+    const svc = new WorkflowService(makeDb(), makeGit(), prs, reviewWorkflow, makeWorkspaceService(), makeAccessControl(), makeFileLockService(), service, testKbContext(), openChangeGate());
+    const outcome = await svc.mergeChangeRequest(4, makeUser(), 'sha', [], 'open', 'PR title', 'main', 'w1', { bypass: true });
+    expect(outcome).toEqual({ kind: 'merged', result: mergeResult });
+    expect(service.queuedOnBranch).not.toHaveBeenCalled();
+  });
+});

package/src/modules/workflow/__tests__/workflow.service.folder-proposals.test.ts

@@ -281,6 +281,10 @@ describe('WorkflowService.removeFolderFromChangeRequests', () => {
     expect(closed).toEqual([40]);
     expect([...changed.get(elsewhere.branch)!]).toEqual(['Data/ReportsArchive/old.md']);
 
+    // Each source checkout is brought up to date replaying merges as merges:
+    // a merge a refused open or update stranded there must not be flattened.
+    expect(git.pull).toHaveBeenCalledWith(aliceWs, { preserveMerges: true });
+    expect(git.pull).toHaveBeenCalledWith(bobWs, { preserveMerges: true });
     // Every checkout goes to git in ONE call, each file reverted to its merge base.
     expect(git.revertPathsAndPush).toHaveBeenCalledTimes(1);
     expect(plansOf(git)).toEqual([

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

@@ -599,7 +599,7 @@ describe('WorkflowService — git-sync visibility events', () => {
     expect(kinds()).toEqual(['file-changed', 'file-changed']);
   });
 
-  it('carries the branch and a sanitised reason for the banner', async () => {
+  it('carries the branch and a reason in words — never the git output — for the banner', async () => {
     const svc = makeFacade(
       makeGit({ pushBehavior: 'auth-fail' }),
       makeFileLocks(USER.id),
@@ -615,9 +615,10 @@ describe('WorkflowService — git-sync visibility events', () => {
       workspaceId: 'ws-1',
       branch: 'feat/x',
     });
-    expect((emitSpy.mock.calls[0][0] as { reason: string }).reason).toContain(
-      'Authentication failed',
-    );
+    // The kind of failure survives; git's own text stays in the server log.
+    const { reason } = emitSpy.mock.calls[0][0] as { reason: string };
+    expect(reason).toBe("The repository host did not accept this server's credentials.");
+    expect(reason).not.toContain('Authentication failed');
   });
 
   it('re-announces on every failure, so a session joining mid-outage still learns of it', async () => {