@bevel-software/platform-core-backend 0.3.2 → 0.4.0

package/src/modules/workflow/__tests__/pending-commits.enqueue-if-absent.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it, vi } from 'vitest';
+import { PendingCommitsService } from '../pending-commits.service.js';
+import type { Database } from '../../database/connection.js';
+
+/**
+ * `enqueueIfAbsent` backs the pull-conflict recovery dispatch: it must
+ * insert only when NO row exists for the (workspace, branch, path) in ANY
+ * status. A plain `enqueue` would refresh an existing pending row and reset
+ * its retry counters — and the dispatch path fires on every sync attempt,
+ * so those resets would starve the worker's ladder and the recovery agent
+ * would never spawn. A `needs_attention` row must also block re-entry (the
+ * ladder already escalated to a human; more agent runs are just a loop).
+ *
+ * Fake drizzle chain, same shape as the vault tests — the queue's SQL-level
+ * behavior (claim fencing etc.) is covered elsewhere; this pins the
+ * check-then-insert decision logic.
+ */
+function makeFakeDb(existingCount: number) {
+  const inserted: unknown[] = [];
+  const selectChain: any = {};
+  selectChain.from = vi.fn(() => selectChain);
+  selectChain.where = vi.fn(() => selectChain);
+  selectChain.then = (onF: any, onR: any) =>
+    Promise.resolve([{ count: existingCount }]).then(onF, onR);
+  const insertChain: any = {};
+  insertChain.values = vi.fn((v: unknown) => {
+    inserted.push(v);
+    return insertChain;
+  });
+  insertChain.then = (onF: any, onR: any) => Promise.resolve(undefined).then(onF, onR);
+  const db = {
+    select: vi.fn(() => selectChain),
+    insert: vi.fn(() => insertChain),
+  } as unknown as Database;
+  return { db, inserted };
+}
+
+const INPUT = {
+  workspaceId: 'razvan.radulescu/feature',
+  branch: 'razvan.radulescu/feature',
+  path: 'PR-Overviews/PR-7.html',
+  authorEmail: 'Alice@Example.com',
+  authorName: 'Alice',
+};
+
+describe('PendingCommitsService.enqueueIfAbsent', () => {
+  it('inserts (canonical workspace id, lowercased email) when no row exists', async () => {
+    const { db, inserted } = makeFakeDb(0);
+    const svc = new PendingCommitsService(db);
+
+    await expect(svc.enqueueIfAbsent(INPUT)).resolves.toBe(true);
+
+    expect(inserted).toHaveLength(1);
+    expect(inserted[0]).toMatchObject({
+      // Same canonicalization as `enqueue` — the worker claims per the
+      // ENCODED `knownWorkspaces()` id, so a decoded id would never drain.
+      workspaceId: 'razvan.radulescu%2Ffeature',
+      branch: 'razvan.radulescu/feature',
+      path: 'PR-Overviews/PR-7.html',
+      authorEmail: 'alice@example.com',
+      authorName: 'Alice',
+    });
+  });
+
+  it('is a no-op when ANY row exists for the tuple (pending, running, or needs_attention)', async () => {
+    const { db, inserted } = makeFakeDb(1);
+    const svc = new PendingCommitsService(db);
+
+    await expect(svc.enqueueIfAbsent(INPUT)).resolves.toBe(false);
+    expect(inserted).toHaveLength(0);
+  });
+});

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

@@ -11,6 +11,7 @@ import { WorkflowEventBus } from '../event-bus.js';
 import { WorkflowService } from '../workflow.service.js';
 import type { Database } from '../../database/connection.js';
 import {
+  PullRebaseConflictError,
   PushNeedsAgentResolutionError,
   WorkflowValidationError,
 } from '../workflow.errors.js';
@@ -66,6 +67,7 @@ function makeFileLocks(holderUserId: string): FileLockService {
 function makePending(): PendingCommitsService {
   return {
     enqueue: vi.fn().mockResolvedValue(undefined),
+    enqueueIfAbsent: vi.fn().mockResolvedValue(true),
     claimNext: vi.fn().mockResolvedValue(null),
     markSucceeded: vi.fn().mockResolvedValue(undefined),
     markTransientFailure: vi.fn().mockResolvedValue(undefined),
@@ -82,6 +84,7 @@ function makeGit(overrides: Partial<{
   pushBehavior: 'ok' | 'nff' | 'auth-fail';
   pullBehavior: 'ok' | 'fail';
   pushAfterPullBehavior: 'ok' | 'fail';
+  hasUnpushedCommits: boolean;
 }> = {}): GitService {
   const commitFileResult = overrides.commitFile === undefined ? CHANGE : overrides.commitFile;
   const pushBehavior = overrides.pushBehavior ?? 'ok';
@@ -90,6 +93,7 @@ function makeGit(overrides: Partial<{
   let pushCalls = 0;
   return {
     commitFile: vi.fn().mockResolvedValue(commitFileResult),
+    hasUnpushedCommits: vi.fn().mockResolvedValue(overrides.hasUnpushedCommits ?? false),
     push: vi.fn().mockImplementation(async () => {
       pushCalls++;
       const phase = pushCalls === 1 ? pushBehavior : pushAfterPullBehavior;
@@ -265,10 +269,10 @@ describe('WorkflowService.runPendingCommit — worker entry point', () => {
     });
   });
 
-  it('skips push + file-changed when commitFile reports nothing dirty (double-enqueue, identical bytes)', async () => {
+  it('skips push + file-changed on a no-op commit with nothing unpushed (double-enqueue, identical bytes)', async () => {
     // The worker treats a no-op commit as success and drops the row.
     // No push, no SSE event — there's no new sha for clients to see.
-    const git = makeGit({ commitFile: null });
+    const git = makeGit({ commitFile: null, hasUnpushedCommits: false });
     const svc = makeFacade(git, makeFileLocks(USER.id), makePending(), events);
 
     await svc.runPendingCommit('ws-1', 'feat/x', 'foo.md', USER);
@@ -278,6 +282,41 @@ describe('WorkflowService.runPendingCommit — worker entry point', () => {
     expect(emitSpy).not.toHaveBeenCalled();
   });
 
+  it('STILL pushes on a no-op commit when the branch is ahead of origin (stranded autosave commit)', async () => {
+    // Regression: the autosave path commits locally with a best-effort
+    // push. When that push fails, the eventual queue row finds a CLEAN
+    // tree — and the old early-return treated it as success, dropping the
+    // row without ever pushing. The local commit stayed stranded forever
+    // and the recovery ladder never started.
+    const git = makeGit({ commitFile: null, hasUnpushedCommits: true });
+    const svc = makeFacade(git, makeFileLocks(USER.id), makePending(), events);
+
+    await svc.runPendingCommit('ws-1', 'feat/x', 'foo.md', USER);
+
+    expect(git.push).toHaveBeenCalledTimes(1);
+    // No new commit → still no file-changed (there's no new sha).
+    expect(emitSpy).not.toHaveBeenCalled();
+  });
+
+  it('no-op commit + unpushed + conflicting divergence throws so the worker ladder takes over', async () => {
+    // The stranded-commit case where origin ALSO moved with a conflicting
+    // change (the production stuck-workspace state): push rejects non-FF,
+    // the cooperative pull conflicts — the typed error must reach the
+    // worker so its retry → recovery-agent ladder runs.
+    const git = makeGit({
+      commitFile: null,
+      hasUnpushedCommits: true,
+      pushBehavior: 'nff',
+      pullBehavior: 'fail',
+    });
+    const svc = makeFacade(git, makeFileLocks(USER.id), makePending(), events);
+
+    await expect(svc.runPendingCommit('ws-1', 'feat/x', 'foo.md', USER)).rejects.toBeInstanceOf(
+      PushNeedsAgentResolutionError,
+    );
+    expect(emitSpy).not.toHaveBeenCalled();
+  });
+
   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
@@ -338,3 +377,73 @@ describe('WorkflowService.runPendingCommit — worker entry point', () => {
     expect(emitSpy).not.toHaveBeenCalled();
   });
 });
+
+describe('WorkflowService.updateFromRemote — pull-conflict recovery dispatch', () => {
+  const CONFLICT = new PullRebaseConflictError(
+    'main',
+    ['PR-Overviews/PR-7.html', 'other.md'],
+    'git rebase failed: could not apply 0d7b463',
+  );
+
+  function makeConflictingGit(err: unknown): GitService {
+    return {
+      pull: vi.fn().mockRejectedValue(err),
+    } as unknown as GitService;
+  }
+
+  it('queues ONE recovery row (first conflicted path, triggering user) and rethrows', async () => {
+    const pending = makePending();
+    const svc = makeFacade(
+      makeConflictingGit(CONFLICT), makeFileLocks(USER.id), pending, new WorkflowEventBus(),
+    );
+
+    await expect(svc.updateFromRemote('main', USER)).rejects.toBe(CONFLICT);
+
+    expect(pending.enqueueIfAbsent).toHaveBeenCalledTimes(1);
+    expect(pending.enqueueIfAbsent).toHaveBeenCalledWith({
+      workspaceId: 'main',
+      branch: 'main',
+      path: 'PR-Overviews/PR-7.html',
+      authorEmail: USER.email,
+      authorName: USER.name,
+    });
+    // `enqueue` (counter-resetting refresh) must NOT be used here — repeated
+    // sync attempts would starve the worker's ladder.
+    expect(pending.enqueue).not.toHaveBeenCalled();
+  });
+
+  it('falls back to the recovery-bot identity when no user is available', async () => {
+    const pending = makePending();
+    const svc = makeFacade(
+      makeConflictingGit(CONFLICT), makeFileLocks(USER.id), pending, new WorkflowEventBus(),
+    );
+
+    await expect(svc.updateFromRemote('main')).rejects.toBe(CONFLICT);
+
+    const input = (pending.enqueueIfAbsent as ReturnType<typeof vi.fn>).mock.calls[0][0];
+    expect(input.authorEmail).toContain('recovery-bot@');
+  });
+
+  it('does NOT queue recovery for a non-conflict pull failure (transient fetch error)', async () => {
+    const pending = makePending();
+    const transient = new Error('git fetch failed: could not resolve host');
+    const svc = makeFacade(
+      makeConflictingGit(transient), makeFileLocks(USER.id), pending, new WorkflowEventBus(),
+    );
+
+    await expect(svc.updateFromRemote('main', USER)).rejects.toBe(transient);
+    expect(pending.enqueueIfAbsent).not.toHaveBeenCalled();
+  });
+
+  it('a queue hiccup does not mask the conflict error', async () => {
+    const pending = makePending();
+    (pending.enqueueIfAbsent as ReturnType<typeof vi.fn>).mockRejectedValue(
+      new Error('db down'),
+    );
+    const svc = makeFacade(
+      makeConflictingGit(CONFLICT), makeFileLocks(USER.id), pending, new WorkflowEventBus(),
+    );
+
+    await expect(svc.updateFromRemote('main', USER)).rejects.toBe(CONFLICT);
+  });
+});

package/src/modules/workflow/git/__tests__/git.service.pull.test.ts

@@ -3,6 +3,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 import { GitService } from '../git.service.js';
+import { PullRebaseConflictError } from '../../workflow.errors.js';
 import { runGit, gitOut, stubWorkflowHooks, stubWorkspaceService } from './git-test-helpers.js';
 
 /** See git.service.createBranch.test.ts — same prod-mirroring layout. */
@@ -229,4 +230,77 @@ describe('GitService.pull', () => {
     const dash = await fs.readFile(path.join(repo, 'dash.html'), 'utf8');
     expect(dash).toBe('v1\n');
   });
+
+  // The production stuck-workspace state: a local commit and an origin commit
+  // both rewrote the same file, so replaying the local commit conflicts. The
+  // pull must (a) abort the rebase so the clone isn't left in a detached
+  // apply state, (b) surface a TYPED error naming the contested paths so the
+  // workflow layer can queue background recovery, and (c) leave the local
+  // commit intact (it's someone's saved content).
+  it('throws PullRebaseConflictError with the conflicted paths and aborts the rebase cleanly', async () => {
+    const { upstream, repo } = await seedWorkspace(root, workspaceId);
+
+    // Shared base version of the contested file.
+    await fs.writeFile(path.join(repo, 'PR-7.html'), 'base\n');
+    await runGit(repo, ['add', '.']);
+    await runGit(repo, ['commit', '-m', 'add overview']);
+    await runGit(repo, ['push', 'origin', 'target-company-state']);
+
+    // Origin rewrites it one way...
+    const pusher = path.join(root, '.conflict-pusher');
+    await runGit(root, ['clone', upstream, pusher]);
+    await fs.writeFile(path.join(pusher, 'PR-7.html'), 'origin version\n');
+    await runGit(pusher, ['add', '.']);
+    await runGit(pusher, ['commit', '-m', 'origin rewrite']);
+    await runGit(pusher, ['push', 'origin', 'target-company-state']);
+
+    // ...and the local branch rewrites it another way (the stranded commit).
+    await fs.writeFile(path.join(repo, 'PR-7.html'), 'local version\n');
+    await runGit(repo, ['add', '.']);
+    await runGit(repo, ['commit', '-m', 'local rewrite']);
+    const localHead = await gitOut(repo, ['rev-parse', 'HEAD']);
+
+    const svc = new GitService(
+      stubWorkspaceService({ [workspaceId]: path.join(root, workspaceId) }),
+      stubWorkflowHooks(),
+      'knowledge-base',
+    );
+
+    const err = await svc.pull(workspaceId).then(() => null).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(PullRebaseConflictError);
+    expect((err as PullRebaseConflictError).branch).toBe('target-company-state');
+    expect((err as PullRebaseConflictError).conflictedPaths).toEqual(['PR-7.html']);
+
+    // The rebase was aborted: no in-progress rebase state, clean tree, and
+    // the local commit is still HEAD with its version of the file on disk.
+    await expect(
+      fs.access(path.join(repo, '.git', 'rebase-merge')),
+    ).rejects.toMatchObject({ code: 'ENOENT' });
+    expect(await gitOut(repo, ['status', '--porcelain'])).toBe('');
+    expect(await gitOut(repo, ['rev-parse', 'HEAD'])).toBe(localHead);
+    // \r tolerated: Windows checkouts with autocrlf rewrite the file on the
+    // abort's checkout — content identity is what matters here.
+    const onDisk = await fs.readFile(path.join(repo, 'PR-7.html'), 'utf8');
+    expect(onDisk.replace(/\r/g, '')).toBe('local version\n');
+  });
+
+  // hasUnpushedCommits backs the worker's no-op arm (see runPendingCommit).
+  it('hasUnpushedCommits: false when in sync, true once a local commit lands', async () => {
+    const { repo } = await seedWorkspace(root, workspaceId);
+    const svc = new GitService(
+      stubWorkspaceService({ [workspaceId]: path.join(root, workspaceId) }),
+      stubWorkflowHooks(),
+      'knowledge-base',
+    );
+
+    await expect(svc.hasUnpushedCommits(workspaceId)).resolves.toBe(false);
+
+    await fs.writeFile(path.join(repo, 'new.txt'), 'x\n');
+    await runGit(repo, ['add', '.']);
+    await runGit(repo, ['commit', '-m', 'unpushed']);
+    await expect(svc.hasUnpushedCommits(workspaceId)).resolves.toBe(true);
+
+    await runGit(repo, ['push', 'origin', 'target-company-state']);
+    await expect(svc.hasUnpushedCommits(workspaceId)).resolves.toBe(false);
+  });
 });

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

@@ -29,6 +29,7 @@ import {
   BranchAuthorshipError,
   WorkflowValidationError,
   ProtectedBranchError,
+  PullRebaseConflictError,
 } from '../workflow.errors.js';
 
 const execFileAsync = promisify(execFile);
@@ -1387,16 +1388,65 @@ export class GitService implements IGitService {
         const remoteRef = await this.refreshRemoteBranchRef(cwd, branch);
         await this.git(cwd, ['rebase', '--autostash', remoteRef]);
       } catch (err) {
+        // Capture the contested paths BEFORE the abort wipes the rebase
+        // state — `--diff-filter=U` lists exactly the files whose replay
+        // conflicted. Best-effort: an empty list just means this wasn't a
+        // content conflict (or the probe itself failed) and the raw error
+        // is surfaced unchanged.
+        let conflictedPaths: string[] = [];
+        try {
+          const { stdout } = await this.git(cwd, ['diff', '--name-only', '--diff-filter=U']);
+          conflictedPaths = stdout.split('\n').map((s) => s.trim()).filter(Boolean);
+        } catch {
+          // fall through with an empty list
+        }
         // A failed rebase leaves the repo in a "REBASE_HEAD" / detached-apply state,
         // which makes every subsequent git command behave unexpectedly. Return the
         // working tree to a clean state before surfacing the original error.
         await this.git(cwd, ['rebase', '--abort']).catch(() => undefined);
+        if (conflictedPaths.length > 0) {
+          // Typed so the workflow layer can queue background recovery — this
+          // divergence never resolves on its own (every retry pull hits the
+          // same conflict) and the unpushed local commits are someone's saved
+          // content stuck violating save=share.
+          throw new PullRebaseConflictError(
+            branch,
+            conflictedPaths,
+            err instanceof Error ? err.message : String(err),
+          );
+        }
         throw err;
       }
       this.accessControl?.invalidate(workspaceId);
     });
   }
 
+  /**
+   * Does the checked-out branch carry commits its remote-tracking ref
+   * doesn't reach? Purely local (`rev-list` against
+   * `refs/remotes/origin/<branch>` — no network), so a stale tracking ref
+   * can only over-report: commits that were in fact already pushed make
+   * this return true, and the follow-up push is a harmless no-op. A
+   * missing tracking ref (branch never pushed) counts as unpushed — that
+   * IS unshared work.
+   *
+   * Used by the pending-commits worker's no-op arm: a clean tree does NOT
+   * mean "nothing to share" when a prior best-effort push (the autosave
+   * path) failed and left the committed change stranded locally.
+   */
+  async hasUnpushedCommits(workspaceId: string): Promise<boolean> {
+    const cwd = await this.repoDir(workspaceId);
+    const branch = await this.currentBranch(cwd);
+    try {
+      const { stdout } = await this.git(cwd, [
+        'rev-list', '--count', `refs/remotes/origin/${branch}..HEAD`,
+      ]);
+      return Number(stdout.trim()) > 0;
+    } catch {
+      return true;
+    }
+  }
+
   /**
    * Hard-reset the workspace's checked-out branch to `origin/<branch>`, fetching
    * first. This is the break-glass primitive behind roles.yaml recovery: it

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

@@ -216,6 +216,45 @@ export class PendingCommitsService {
     });
   }
 
+  /**
+   * Enqueue ONLY when no row — in ANY status — exists for
+   * `(workspaceId, branch, path)`. The pull-conflict recovery dispatch uses
+   * this instead of `enqueue` because that path can fire repeatedly (every
+   * branch focus / merge retries the pull) and `enqueue`'s refresh
+   * semantics would reset the existing row's retry counters each time —
+   * starving the worker's ladder so the recovery agent never spawns. A
+   * `needs_attention` row also blocks re-entry on purpose: the ladder
+   * already escalated that divergence to a human; spawning more agents on
+   * it would loop.
+   *
+   * Returns whether a row was inserted. Race window between the existence
+   * check and the insert is harmless — the schema allows duplicate rows and
+   * the worker's idempotent commit pass collapses them (same reasoning as
+   * `startupReconcile`'s bypass of the mutex).
+   */
+  async enqueueIfAbsent(input: EnqueueInput): Promise<boolean> {
+    const workspaceId = canonicalWorkspaceId(input.workspaceId);
+    const rows = await this.db
+      .select({ count: sql<number>`count(*)::int` })
+      .from(pendingCommits)
+      .where(
+        and(
+          eq(pendingCommits.workspaceId, workspaceId),
+          eq(pendingCommits.branch, input.branch),
+          eq(pendingCommits.path, input.path),
+        ),
+      );
+    if ((rows[0]?.count ?? 0) > 0) return false;
+    await this.db.insert(pendingCommits).values({
+      workspaceId,
+      branch: input.branch,
+      path: input.path,
+      authorEmail: input.authorEmail.trim().toLowerCase(),
+      authorName: input.authorName,
+    });
+    return true;
+  }
+
   /**
    * Atomically claim the next ready row for `workspaceId`. "Ready" means:
    *

package/src/modules/workflow/workflow.errors.ts

@@ -120,6 +120,47 @@ export class PushNeedsAgentResolutionError extends WorkflowDomainError {
   }
 }
 
+/**
+ * Refreshing a workspace from origin (`GitService.pull`) hit a rebase
+ * conflict: the workspace carries local commits origin doesn't have, origin
+ * moved ahead with changes that touch the same files, and replaying the
+ * local commits conflicts. The rebase has already been aborted — the
+ * workspace is back in its pre-pull state (diverged, clean tree).
+ *
+ * This state does NOT resolve itself: every subsequent pull hits the same
+ * conflict, and the local commits (someone's saved content, under
+ * save=share) stay unshared until the divergence is reconciled. The service
+ * layer therefore reacts by queueing a background recovery run (see
+ * `WorkflowService.updateFromRemote`); this error tells the caller what
+ * happened and which paths are contested.
+ *
+ * 409 like the other conflict errors — the operation needs the divergence
+ * cleared before it can succeed. `detail` (the raw git failure, already
+ * credential-redacted by `GitService.git`) is kept OFF the payload; it's for
+ * server logs and the recovery pipeline, not the client.
+ */
+export class PullRebaseConflictError extends WorkflowDomainError {
+  readonly kind = 'pull-rebase-conflict' as const;
+  constructor(
+    readonly branch: string,
+    readonly conflictedPaths: string[],
+    readonly detail: string,
+  ) {
+    const list = conflictedPaths.join(', ');
+    super(
+      `Updating "${branch}" from origin hit conflicts in ${conflictedPaths.length} file(s): ${list}. ` +
+        `Automatic background recovery has been queued.`,
+      409,
+      {
+        kind: 'pull-rebase-conflict',
+        branch,
+        conflictedPaths,
+      },
+    );
+    this.name = 'PullRebaseConflictError';
+  }
+}
+
 /**
  * Generic 400 for workflow-input validation (malformed branch names, missing
  * fields, etc.). Carries an optional payload so callers can attach typed

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

@@ -192,9 +192,12 @@ export function createWorkflowRoutes(
   });
 
   router.post('/workspace/:id/workflow/update-from-remote', async (req, res) => {
-    if (!(await requireUser(req, res))) return;
+    // The user is threaded through so a pull-conflict recovery row is
+    // attributed to whoever triggered the sync (see updateFromRemote).
+    const user = await requireUser(req, res);
+    if (!user) return;
     try {
-      await workflow.updateFromRemote(req.params.id);
+      await workflow.updateFromRemote(req.params.id, user);
       res.json({ status: 'updated' });
     } catch (err) {
       const { status, body } = toHttpError(err);

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

@@ -60,9 +60,11 @@ import {
   ChangeRequestConflictsError,
   DuplicateChangeRequestError,
   RolesYamlPreservationError,
+  PullRebaseConflictError,
   PushNeedsAgentResolutionError,
   WorkflowValidationError,
 } from './workflow.errors.js';
+import { RECOVERY_BOT_EMAIL, RECOVERY_BOT_NAME } from './recovery-bot.js';
 import { AccessDeniedError } from '../access/access-errors.js';
 
 const execFileAsync = promisify(execFile);
@@ -299,8 +301,64 @@ export class WorkflowService implements IWorkflowService {
     return this.git.fetch(workspaceId);
   }
 
-  updateFromRemote(workspaceId: string): Promise<void> {
-    return this.git.pull(workspaceId);
+  async updateFromRemote(workspaceId: string, user?: AuthUser): Promise<void> {
+    try {
+      await this.git.pull(workspaceId);
+    } catch (err) {
+      if (err instanceof PullRebaseConflictError) {
+        await this.queuePullConflictRecovery(workspaceId, err, user);
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * A pull hit a rebase conflict — the workspace carries local commits that
+   * conflict with origin, a state that never resolves on its own (every
+   * retry pull re-hits it, and the local commits are saved-but-unshared
+   * content violating save=share). Queue ONE pending-commits row for it so
+   * the worker's existing retry → recovery-agent → escalate ladder takes
+   * over in the background.
+   *
+   * `enqueueIfAbsent` (not `enqueue`): sync attempts can fire repeatedly
+   * (every branch focus / merge), and a fresh `enqueue` would reset the
+   * existing row's retry counters each time — starving the ladder so the
+   * recovery agent never spawns. It also refuses to resurrect a
+   * `needs_attention` row: once the ladder has escalated to a human, more
+   * agent runs on the same divergence are just a loop.
+   *
+   * One row, first conflicted path as the representative: the recovery
+   * agent's job is "bring the BRANCH into a pushable state", so one ladder
+   * per divergence — not one per conflicted file, which would multiply
+   * agent runs for a single underlying conflict.
+   *
+   * Best-effort by design — the caller is already surfacing the conflict
+   * error; a queue hiccup must not mask it.
+   */
+  private async queuePullConflictRecovery(
+    workspaceId: string,
+    err: PullRebaseConflictError,
+    user?: AuthUser,
+  ): Promise<void> {
+    try {
+      const queued = await this.pendingCommits.enqueueIfAbsent({
+        workspaceId,
+        branch: err.branch,
+        path: err.conflictedPaths[0],
+        authorEmail: user?.email ?? RECOVERY_BOT_EMAIL,
+        authorName: user?.name ?? RECOVERY_BOT_NAME,
+      });
+      if (queued) {
+        console.warn(
+          `[workflow] pull conflict on ws=${workspaceId} branch=${err.branch} (${err.conflictedPaths.join(', ')}) — queued background recovery`,
+        );
+      }
+    } catch (queueErr) {
+      console.error(
+        `[workflow] failed to queue pull-conflict recovery for ws=${workspaceId}:`,
+        queueErr instanceof Error ? queueErr.message : queueErr,
+      );
+    }
   }
 
   resetToRemote(workspaceId: string, branch: string): Promise<void> {
@@ -680,9 +738,21 @@ export class WorkflowService implements IWorkflowService {
   ): Promise<void> {
     const change = await this.git.commitFile(workspaceId, user, targetPath);
     if (!change) {
-      // No-op commit (path was already clean — typical for a double-enqueue
-      // or a save of bytes identical to HEAD). Nothing to push; nothing to
-      // emit. The worker treats this as success and drops the row.
+      // No-op commit — the path was already clean. Usually a double-enqueue
+      // or a save of bytes identical to HEAD, BUT a clean tree does NOT
+      // prove there's nothing to share: the autosave path
+      // (`commitFileWhileLocked`) commits locally with a best-effort push,
+      // and when that push fails the commit stays stranded on the local
+      // branch with the tree clean. Treating that as success dropped the
+      // row without ever starting the retry → recovery-agent ladder —
+      // which is exactly how a diverged workspace ends up stuck forever.
+      // So: if the branch is ahead of its remote-tracking ref, push (with
+      // the same cooperative recovery, so a conflicting divergence throws
+      // and the worker's ladder takes over). Nothing to emit either way —
+      // there's no new sha.
+      if (await this.git.hasUnpushedCommits(workspaceId)) {
+        await this.pushWithRecovery(workspaceId, branch, targetPath, user);
+      }
       return;
     }
     await this.pushWithRecovery(workspaceId, branch, targetPath, user);
@@ -1352,6 +1422,14 @@ export class WorkflowService implements IWorkflowService {
       const targetWorkspace = await this.workspaceService.getOrCreateForBranch(baseBranch);
       await this.git.pull(targetWorkspace.id);
     } catch (err) {
+      // Still best-effort for the merge response (the merge already landed
+      // on origin) — but a rebase CONFLICT here means the target workspace
+      // is stranded (local commits vs origin, never self-heals), so queue
+      // the background recovery ladder before shrugging.
+      if (err instanceof PullRebaseConflictError) {
+        const targetWorkspaceId = encodeURIComponent(baseBranch);
+        await this.queuePullConflictRecovery(targetWorkspaceId, err, user);
+      }
       console.warn(
         `[merge] post-merge pull of target "${baseBranch}" failed — its workspace may be momentarily behind origin`,
         err,