@bevel-software/platform-core-backend 0.13.6 → 0.15.1

package/src/modules/workflow/__tests__/workflow.service.branch-in-use.test.ts

@@ -0,0 +1,337 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { drizzle } from 'drizzle-orm/pg-proxy';
+import { configureBranchModel } from '@bevel-software/platform-shared';
+import type { GitService } from '../git/git.service.js';
+import type { PullRequestService } from '../git/pull-request.service.js';
+import type { IReviewWorkflowService } from '../review-workflow/review-workflow.interface.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { FileLockService } from '../file-lock.service.js';
+import type { PendingCommitsService } from '../pending-commits.service.js';
+import type { Database } from '../../database/connection.js';
+import { WorkflowService } from '../workflow.service.js';
+
+/**
+ * A branch is load-bearing for a change request at EITHER end.
+ *
+ * The regression: merging `X -> main` retired X while a second open request
+ * `Y -> X` still proposed INTO it. Every guard asked only "is X anybody's
+ * SOURCE?", so X was deleted and `Y -> X` became permanently unusable — it
+ * could not be read (the detail read resolves the target first), declined, or
+ * deleted, and the boot sweep looked at sources only, so it survived every
+ * restart.
+ *
+ * These tests run the REAL drizzle query against seeded rows (via the pg-proxy
+ * driver, which hands the generated SQL and its parameters to a callback)
+ * rather than a stub that answers by call order. That is deliberate: a mock
+ * blind to the `where` clause returns the same row whether the guard asks
+ * about one branch end or both, so it would pass just as happily against the
+ * source-only code this fixes — it could not detect the regression it exists
+ * for. Here, reverting `openChangeRequestOn` to a source-only lookup makes the
+ * seeded `Y -> X` row stop matching, and these tests fail.
+ */
+
+interface CrRow {
+  number: number;
+  source_branch: string;
+  target_branch: string;
+  state: string;
+}
+
+/**
+ * A `change_requests` table that answers the query it is actually given.
+ *
+ * The driver receives real SQL and real parameters, so the predicate is read
+ * back off the statement: every `"column" = $n` becomes a (column, value)
+ * pair. One value bound to SEVERAL columns is the either-end test and ORs
+ * across them (`source_branch = $1 or target_branch = $1`); distinct values
+ * AND together (`… and state = $2`). Non-`select` statements report one
+ * affected row, which is the guarded update in the sweep succeeding.
+ */
+function fakeDb(rows: CrRow[]) {
+  const statements: string[] = [];
+  const db = drizzle(async (sql: string, params: unknown[]) => {
+    statements.push(sql);
+    if (!/^\s*select/i.test(sql)) return { rows: [['row-id']] };
+
+    const projection = (/^\s*select\s+(.+?)\s+from\s/is.exec(sql)?.[1] ?? '')
+      .split(',')
+      .map((item) => item.trim().replace(/.*"(\w+)"$/, '$1'));
+
+    const byValue = new Map<unknown, string[]>();
+    for (const m of sql.matchAll(/"(\w+)"\s*=\s*\$(\d+)/g)) {
+      const value = params[Number(m[2]) - 1];
+      byValue.set(value, [...(byValue.get(value) ?? []), m[1]!]);
+    }
+
+    // Reading the predicate off the statement means the reader can go stale
+    // against a future drizzle that quotes, aliases or parameterises
+    // differently. That is survivable ONLY if it fails loudly: an unparsed
+    // WHERE would leave `byValue` empty, `every` over nothing is vacuously
+    // true, and every seeded row would match — which is exactly the blind
+    // mock this harness replaced, silently restored. So refuse to answer a
+    // statement this cannot actually read.
+    if (!projection.length || projection.some((c) => !/^\w+$/.test(c))) {
+      throw new Error(`fakeDb could not read the projection of: ${sql}`);
+    }
+    if (/\bwhere\b/i.test(sql) && byValue.size === 0) {
+      throw new Error(`fakeDb could not read the predicate of: ${sql}`);
+    }
+
+    const matched = rows.filter((row) =>
+      [...byValue].every(([value, columns]) =>
+        columns.some((c) => row[c as keyof CrRow] === value),
+      ),
+    );
+    return { rows: matched.map((row) => projection.map((c) => row[c as keyof CrRow])) };
+  });
+  return { db: db as unknown as Database, statements };
+}
+
+function makeService(db: Database, git: Partial<GitService>) {
+  return new WorkflowService(
+    db,
+    git as GitService,
+    { invalidateDetailCache: vi.fn() } as unknown as PullRequestService,
+    {} as IReviewWorkflowService,
+    {
+      getOrCreateForBranch: vi.fn(async () => ({ id: 'ws-target' })),
+      ensureRemotesFetched: vi.fn(async () => undefined),
+      hasBootstrappedWorkspace: vi.fn(async () => false),
+    } as unknown as WorkspaceService,
+    {} as IAccessControl,
+    {} as FileLockService,
+    {} as PendingCommitsService,
+    'knowledge-base',
+  );
+}
+
+const USER = { email: 'juan@example.com', name: 'Juan', id: 'u1' };
+
+/** The merged request, and a second one still proposing INTO its source. */
+const MERGED_23: CrRow = {
+  number: 23,
+  source_branch: 'juan/rfi',
+  target_branch: 'target-company-state',
+  state: 'merged',
+};
+const OPEN_24_INTO_RFI: CrRow = {
+  number: 24,
+  source_branch: 'juan/rfi-mock',
+  target_branch: 'juan/rfi',
+  state: 'open',
+};
+
+function retire(svc: WorkflowService, number: number, base: string) {
+  return (
+    svc as unknown as {
+      retireMergedSourceBranch(n: number, base: string, u: unknown): Promise<void>;
+    }
+  ).retireMergedSourceBranch(number, base, USER);
+}
+
+beforeEach(() => {
+  configureBranchModel({
+    defaultBranch: 'target-company-state',
+    protectedBranches: ['current-company-state', 'target-company-state'],
+  });
+});
+
+describe('post-merge branch retirement', () => {
+  it('keeps a branch another open request proposes INTO', async () => {
+    const deleted: string[] = [];
+    const { db, statements } = fakeDb([MERGED_23, OPEN_24_INTO_RFI]);
+    const svc = makeService(db, {
+      deleteBranch: vi.fn(async (_ws: string, name: string) => void deleted.push(name)),
+    });
+
+    await retire(svc, 23, 'target-company-state');
+
+    expect(deleted).toEqual([]);
+    // The guard must ask about both ends — a statement naming only
+    // `source_branch` is the regression.
+    expect(statements.some((q) => /target_branch/.test(q))).toBe(true);
+  });
+
+  it('still retires a branch nothing open needs', async () => {
+    const deleted: string[] = [];
+    // #24 is gone; only the merged request remains, so nothing needs the branch.
+    const { db } = fakeDb([MERGED_23]);
+    const svc = makeService(db, {
+      deleteBranch: vi.fn(async (_ws: string, name: string) => void deleted.push(name)),
+    });
+
+    await retire(svc, 23, 'target-company-state');
+
+    expect(deleted).toEqual(['juan/rfi']);
+  });
+
+  it('keeps a branch another open request proposes FROM', async () => {
+    const deleted: string[] = [];
+    const { db } = fakeDb([
+      MERGED_23,
+      { number: 25, source_branch: 'juan/rfi', target_branch: 'other', state: 'open' },
+    ]);
+    const svc = makeService(db, {
+      deleteBranch: vi.fn(async (_ws: string, name: string) => void deleted.push(name)),
+    });
+
+    await retire(svc, 23, 'target-company-state');
+
+    expect(deleted).toEqual([]);
+  });
+});
+
+describe('deleteBranch', () => {
+  it('refuses a branch an open request proposes INTO, naming who can act', async () => {
+    const { db } = fakeDb([OPEN_24_INTO_RFI]);
+    const svc = makeService(db, { deleteBranch: vi.fn() });
+
+    // Not "withdraw or decline it": the request belongs to someone else, and
+    // the branch owner may be authorized to do neither. The message has to
+    // say what the situation is and who can clear it.
+    await expect(svc.deleteBranch('ws', 'juan/rfi', USER)).rejects.toThrow(
+      /change request #24 proposes changes into "juan\/rfi"/,
+    );
+  });
+
+  it('refuses a branch an open request proposes FROM, offering the withdraw verb', async () => {
+    const { db } = fakeDb([
+      { number: 26, source_branch: 'juan/rfi', target_branch: 'target-company-state', state: 'open' },
+    ]);
+    const svc = makeService(db, { deleteBranch: vi.fn() });
+
+    await expect(svc.deleteBranch('ws', 'juan/rfi', USER)).rejects.toThrow(
+      /open change request \(#26\)\. Withdraw or decline it/,
+    );
+  });
+
+  it('allows a branch no open request names', async () => {
+    const deleted: string[] = [];
+    const { db } = fakeDb([OPEN_24_INTO_RFI]);
+    const svc = makeService(db, {
+      deleteBranch: vi.fn(async (_ws: string, name: string) => void deleted.push(name)),
+    });
+
+    await svc.deleteBranch('ws', 'juan/unrelated', USER);
+
+    expect(deleted).toEqual(['juan/unrelated']);
+  });
+});
+
+describe('runOnBranchPair', () => {
+  function deferred() {
+    let resolve!: () => void;
+    const promise = new Promise<void>((r) => { resolve = r; });
+    return { promise, resolve };
+  }
+
+  type LockInternals = {
+    branchLifecycle: { run(key: string, fn: () => Promise<void>): Promise<void> };
+    runOnBranchPair(source: string, target: string, fn: () => Promise<void>): Promise<void>;
+  };
+
+  function locks(svc: WorkflowService) {
+    return svc as unknown as LockInternals;
+  }
+
+  it('waits on an unprotected target: its key really is reserved', async () => {
+    const { db } = fakeDb([]);
+    const svc = locks(makeService(db, {}));
+    const order: string[] = [];
+    const release = deferred();
+
+    const holder = svc.branchLifecycle.run('branch:juan/rfi', async () => {
+      await release.promise;
+      order.push('holder');
+    });
+    await new Promise((r) => setImmediate(r));
+
+    const pair = svc.runOnBranchPair('juan/other', 'juan/rfi', async () => {
+      order.push('pair');
+    });
+    await new Promise((r) => setImmediate(r));
+    expect(order).toEqual([]);
+
+    release.resolve();
+    await Promise.all([holder, pair]);
+    expect(order).toEqual(['holder', 'pair']);
+  });
+
+  it('does not reserve a PROTECTED target key', async () => {
+    // No path in the system can delete a protected branch, so the key would
+    // exclude nothing while serializing every open into the default branch,
+    // which is where nearly all requests point. The pair operation must run
+    // even while something else holds the protected branch's key.
+    const { db } = fakeDb([]);
+    const svc = locks(makeService(db, {}));
+    const order: string[] = [];
+    const release = deferred();
+
+    const holder = svc.branchLifecycle.run('branch:target-company-state', async () => {
+      await release.promise;
+      order.push('holder');
+    });
+    await new Promise((r) => setImmediate(r));
+
+    await svc.runOnBranchPair('juan/other', 'target-company-state', async () => {
+      order.push('pair');
+    });
+    expect(order).toEqual(['pair']);
+
+    release.resolve();
+    await holder;
+  });
+
+  it('always reserves the source key', async () => {
+    const { db } = fakeDb([]);
+    const svc = locks(makeService(db, {}));
+    const order: string[] = [];
+    const release = deferred();
+
+    const holder = svc.branchLifecycle.run('branch:juan/other', async () => {
+      await release.promise;
+      order.push('holder');
+    });
+    await new Promise((r) => setImmediate(r));
+
+    const pair = svc.runOnBranchPair('juan/other', 'target-company-state', async () => {
+      order.push('pair');
+    });
+    await new Promise((r) => setImmediate(r));
+    expect(order).toEqual([]);
+
+    release.resolve();
+    await Promise.all([holder, pair]);
+    expect(order).toEqual(['holder', 'pair']);
+  });
+});
+
+describe('closeChangeRequestsWithDeletedBranches', () => {
+  it('closes a request whose TARGET branch is gone', async () => {
+    const { db } = fakeDb([OPEN_24_INTO_RFI]);
+    const svc = makeService(db, {
+      // #24's source lives on; its target `juan/rfi` is gone.
+      listBranches: vi.fn(async () => [
+        { name: 'target-company-state' },
+        { name: 'juan/rfi-mock' },
+      ]),
+    } as unknown as Partial<GitService>);
+
+    await expect(svc.closeChangeRequestsWithDeletedBranches()).resolves.toBe(1);
+  });
+
+  it('leaves a request whose branches both exist', async () => {
+    const { db } = fakeDb([
+      { ...OPEN_24_INTO_RFI, target_branch: 'target-company-state' },
+    ]);
+    const svc = makeService(db, {
+      listBranches: vi.fn(async () => [
+        { name: 'target-company-state' },
+        { name: 'juan/rfi-mock' },
+      ]),
+    } as unknown as Partial<GitService>);
+
+    await expect(svc.closeChangeRequestsWithDeletedBranches()).resolves.toBe(0);
+  });
+});

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

@@ -83,6 +83,7 @@ function makeGit(overrides: Partial<{
     }),
     pull: vi.fn().mockImplementation(async () => {
       if (pullBehavior === 'fail') throw new Error('git pull failed: merge conflict');
+      return { treeChanged: true };
     }),
   } as unknown as GitService;
 }

package/src/modules/workflow/__tests__/workflow.service.deleted-branch-sweep.test.ts

@@ -114,7 +114,13 @@ describe('closeChangeRequestsWithDeletedBranches', () => {
       { name: 'x' },
     ]);
     await svc.closeChangeRequestsWithDeletedBranches();
-    expect(git.listBranches).toHaveBeenCalledWith('target-company-state', { freshFetch: true });
+    expect(git.listBranches).toHaveBeenCalledWith('target-company-state', {
+      freshFetch: true,
+      // Strict: a fetch that cannot be proven fresh throws instead of serving
+      // stale refs, and the sweep's catch closes nothing. Without this, a
+      // branch created after the clone's last good fetch reads as "deleted".
+      strictFetch: true,
+    });
   });
 
   /**

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

@@ -16,14 +16,61 @@ import { PullRebaseConflictError } from '../../../shared/domain-errors.js';
 import type { Database } from '../../database/connection.js';
 
 // `deleteBranch`'s open-request guard is the only DB touch these tests
-// exercise: a chainable select→from→where→limit stub resolving `rows` covers
-// it (rows default to "no open request").
-function makeDb(rows: unknown[] = []): Database {
+// exercise. The stub ANSWERS FROM THE WHERE-CLAUSE rather than returning the
+// rows unfiltered — a guard that dropped the `state = 'open'` filter or asked
+// about only one branch end used to pass these tests anyway, because any row
+// came back regardless of the predicate.
+//
+// The evaluator walks the drizzle condition tree (duck-typing the
+// SQL/Column/Param/StringChunk shapes) and evaluates it against the row:
+// an `eq(column, value)` leaf compares the row's field, and a node combines
+// its children with whichever connector its literal chunks carry (`and` /
+// `or` — drizzle nests them, so one node never mixes both).
+function rowMatches(cond: unknown, row: Record<string, unknown>): boolean {
+  // snake_case column → camelCase row field (the stubs carry row objects in
+  // the service's own field names).
+  const field = (col: string) => col.replace(/_([a-z])/g, (_, ch: string) => ch.toUpperCase());
+  const evalNode = (node: unknown): boolean => {
+    const chunks = (node as { queryChunks?: unknown[] }).queryChunks;
+    if (!Array.isArray(chunks)) return true;
+    const results: boolean[] = [];
+    let anyOr = false;
+    let pendingColumn: string | null = null;
+    for (const c of chunks) {
+      if (!c || typeof c !== 'object') continue;
+      if ('queryChunks' in c) {
+        results.push(evalNode(c));
+      } else if ('name' in c && 'keyAsName' in c) {
+        pendingColumn = String((c as { name: unknown }).name);
+      } else if ('encoder' in c && 'value' in c) {
+        if (pendingColumn !== null) {
+          results.push(row[field(pendingColumn)] === (c as { value: unknown }).value);
+          pendingColumn = null;
+        }
+      } else if ('value' in c) {
+        if (String((c as { value: unknown }).value).includes(' or ')) anyOr = true;
+      }
+    }
+    // A node this walker cannot decompose (`inArray`, `isNull`, a future
+    // rewrite of the query) must NOT read as a match — `true` here would be
+    // the permissive direction, returning rows the real query excludes and
+    // masking exactly the guard regressions these tests exist to catch.
+    if (results.length === 0) return false;
+    return anyOr ? results.some(Boolean) : results.every(Boolean);
+  };
+  return evalNode(cond);
+}
+
+function makeDb(rows: Record<string, unknown>[] = []): Database {
+  let lastWhere: unknown;
   const chain = {
     select: vi.fn(() => chain),
     from: vi.fn(() => chain),
-    where: vi.fn(() => chain),
-    limit: vi.fn(async () => rows),
+    where: vi.fn((cond: unknown) => {
+      lastWhere = cond;
+      return chain;
+    }),
+    limit: vi.fn(async () => rows.filter((r) => rowMatches(lastWhere, r))),
   };
   return chain as unknown as Database;
 }
@@ -135,7 +182,7 @@ function makeGit(): GitService {
     commit: vi.fn(),
     push: vi.fn(),
     fetch: vi.fn(),
-    pull: vi.fn(),
+    pull: vi.fn().mockResolvedValue({ treeChanged: true }),
     diffStat: vi.fn(),
     pendingChanges: vi.fn(),
     resolveForkBase: vi.fn(),
@@ -435,11 +482,27 @@ describe('WorkflowService — file lock delegation', () => {
   it('deleteBranch refuses while the branch carries an open change request', async () => {
     const git = makeGit();
     // One open request rides the branch — deleting it would strand the request.
-    const svc = new WorkflowService(makeDb([{ number: 7 }]), git, makePrs(), makeReviewWorkflow(), makeWorkspaceService(), makeAccessControl(), makeFileLockService(), makePendingCommits(), 'knowledge-base');
+    // `sourceBranch` matters to the guard now: it decides whether the refusal
+    // says "withdraw yours" (source) or names the other request's actors (target).
+    const svc = new WorkflowService(makeDb([{ number: 7, sourceBranch: 'feat/x', targetBranch: 'dev', state: 'open' }]), git, makePrs(), makeReviewWorkflow(), makeWorkspaceService(), makeAccessControl(), makeFileLockService(), makePendingCommits(), 'knowledge-base');
     await expect(svc.deleteBranch('w1', 'feat/x', makeUser())).rejects.toThrow(/open change request \(#7\)/);
     expect(git.deleteBranch).not.toHaveBeenCalled();
   });
 
+  it('deleteBranch refuses when an open request proposes INTO the branch (target end)', async () => {
+    const git = makeGit();
+    const svc = new WorkflowService(makeDb([{ number: 9, sourceBranch: 'other/y', targetBranch: 'feat/x', state: 'open' }]), git, makePrs(), makeReviewWorkflow(), makeWorkspaceService(), makeAccessControl(), makeFileLockService(), makePendingCommits(), 'knowledge-base');
+    await expect(svc.deleteBranch('w1', 'feat/x', makeUser())).rejects.toThrow(/proposes changes into/);
+    expect(git.deleteBranch).not.toHaveBeenCalled();
+  });
+
+  it('deleteBranch proceeds past a CLOSED request — the guard filters on state, not mere mention', async () => {
+    const git = makeGit();
+    const svc = new WorkflowService(makeDb([{ number: 7, sourceBranch: 'feat/x', targetBranch: 'dev', state: 'closed' }]), git, makePrs(), makeReviewWorkflow(), makeWorkspaceService(), makeAccessControl(), makeFileLockService(), makePendingCommits(), 'knowledge-base');
+    await expect(svc.deleteBranch('w1', 'feat/x', makeUser())).resolves.toBeUndefined();
+    expect(git.deleteBranch).toHaveBeenCalled();
+  });
+
   it('deleteBranch deletes when the branch has no open change request', async () => {
     const git = makeGit();
     const svc = new WorkflowService(makeDb(), git, makePrs(), makeReviewWorkflow(), makeWorkspaceService(), makeAccessControl(), makeFileLockService(), makePendingCommits(), 'knowledge-base');
@@ -496,7 +559,7 @@ describe('WorkflowService — revertChangeRequestFile / closeEmptyChangeRequest'
 
   function makeRevertGit(overrides: Record<string, unknown> = {}): GitService {
     return Object.assign(makeGit(), {
-      pull: vi.fn().mockResolvedValue(undefined),
+      pull: vi.fn().mockResolvedValue({ treeChanged: true }),
       changedPathsForPr: vi.fn().mockResolvedValue(['Docs/a.md', 'Docs/b.md']),
       mergeBaseForPr: vi.fn().mockResolvedValue('mb-sha'),
       restorePathFromRef: vi.fn().mockResolvedValue(undefined),
@@ -656,8 +719,9 @@ describe('WorkflowService — deleteChangeRequest (admin moderation verb)', () =
       set: vi.fn(() => chain),
       returning: vi.fn(async () => [{ id: 1 }]),
     });
-    const svc = new WorkflowService(chain as unknown as Database, git, prs, makeReviewWorkflow(), makeWorkspaceService(), access, makeFileLockService(), makePendingCommits(), 'knowledge-base');
-    return { svc, prs, db: chain, access };
+    const workspaces = makeWorkspaceService();
+    const svc = new WorkflowService(chain as unknown as Database, git, prs, makeReviewWorkflow(), workspaces, access, makeFileLockService(), makePendingCommits(), 'knowledge-base');
+    return { svc, prs, db: chain, access, workspaces };
   }
 
   it('refuses a non-admin with 403 and touches nothing', async () => {
@@ -678,4 +742,27 @@ describe('WorkflowService — deleteChangeRequest (admin moderation verb)', () =
     await expect(svc.deleteChangeRequest(9, makeUser())).rejects.toMatchObject({ status: 422 });
     expect(db.update).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(
+      new Error('Remote branch main not found in upstream origin'),
+    );
+    const sweep = vi.spyOn(svc, 'closeChangeRequestsWithDeletedBranches').mockResolvedValue(0);
+
+    // The failure still surfaces (it is not proven absence, so the verb must
+    // not pretend to succeed), but the sweep is kicked so a genuinely
+    // stranded request is closed without waiting for a restart.
+    await expect(svc.deleteChangeRequest(9, makeUser())).rejects.toThrow(/not found/);
+    expect(sweep).toHaveBeenCalledTimes(1);
+    expect(db.update).not.toHaveBeenCalled();
+  });
+
+  it('does not kick the sweep on a plain authorization refusal', async () => {
+    const { svc, db } = makeDeleteHarness({ isAdmin: false });
+    const sweep = vi.spyOn(svc, 'closeChangeRequestsWithDeletedBranches').mockResolvedValue(0);
+    await expect(svc.deleteChangeRequest(9, makeUser())).rejects.toMatchObject({ status: 403 });
+    expect(sweep).not.toHaveBeenCalled();
+    expect(db.update).not.toHaveBeenCalled();
+  });
 });

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

@@ -8,9 +8,10 @@ import type { IAccessControl } from '../../access/access-control.interface.js';
 import { FileLockService } from '../file-lock.service.js';
 import { PendingCommitsService } from '../pending-commits.service.js';
 import { WorkflowEventBus } from '../event-bus.js';
-import { WorkflowService } from '../workflow.service.js';
+import { WorkflowService, syncConflictMessage } from '../workflow.service.js';
 import type { Database } from '../../database/connection.js';
 import {
+  PullRebaseConflictError,
   PullRebaseConflictError,
   PushNeedsAgentResolutionError,
   WorkflowValidationError,
@@ -87,7 +88,7 @@ function makePending(): PendingCommitsService {
 function makeGit(overrides: Partial<{
   commitFile: Change | null;
   pushBehavior: 'ok' | 'nff' | 'auth-fail';
-  pullBehavior: 'ok' | 'fail';
+  pullBehavior: 'ok' | 'fail' | 'conflict';
   pushAfterPullBehavior: 'ok' | 'fail';
   hasUnpushedCommits: boolean;
 }> = {}): GitService {
@@ -120,6 +121,8 @@ function makeGit(overrides: Partial<{
     }),
     pull: vi.fn().mockImplementation(async () => {
       if (pullBehavior === 'fail') throw new Error('git pull failed: merge conflict');
+      if (pullBehavior === 'conflict') throw new PullRebaseConflictError('feat/x', ['foo.md'], 'CONFLICT (content)');
+      return { treeChanged: true };
     }),
   } as unknown as GitService;
 }
@@ -460,6 +463,29 @@ describe('WorkflowService.runPendingCommit — worker entry point', () => {
     ]);
   });
 
+  it('a rebase CONFLICT on the recovery path raises the banner WITH its files, like the remote sync does', async () => {
+    // The banner keeps the latest failure per branch. The remote sync raises
+    // the conflict variant (files as links); if this path then raised the
+    // generic variant for the same conflict, the retry would take the links
+    // away — seen on staging. Every path names the files.
+    const git = makeGit({
+      commitFile: null,
+      hasUnpushedCommits: true,
+      pushBehavior: 'nff',
+      pullBehavior: 'conflict',
+    });
+    const svc = makeFacade(git, makeFileLocks(USER.id), makePending(), events);
+    await expect(svc.runPendingCommit('ws-1', 'feat/x', 'foo.md', USER)).rejects.toBeInstanceOf(
+      PushNeedsAgentResolutionError,
+    );
+    const failed = emitSpy.mock.calls.map((c) => c[0] as Record<string, unknown>).find((e) => e.kind === 'git-sync-failed');
+    expect(failed).toMatchObject({
+      branch: 'feat/x',
+      conflictedPaths: ['foo.md'],
+      reason: syncConflictMessage('feat/x', ['foo.md']),
+    });
+  });
+
   it('recovers from non-fast-forward push via pull --rebase + retry, emits file-changed exactly once', async () => {
     // Teammate pushed to the same branch between our commit and our
     // push. The cooperative path pulls + retries — this is the case
@@ -750,3 +776,94 @@ describe('WorkflowService.updateFromRemote — pull-conflict recovery dispatch',
     await expect(svc.updateFromRemote('main', USER)).rejects.toBe(CONFLICT);
   });
 });
+
+describe('WorkflowService.updateFromRemote — the tree-change announcement', () => {
+  /**
+   * The announcement under test is what keeps the DEFAULT branch's catalog
+   * caches (skills, tool manuals, plugin index) honest: a pull is the one way
+   * a tree changes without passing the write routes, so `pullWorkspace` owes
+   * the process an `fs-tree-changed` — and owes it ONLY when the pull moved
+   * HEAD, on the default branch, after the pull resolved. Asserted through
+   * `updateFromRemote`, the public verb that wraps `pullWorkspace`.
+   */
+  const DEFAULT_WS = 'target-company-state'; // == the test env's DEFAULT_BRANCH
+
+  function makePullingGit(result: { treeChanged: boolean } | Error): {
+    git: GitService;
+    pullSettled: () => boolean;
+  } {
+    let settled = false;
+    const git = {
+      pull: vi.fn().mockImplementation(async () => {
+        // A microtask gap, so an emit issued before the await would be
+        // observably premature rather than coincidentally ordered.
+        await Promise.resolve();
+        settled = true;
+        if (result instanceof Error) throw result;
+        return result;
+      }),
+    } as unknown as GitService;
+    return { git, pullSettled: () => settled };
+  }
+
+  function treeChangedEvents(emitSpy: MockInstance): unknown[] {
+    return emitSpy.mock.calls
+      .map((c) => c[0] as { kind: string })
+      .filter((e) => e.kind === 'fs-tree-changed');
+  }
+
+  it('emits fs-tree-changed for the default workspace once the pull has changed the tree', async () => {
+    const events = new WorkflowEventBus();
+    const emitSpy = vi.spyOn(events, 'emit');
+    const { git, pullSettled } = makePullingGit({ treeChanged: true });
+    let settledAtEmit: boolean | undefined;
+    emitSpy.mockImplementation(() => {
+      settledAtEmit = pullSettled();
+    });
+    const svc = makeFacade(git, makeFileLocks(USER.id), makePending(), events);
+
+    await svc.updateFromRemote(DEFAULT_WS, USER);
+
+    expect(treeChangedEvents(emitSpy)).toEqual([
+      { kind: 'fs-tree-changed', workspaceId: DEFAULT_WS, branch: DEFAULT_WS },
+    ]);
+    // After the pull RESOLVED — an emit for a pull that later failed would
+    // make other clients refetch a tree that never changed.
+    expect(settledAtEmit).toBe(true);
+  });
+
+  it('stays silent when the pull found nothing new (treeChanged: false)', async () => {
+    const events = new WorkflowEventBus();
+    const emitSpy = vi.spyOn(events, 'emit');
+    const { git } = makePullingGit({ treeChanged: false });
+    const svc = makeFacade(git, makeFileLocks(USER.id), makePending(), events);
+
+    await svc.updateFromRemote(DEFAULT_WS, USER);
+
+    // An "already up to date" sync must not drop the catalogs or make every
+    // attached browser refetch its file tree.
+    expect(treeChangedEvents(emitSpy)).toEqual([]);
+  });
+
+  it('stays silent for a non-default workspace even when the tree changed', async () => {
+    const events = new WorkflowEventBus();
+    const emitSpy = vi.spyOn(events, 'emit');
+    const { git } = makePullingGit({ treeChanged: true });
+    const svc = makeFacade(git, makeFileLocks(USER.id), makePending(), events);
+
+    await svc.updateFromRemote(encodeURIComponent('alice/draft'), USER);
+
+    expect(treeChangedEvents(emitSpy)).toEqual([]);
+  });
+
+  it('stays silent when the pull throws', async () => {
+    const events = new WorkflowEventBus();
+    const emitSpy = vi.spyOn(events, 'emit');
+    const { git } = makePullingGit(new Error('git fetch failed: could not resolve host'));
+    const svc = makeFacade(git, makeFileLocks(USER.id), makePending(), events);
+
+    await expect(svc.updateFromRemote(DEFAULT_WS, USER)).rejects.toThrow();
+
+    expect(treeChangedEvents(emitSpy)).toEqual([]);
+  });
+});