@1agh/maude 0.53.1 → 0.54.0

package/apps/studio/git/repo-lock.ts

@@ -0,0 +1,305 @@
+// One writer at a time on the workspace checkout — Cloud Phase 27 D2.
+//
+// THE PROBLEM THIS EXISTS FOR. A cell is two processes over one working tree.
+// The hub commits autosaves, bundles backups and (at boot) clones the checkout;
+// the studio writes canvas source and runs the browser's own git verbs —
+// commit, discard, branch, checkout, fold, pull. Neither could see the other,
+// and the phase's preserved dissent says exactly what that costs: "the 3 a.m.
+// event is not a 500 — it is a tenant's canvas lost to a half-staged commit or
+// a checkout under a live writer, in a cell whose /health still says 200."
+//
+// WHY GIT'S OWN LOCK WAS NOT ENOUGH, AND WHAT HAD TO CHANGE FIRST. `index.lock`
+// only serializes processes that take it, and the studio did not: it runs
+// isomorphic-git for the write paths, which keeps an in-PROCESS async lock and
+// writes `.git/index` directly. Two engines, one index, no shared lock — so the
+// first half of D2 is `MAUDE_USE_SYSTEM_GIT=1` in a cell (studio-child.mjs), and
+// this file is the second half.
+//
+// WHY A SECOND LOCK ON TOP OF `index.lock`. Two reasons, and both matter:
+//
+//   1. `index.lock` FAILS rather than waits. Two commits racing gives one of
+//      them "Unable to create '.git/index.lock': File exists" — loud, but a
+//      failed autosave commit is a history that quietly stops. Here the loser
+//      WAITS, which is what an autosave wants.
+//   2. `index.lock` is held per git INVOCATION, and the dangerous unit is a
+//      SEQUENCE: `add` then `commit` is two invocations, and a `checkout`
+//      landing between them is precisely the half-staged commit. A lock the
+//      caller holds across the whole sequence is the only thing that closes it.
+//
+// WHAT IT DELIBERATELY DOES NOT COVER. Ordinary file writes are not locked.
+// They are atomic per file (tmp + rename everywhere in this codebase), so a
+// `git add` racing a canvas write stages the old bytes or the new ones, never
+// half of either, and the next quiescence commits the rest. Locking every
+// keystroke-debounced write against a 3-second commit cycle would buy nothing
+// and cost the editor its latency. What is locked is the operations that
+// REWRITE the tree or the index — those are the ones that lose work.
+//
+// The hub's tree-rewriting operations (`seedRepo`, `restoreRepo`, rehydrate)
+// are all cold-start, before the studio is serving — verified, not assumed:
+// `restoreLatest` is called only from `rehydrate.mjs`, which the cell entrypoint
+// runs as its own process before the hub starts, and `seedRepo` runs once in
+// `startWorkspaceAgent` against an empty directory. That is why this is a lock
+// and not a lock plus a quiesce RPC: there is no live hub operation for the
+// studio to be quiesced FOR. If one is ever added, it needs the RPC too, and
+// this comment is where to notice that.
+
+import {
+  closeSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  utimesSync,
+  writeSync,
+} from 'node:fs';
+import path from 'node:path';
+
+/** Where the lock lives. Inside `.git/` because it is git state, and beside
+ *  `index.lock` because that is where anyone debugging a stuck repo looks. It
+ *  is NOT named `index.lock` — faking git's own lock would make git itself
+ *  refuse to run, which is a cure considerably worse than the disease. */
+export const REPO_LOCK_FILE = 'maude-repo.lock';
+
+/** Past this, a holder is assumed dead. Deliberately shorter than the 60 s
+ *  `/health` staleness window: that one answers "should a human worry", this one
+ *  answers "may I proceed", and waiting a minute to autosave is its own failure.
+ *  Every operation under this lock is seconds at most; a clone is not (it runs
+ *  before anything else exists to contend with it). */
+export const STALE_LOCK_MS = 30_000;
+
+/** How long a caller waits before giving up. Long enough to outlast any commit
+ *  or checkout, short enough that a wedged holder surfaces as an error rather
+ *  than a hang. */
+export const DEFAULT_WAIT_MS = 15_000;
+
+/** How often a holder refreshes its lock's mtime. Comfortably inside
+ *  STALE_LOCK_MS, so a live holder is never mistaken for a dead one. */
+export const HEARTBEAT_MS = 5_000;
+
+export interface RepoLockOptions {
+  /** Milliseconds to wait for the lock before throwing. */
+  waitMs?: number;
+  /** Test seam. */
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  log?: Pick<Console, 'warn' | 'log'>;
+}
+
+export interface LockHolder {
+  pid: number;
+  /** Who and what — `hub:autocommit`, `studio:checkout`. Read by a human. */
+  holder: string;
+  at: number;
+  /** Distinguishes OUR lock from one a stale-steal handed to somebody else. */
+  token: string;
+}
+
+function lockPathFor(repoRoot: string): string {
+  return path.join(repoRoot, '.git', REPO_LOCK_FILE);
+}
+
+function readHolder(file: string): LockHolder | null {
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    return typeof parsed?.pid === 'number' ? (parsed as LockHolder) : null;
+  } catch {
+    // Unreadable or half-written: treat as an unknown holder rather than as
+    // absent. Staleness still reaps it; guessing "nobody" would not.
+    return null;
+  }
+}
+
+/**
+ * Is the process that wrote this lock still alive?
+ *
+ * Both contenders live in the same container (and on a desktop, the same
+ * machine), so signal 0 is a real answer rather than a guess. An unknown pid is
+ * treated as ALIVE — an unreadable lock file must not become a licence to
+ * steal; that is what the staleness window is for.
+ */
+function holderAlive(holder: LockHolder | null): boolean {
+  if (!holder) return true;
+  try {
+    process.kill(holder.pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM means it exists and belongs to another user — alive.
+    return (err as NodeJS.ErrnoException)?.code === 'EPERM';
+  }
+}
+
+/**
+ * Take the lock, run `fn`, release it — even when `fn` throws.
+ *
+ * A repo with no `.git` yet runs UNLOCKED, on purpose: there is nothing to
+ * serialize before the checkout exists, and the only code that runs then is the
+ * boot-time seed, single-process by construction. Creating `.git` here to hold
+ * a lock would make this function a repo initializer, which is the last thing
+ * it should be.
+ */
+export async function withRepoLock<T>(
+  repoRoot: string,
+  holder: string,
+  fn: () => Promise<T>,
+  opts: RepoLockOptions = {}
+): Promise<T> {
+  const {
+    waitMs = DEFAULT_WAIT_MS,
+    now = () => Date.now(),
+    sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms)),
+    log = console,
+  } = opts;
+
+  const gitDir = path.join(repoRoot, '.git');
+  try {
+    if (!statSync(gitDir).isDirectory()) return await fn();
+  } catch {
+    return await fn(); // no repo yet — see above
+  }
+
+  const file = lockPathFor(repoRoot);
+  const token = `${process.pid}-${now()}-${Math.random().toString(36).slice(2, 10)}`;
+  const deadline = now() + waitMs;
+  let delay = 20;
+
+  for (;;) {
+    if (tryAcquire(file, holder, token, now)) break;
+
+    const current = readHolder(file);
+    const age = ageOf(file, now);
+    // Steal only from a holder that is demonstrably gone, or one that has held
+    // it past every plausible operation. A cell that crashed mid-commit must
+    // not need a human to unwedge it.
+    if (age !== null && (age > STALE_LOCK_MS || !holderAlive(current))) {
+      // STEAL BY RENAME, NOT BY UNLINK — the steal has to be a
+      // compare-and-swap or it is a second way to lose mutual exclusion.
+      //
+      // An unconditional `unlink` here loses it outright: two waiters both see
+      // A as stale, the first unlinks and acquires, and the second — still
+      // acting on its read of A — unlinks the FIRST's fresh lock and acquires
+      // too. Both then run their critical section over one git index, which is
+      // precisely the half-staged commit this lock exists to prevent,
+      // reintroduced by its own recovery path.
+      //
+      // `rename` is the fix because it FAILS when the source is already gone:
+      // exactly one waiter can move the stale file aside, and every other gets
+      // ENOENT and goes back around the loop. Comparing the holder's token
+      // before an unlink was tried first and rejected — it narrows the window
+      // rather than closing it, and no honest test could tell it apart from the
+      // unfixed version, which is how the weakness came to light.
+      const sidecar = `${file}.stale-${token}`;
+      try {
+        renameSync(file, sidecar);
+      } catch {
+        continue; // another waiter won the steal; re-read and try again
+      }
+      log.warn?.(
+        `[repo-lock] stole a ${Math.round(age / 1000)}s lock from ${safeLabel(current?.holder)}` +
+          `${holderAlive(current) ? '' : ' (process gone)'}`
+      );
+      try {
+        unlinkSync(sidecar);
+      } catch {
+        /* already gone — the lock path is free either way */
+      }
+      continue;
+    }
+
+    if (now() >= deadline) {
+      throw new Error(
+        `repo lock held by ${current?.holder ?? 'an unreadable holder'} (pid ${current?.pid ?? '?'}) ` +
+          `for ${age === null ? '?' : Math.round(age / 1000)}s — ${holder} gave up after ${Math.round(waitMs / 1000)}s`
+      );
+    }
+    await sleep(delay);
+    delay = Math.min(delay * 2, 250);
+  }
+
+  // KEEP THE LOCK LOOKING ALIVE WHILE IT IS.
+  //
+  // The staleness test is the file's mtime, stamped once at acquisition, so
+  // "held for 30 s" and "the holder died 30 s ago" were the same observation.
+  // That was defensible when everything under this lock was a local `commit`;
+  // D2 put `pull`, `fold` and `resolve` under it too, and those do NETWORK I/O
+  // on a container's cold connection. Without this, the next waiter steals the
+  // lock out from under a running merge.
+  const beat = setInterval(() => {
+    try {
+      const held = readHolder(file);
+      if (held?.token !== token) return; // not ours any more — nothing to refresh
+      const stamp = new Date();
+      utimesSync(file, stamp, stamp);
+    } catch {
+      /* the file is gone or unreadable; the release below is still correct */
+    }
+  }, HEARTBEAT_MS);
+  beat.unref?.();
+
+  try {
+    return await fn();
+  } finally {
+    clearInterval(beat);
+    release(file, token);
+  }
+}
+
+/** Bound a holder label before it reaches a log line. `readHolder` parses
+ *  attacker-plantable JSON, and an unescaped newline in a log is a forged log
+ *  entry. */
+function safeLabel(holder: string | undefined): string {
+  if (!holder) return 'an unreadable holder';
+  const clean = holder.replace(/[^\w:.-]/g, '').slice(0, 64);
+  return clean || 'an unreadable holder';
+}
+
+/** `wx` is the whole mechanism: create-or-fail is atomic on every filesystem
+ *  this runs on, which is what makes this a lock rather than a suggestion. */
+function tryAcquire(file: string, holder: string, token: string, now: () => number): boolean {
+  let fd: number | null = null;
+  try {
+    mkdirSync(path.dirname(file), { recursive: true });
+    fd = openSync(file, 'wx');
+    writeSync(
+      fd,
+      JSON.stringify({ pid: process.pid, holder, at: now(), token } satisfies LockHolder)
+    );
+    return true;
+  } catch {
+    return false;
+  } finally {
+    if (fd !== null) {
+      try {
+        closeSync(fd);
+      } catch {
+        /* nothing useful to do */
+      }
+    }
+  }
+}
+
+function ageOf(file: string, now: () => number): number | null {
+  try {
+    return Math.max(0, now() - statSync(file).mtimeMs);
+  } catch {
+    return null; // vanished between attempts — not stale, just gone
+  }
+}
+
+/**
+ * Release, but only OUR lock.
+ *
+ * If a stale-steal already handed it to somebody else, unlinking here would
+ * pull the lock out from under a live holder — the one way a lock can be worse
+ * than no lock at all.
+ */
+function release(file: string, token: string): void {
+  const current = readHolder(file);
+  if (current && current.token !== token) return;
+  try {
+    unlinkSync(file);
+  } catch {
+    /* already gone */
+  }
+}

package/apps/studio/git/service.ts

@@ -31,7 +31,16 @@ import { isAbsolute, join, relative, sep } from 'node:path';
 import git from 'isomorphic-git';
 import http from 'isomorphic-git/http/node';
 
-const USE_SYSTEM_GIT = /^(1|true|on|yes)$/i.test(process.env.MAUDE_USE_SYSTEM_GIT ?? '');
+import { withRepoLock } from './repo-lock.ts';
+
+// Read LIVE, not as a module-load const — the same reason `noSystemGit()` below
+// is a function, and a sharper one since Cloud Phase 27 D2: a CELL now runs with
+// this forced on (studio-child.mjs), so the system-git write paths stopped being
+// an opt-in escape hatch and became what every cloud tenant's saves go through.
+// A module-load const cannot be scoped around a test, which is how those paths
+// came to have no coverage at all while the iso ones had plenty.
+const systemGitForced = (): boolean =>
+  /^(1|true|on|yes)$/i.test(process.env.MAUDE_USE_SYSTEM_GIT ?? '');
 // DDR-133 (DDR-107 end-state): auto-prefer a detected system `git` for the NETWORK
 // paths (gitFetchRemote / remoteAheadBehind — native fetch is instant + uses the
 // user's own credential helper / SSH agent) AND the READ paths (status / list-
@@ -54,7 +63,7 @@ let systemGitProbe: Promise<boolean> | undefined;
  *  and cheap. The probe NEVER relaxes the DDR-131 transport gate: callers classify
  *  the remote URL first; this only picks which engine runs an already-vetted op. */
 function systemGitAvailable(): Promise<boolean> {
-  if (USE_SYSTEM_GIT) return Promise.resolve(true);
+  if (systemGitForced()) return Promise.resolve(true);
   if (noSystemGit()) return Promise.resolve(false);
   if (!systemGitProbe) {
     systemGitProbe = runGit(process.cwd(), ['--version'], undefined, 4000)
@@ -64,6 +73,33 @@ function systemGitAvailable(): Promise<boolean> {
   return systemGitProbe;
 }
 
+// ── one writer at a time (Cloud Phase 27 D2) ─────────────────────────────────
+//
+// In a CELL this process shares the checkout with the hub, which commits
+// autosaves on its own clock. Every verb below either rewrites the working tree
+// or the index, so each one runs under the cross-process advisory lock — held
+// for the WHOLE verb, not per git invocation, because the dangerous unit is a
+// sequence (`checkout main` → `merge` → `branch -D` in a fold, `add` → `commit`
+// in the autocommit). On a desktop the lock is uncontended and costs a file
+// create.
+//
+// A verb that cannot get the lock REFUSES in its own shape rather than throwing:
+// these results reach a panel, and "somebody else is saving" is a sentence a
+// designer can act on, where a 500 is not.
+const REPO_BUSY = 'Somebody else is saving this project right now — try again in a moment.';
+
+function underRepoLock<T>(
+  dir: string,
+  op: string,
+  fn: () => Promise<T>,
+  busy: () => T
+): Promise<T> {
+  return withRepoLock(dir, `studio:${op}`, fn).catch((err) => {
+    console.warn(`[git] ${op} could not take the repo lock: ${(err as Error).message}`);
+    return busy();
+  });
+}
+
 const TIMED_OUT = Symbol('maude-git-timeout');
 /** Race `p` against a timeout. Returns `TIMED_OUT` if the deadline wins; a late
  *  rejection from the losing promise is swallowed so it never surfaces as an
@@ -207,9 +243,16 @@ function underPrefix(filepath: string, prefix: string): boolean {
  *      transport) → NOT hidden here.
  *    - `_comments/`        → hub-sync-only (DDR-102 CRDT) → HIDDEN, so it never
  *      double-transports through git. */
-function isMaudeRuntimeState(p: string): boolean {
+/** Exported for the test that guards the D3 per-member sibling: three separate
+ *  lists have to agree on what runtime state IS, and they silently did not. */
+export function isMaudeRuntimeState(p: string): boolean {
   return (
-    /(^|\/)_(?:server|active|sync|preflight|locator|export-history|generate-history)\.json$/.test(
+    // The optional `.<session>` segment is Cloud Phase 27 D3: `_active.json`
+    // becomes `_active.<sessionKey>.json` per member in a cell. Without it each
+    // member's open tabs and selection showed as untracked to EVERYONE, a
+    // "Save all" staged them, and a push published them — one person's place in
+    // the project, in the tenant's remote.
+    /(^|\/)_(?:server|active|sync|preflight|locator|export-history|generate-history)(?:\.[A-Za-z0-9_-]{1,64})?\.json$/.test(
       p
     ) ||
     /(^|\/)_server\.(?:lock|log)$/.test(p) ||
@@ -402,7 +445,24 @@ function classifyPorcelain(xy: string): GitFileState | null {
  *  checked; an empty/undefined list means "Save all" (every changed file under
  *  `designPrefix`). Each file is staged add-or-remove based on its workdir
  *  presence, then one commit lands. Returns the new sha. */
-export async function gitCommit(
+export function gitCommit(
+  dir: string,
+  message: string,
+  files?: string[],
+  opts: { designPrefix?: string } = {}
+): Promise<GitCommitResult> {
+  return underRepoLock(
+    dir,
+    'commit',
+    () => commitLocked(dir, message, files, opts),
+    () => ({
+      ok: false,
+      error: REPO_BUSY,
+    })
+  );
+}
+
+async function commitLocked(
   dir: string,
   message: string,
   files?: string[],
@@ -426,7 +486,7 @@ export async function gitCommit(
     selected = status.files;
   }
 
-  return USE_SYSTEM_GIT ? commitSystem(dir, msg, selected) : commitIso(dir, msg, selected);
+  return systemGitForced() ? commitSystem(dir, msg, selected) : commitIso(dir, msg, selected);
 }
 
 async function commitIso(
@@ -479,7 +539,23 @@ export interface GitDiscardResult {
  *  A tracked file (modified/deleted) is restored from HEAD; an untracked file is
  *  deleted (it has no HEAD version to restore). Destructive by intent; the UI
  *  confirms first. Each path is the endpoint-validated repo-relative form. */
-export async function gitDiscard(
+export function gitDiscard(
+  dir: string,
+  files: string[],
+  opts: { designPrefix?: string } = {}
+): Promise<GitDiscardResult> {
+  return underRepoLock(
+    dir,
+    'discard',
+    () => discardLocked(dir, files, opts),
+    () => ({
+      ok: false,
+      error: REPO_BUSY,
+    })
+  );
+}
+
+async function discardLocked(
   dir: string,
   files: string[],
   opts: { designPrefix?: string } = {}
@@ -496,7 +572,7 @@ export async function gitDiscard(
     for (const f of targets) {
       if (byPath.get(f) === 'untracked') {
         await fs.promises.rm(join(dir, f), { force: true });
-      } else if (USE_SYSTEM_GIT) {
+      } else if (systemGitForced()) {
         const r = await runGit(dir, ['checkout', 'HEAD', '--', f]);
         if (r.code !== 0) return { ok: false, error: r.stderr.trim() || 'discard failed' };
       } else {
@@ -731,7 +807,19 @@ export interface GitBranchResult {
 
 /** Create a new draft off HEAD and switch to it. The name is validated against the
  *  same dash-led / charset guard as every other positional (defense-in-depth). */
-export async function gitCreateBranch(dir: string, name: string): Promise<GitBranchResult> {
+export function gitCreateBranch(dir: string, name: string): Promise<GitBranchResult> {
+  return underRepoLock(
+    dir,
+    'branch',
+    () => createBranchLocked(dir, name),
+    () => ({
+      ok: false,
+      error: REPO_BUSY,
+    })
+  );
+}
+
+async function createBranchLocked(dir: string, name: string): Promise<GitBranchResult> {
   if (!isRepo(dir)) return { ok: false, error: 'This project is not versioned yet.' };
   if (!isSafeGitPositional(name))
     return { ok: false, error: "That draft name has characters we can't use." };
@@ -739,7 +827,7 @@ export async function gitCreateBranch(dir: string, name: string): Promise<GitBra
     const existing = await gitListBranches(dir);
     if (existing.some((b) => b.name === name))
       return { ok: false, error: 'A draft with that name already exists.' };
-    if (USE_SYSTEM_GIT) {
+    if (systemGitForced()) {
       const r = await runGit(dir, ['checkout', '-b', name]);
       if (r.code !== 0)
         return { ok: false, error: r.stderr.trim() || 'Could not create the draft.' };
@@ -755,11 +843,23 @@ export async function gitCreateBranch(dir: string, name: string): Promise<GitBra
 /** Switch to an existing draft (or back to the Shared version). A dirty tree that
  *  would be clobbered surfaces a plain "Save your changes first" rather than a
  *  raw git error. */
-export async function gitCheckout(dir: string, name: string): Promise<GitBranchResult> {
+export function gitCheckout(dir: string, name: string): Promise<GitBranchResult> {
+  return underRepoLock(
+    dir,
+    'checkout',
+    () => checkoutLocked(dir, name),
+    () => ({
+      ok: false,
+      error: REPO_BUSY,
+    })
+  );
+}
+
+async function checkoutLocked(dir: string, name: string): Promise<GitBranchResult> {
   if (!isRepo(dir)) return { ok: false, error: 'This project is not versioned yet.' };
   if (!isSafeGitPositional(name)) return { ok: false, error: 'Invalid draft name.' };
   try {
-    if (USE_SYSTEM_GIT) {
+    if (systemGitForced()) {
       // System git DWIMs `git checkout <name>` into a tracking branch when <name>
       // exists on exactly one remote, so the local + remote-only cases share a path.
       const r = await runGit(dir, ['checkout', name]);
@@ -826,7 +926,24 @@ export interface GitFoldResult {
  *  the draft. A content conflict or a rejected publish surfaces the plain "Get latest
  *  first" path (no 3-way merge UI). The local draft is removed ONLY after a clean
  *  publish, so a rejected publish leaves a recoverable state. */
-export async function gitFoldDraft(
+export function gitFoldDraft(
+  dir: string,
+  draftName: string,
+  token: string | undefined,
+  opts: { remote?: string } = {}
+): Promise<GitFoldResult> {
+  return underRepoLock(
+    dir,
+    'fold',
+    () => foldLocked(dir, draftName, token, opts),
+    () => ({
+      ok: false,
+      error: REPO_BUSY,
+    })
+  );
+}
+
+async function foldLocked(
   dir: string,
   draftName: string,
   token: string | undefined,
@@ -868,7 +985,7 @@ export async function gitFoldDraft(
   // locally; there's no PR host. Unchanged pre-PR-flow behavior.
   // Merge the draft into the Shared version (FF when possible, else a merge commit).
   try {
-    if (USE_SYSTEM_GIT) {
+    if (systemGitForced()) {
       const co = await runGit(dir, ['checkout', shared]);
       if (co.code !== 0) return { ok: false, error: 'Save your changes before adding the draft.' };
       const mg = await runGit(dir, ['merge', draftName]);
@@ -896,7 +1013,7 @@ export async function gitFoldDraft(
       await git.checkout({ fs, dir, ref: shared, force: true });
     }
   } catch (e) {
-    if (!USE_SYSTEM_GIT) {
+    if (!systemGitForced()) {
       try {
         await git.checkout({ fs, dir, ref: draftName, force: true });
       } catch {
@@ -928,7 +1045,7 @@ export async function gitFoldDraft(
 
   // The draft's work is now in the Shared version — remove the draft (local only).
   try {
-    if (USE_SYSTEM_GIT) await runGit(dir, ['branch', '-D', draftName]);
+    if (systemGitForced()) await runGit(dir, ['branch', '-D', draftName]);
     else await git.deleteBranch({ fs, dir, ref: draftName });
   } catch {
     /* non-fatal: the fold + publish succeeded; a leftover draft ref is harmless */
@@ -1011,7 +1128,7 @@ export async function gitPush(
     case 'iso':
       return pushIso(dir, token, remote, opts.ref);
     case 'legacy':
-      return USE_SYSTEM_GIT
+      return systemGitForced()
         ? pushSystem(dir, token, remote, opts.ref)
         : pushIso(dir, token, remote, opts.ref);
   }
@@ -1141,7 +1258,23 @@ function isTransportError(blob: string): boolean {
 // ── pull (Get latest) ─────────────────────────────────────────────────────
 
 /** Get latest. Same optional-token model as gitPush (see its doc comment). */
-export async function gitPull(
+export function gitPull(
+  dir: string,
+  token: string | undefined,
+  opts: { remote?: string; ref?: string } = {}
+): Promise<GitPullResult> {
+  return underRepoLock(
+    dir,
+    'pull',
+    () => pullLocked(dir, token, opts),
+    () => ({
+      ok: false,
+      error: REPO_BUSY,
+    })
+  );
+}
+
+async function pullLocked(
   dir: string,
   token: string | undefined,
   opts: { remote?: string; ref?: string } = {}
@@ -1160,7 +1293,7 @@ export async function gitPull(
     case 'iso':
       return pullIso(dir, token, remote, opts.ref);
     case 'legacy':
-      return USE_SYSTEM_GIT
+      return systemGitForced()
         ? pullSystem(dir, token, remote, opts.ref)
         : pullIso(dir, token, remote, opts.ref);
   }
@@ -1351,7 +1484,24 @@ export async function gitFetchRemote(
  *   • `both`   — take theirs AND save ours as a "<name> (mine)<ext>" copy (the
  *                DiffView zero-data-loss default).
  *  Produces the two-parent merge commit so a subsequent Publish fast-forwards. */
-export async function gitResolve(
+export function gitResolve(
+  dir: string,
+  choice: ResolveChoice,
+  token: string | undefined,
+  opts: { remote?: string; ref?: string } = {}
+): Promise<GitResolveResult> {
+  return underRepoLock(
+    dir,
+    'resolve',
+    () => resolveLocked(dir, choice, token, opts),
+    () => ({
+      ok: false,
+      error: REPO_BUSY,
+    })
+  );
+}
+
+async function resolveLocked(
   dir: string,
   choice: ResolveChoice,
   token: string | undefined,
@@ -1360,7 +1510,7 @@ export async function gitResolve(
   if (!isRepo(dir)) return { ok: false, error: 'This project is not versioned yet.' };
   if (choice !== 'mine' && choice !== 'theirs' && choice !== 'both')
     return { ok: false, error: 'Pick how to resolve: keep mine, theirs, or both.' };
-  return USE_SYSTEM_GIT
+  return systemGitForced()
     ? resolveSystem(dir, choice, opts.remote || 'origin', opts.ref)
     : resolveIso(dir, choice, token, opts.remote || 'origin', opts.ref);
 }