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

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,76 @@ 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);
+        let abortSucceeded = true;
+        await this.git(cwd, ['rebase', '--abort']).catch(() => {
+          abortSucceeded = false;
+        });
+        if (abortSucceeded && 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.
+          //
+          // Gated on the abort succeeding: a failed abort means either no
+          // rebase was ever active (the unmerged paths pre-date this pull —
+          // some earlier operation left the index broken) or the clone is in
+          // a state git itself can't unwind. Queueing recovery there would
+          // point the worker's commitFile at a repo mid-conflict, risking a
+          // commit full of conflict markers — surface the raw error instead
+          // and leave diagnosis to a human.
+          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,67 @@ 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, smallest 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. Sorted so the choice is
+   * stable across retries regardless of how the caller ordered the paths —
+   * a shifting representative would slip past `enqueueIfAbsent`'s
+   * per-(workspace, branch, path) dedup and start a second ladder.
+   *
+   * 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].sort()[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 +741,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);
@@ -1348,10 +1421,21 @@ export class WorkflowService implements IWorkflowService {
     // this a read right after a merge misses the just-merged change. Best-effort:
     // the merge already succeeded on origin, so a pull hiccup must not fail the
     // response (a later fetch/pull reconciles).
+    let targetWorkspaceId: string | undefined;
     try {
       const targetWorkspace = await this.workspaceService.getOrCreateForBranch(baseBranch);
+      targetWorkspaceId = targetWorkspace.id;
       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. A conflict can
+      // only have come from the pull, so the workspace id is always set on
+      // this arm — the guard just satisfies the narrowing.
+      if (err instanceof PullRebaseConflictError && targetWorkspaceId) {
+        await this.queuePullConflictRecovery(targetWorkspaceId, err, user);
+      }
       console.warn(
         `[merge] post-merge pull of target "${baseBranch}" failed — its workspace may be momentarily behind origin`,
         err,