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

package/src/modules/kb-fs/__tests__/move-with-edits.test.ts

@@ -0,0 +1,304 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+import { GitService } from '../../workflow/git/git.service.js';
+import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import { LockingFilesystem, MoveLockedError, MoveRacedError, MoveUndoError } from '../locking-filesystem.js';
+import { PushNeedsAgentResolutionError } from '../../../shared/domain-errors.js';
+
+/**
+ * `LockingFilesystem.moveWithEdits` — `move_file` with link rewriting: the
+ * move and every link edit in ONE commit, which git reads as a rename; and,
+ * when any lock is out of reach, nothing changed at all. Committed through the
+ * real `GitService.commitChanges` on a real repository.
+ */
+
+const exec = promisify(execFile);
+const KB = 'knowledge-base';
+const WS = 'ws-move';
+const USER: AuthUser = { id: 'u-alice', name: 'Alice', email: 'alice@bevel.software' };
+
+async function git(cwd: string, args: string[]): Promise<string> {
+  const { stdout } = await exec('git', args, {
+    cwd,
+    env: { ...process.env, GIT_AUTHOR_NAME: 'T', GIT_AUTHOR_EMAIL: 't@x.com', GIT_COMMITTER_NAME: 'T', GIT_COMMITTER_EMAIL: 't@x.com' },
+  });
+  return stdout;
+}
+
+let root: string;
+let repo: string;
+let workflow: IWorkflowService;
+let lockedPaths: Set<string>;
+
+async function put(rel: string, content: string | Buffer): Promise<void> {
+  await fs.mkdir(path.dirname(path.join(repo, rel)), { recursive: true });
+  await fs.writeFile(path.join(repo, rel), content);
+}
+
+const read = (rel: string) => fs.readFile(path.join(repo, rel), 'utf8');
+
+beforeEach(async () => {
+  root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-move-edits-'));
+  repo = path.join(root, KB);
+  await fs.mkdir(repo, { recursive: true });
+  await git(repo, ['init', '-b', 'feature-test']);
+  await git(repo, ['config', 'user.email', 'test@bevel.local']);
+  await git(repo, ['config', 'user.name', 'Test Runner']);
+  await put('Projects/A/One.md', '---\nnodeType: "[Task](../../NodeTypes/Task.md)"\nid: one\n---\n\n# One\nSee [two](Two.md).\n' + 'body line\n'.repeat(20));
+  await put('Projects/A/Two.md', '# Two\n' + 'two line\n'.repeat(20));
+  await put('Projects/A/pic.png', Buffer.from([0x89, 0x50, 0x4e, 0x47, 0, 1, 2, 3]));
+  await put('Index.md', '[one](Projects/A/One.md)\n');
+  await put('NodeTypes/Task.md', '# Task\n');
+  await git(repo, ['add', '-A']);
+  await git(repo, ['commit', '-m', 'seed']);
+
+  const svc = new GitService(
+    { getWorkspacePath: async () => root } as unknown as WorkspaceService,
+    (() => {
+      const hooks = new WorkflowHooks();
+      hooks.onCommitValidation(vi.fn(async () => ({ ok: true, mustFix: [], warnings: [], rawOutput: '' })));
+      return hooks;
+    })(),
+    testKbContext({ kbDirName: KB }),
+  );
+  lockedPaths = new Set();
+  workflow = {
+    acquireLock: vi.fn(async (_w: string, _b: string, p: string) =>
+      lockedPaths.has(p)
+        ? { acquired: false, lock: { holderName: 'Bob' } }
+        : { acquired: true, lock: { holderName: 'Alice' } }),
+    releaseLock: vi.fn(async () => null),
+    releaseLockNoCommit: vi.fn(async () => undefined),
+    releaseLockUntouched: vi.fn(async () => undefined),
+    commitChanges: vi.fn((w: string, u: AuthUser, s: string, paths?: string[]) => svc.commitChanges(w, u, s, paths)),
+  } as unknown as IWorkflowService;
+});
+
+afterEach(async () => {
+  await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+});
+
+const fsLayer = (validateWrite?: (p: string, content: unknown) => Promise<void>) =>
+  new LockingFilesystem(
+    { basePath: root, contained: true },
+    { workflow, workspaceId: WS, branch: 'feature-test', user: USER, kbDirName: KB, ...(validateWrite ? { validateWrite } : {}) },
+  );
+
+/** The paths each release kind was called with. */
+const released = (fn: unknown) => (fn as ReturnType<typeof vi.fn>).mock.calls.map((c) => c[2] as string).sort();
+
+const edits = () => [
+  {
+    path: `${KB}/Topics/Deep/A/One.md`,
+    lockAt: `${KB}/Projects/A/One.md`,
+    content: '---\nnodeType: "[Task](../../../NodeTypes/Task.md)"\nid: one\n---\n\n# One\nSee [two](Two.md).\n' + 'body line\n'.repeat(20),
+  },
+  { path: `${KB}/Index.md`, lockAt: `${KB}/Index.md`, content: '[one](Topics/Deep/A/One.md)\n' },
+];
+
+describe('LockingFilesystem.moveWithEdits', () => {
+  it('lands the folder move and every edit as ONE commit that git reads as renames', async () => {
+    const before = (await git(repo, ['rev-list', '--count', 'HEAD'])).trim();
+    await fsLayer().moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A');
+
+    expect((await git(repo, ['rev-list', '--count', 'HEAD'])).trim()).toBe(String(Number(before) + 1));
+    expect((await git(repo, ['status', '--porcelain'])).trim()).toBe('');
+    const stat = (await git(repo, ['show', '-M', '--name-status', '--format=%s', 'HEAD'])).trim().split('\n');
+    expect(stat[0]).toBe('Move A');
+    const rows = stat.slice(1).filter(Boolean).map((l) => l.split('\t'));
+    expect(rows.map((r) => [r[0].replace(/\d+$/, ''), ...r.slice(1)]).sort()).toEqual([
+      ['M', 'Index.md'],
+      ['R', 'Projects/A/One.md', 'Topics/Deep/A/One.md'],
+      ['R', 'Projects/A/Two.md', 'Topics/Deep/A/Two.md'],
+      ['R', 'Projects/A/pic.png', 'Topics/Deep/A/pic.png'],
+    ]);
+    expect(await read('Index.md')).toBe('[one](Topics/Deep/A/One.md)\n');
+    expect(await read('Topics/Deep/A/One.md')).toContain('../../../NodeTypes/Task.md');
+    // The binary moved byte for byte.
+    expect([...(await fs.readFile(path.join(repo, 'Topics/Deep/A/pic.png')))]).toEqual([0x89, 0x50, 0x4e, 0x47, 0, 1, 2, 3]);
+  });
+
+  it('a single file moved with edits is one commit with a rename', async () => {
+    const body = 'index line\n'.repeat(20);
+    await put('Index.md', `[one](Projects/A/One.md)\n${body}`);
+    await git(repo, ['commit', '-am', 'longer index']);
+    await fsLayer().moveWithEdits(`${KB}/Index.md`, `${KB}/Home/Index.md`, [
+      { path: `${KB}/Home/Index.md`, lockAt: `${KB}/Index.md`, content: `[one](../Projects/A/One.md)\n${body}` },
+    ], 'Move Index');
+    const stat = (await git(repo, ['show', '-M', '--name-status', '--format=', 'HEAD'])).trim();
+    expect(stat).toMatch(/^R\d+\tIndex\.md\tHome\/Index\.md$/);
+  });
+
+  it('a lock held past the retries changes nothing and names the busy file', async () => {
+    // A file inside the moved folder, locked in the middle of the sorted
+    // order: the locks taken before it must all be given back.
+    lockedPaths.add(`${KB}/Projects/A/Two.md`);
+    const head = await git(repo, ['rev-parse', 'HEAD']);
+    // The real retry window: three attempts, two seconds apart.
+    const err = await fsLayer().moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A').catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(MoveLockedError);
+    expect((err as Error).message).toContain(`"${KB}/Projects/A/Two.md" is being edited by Bob`);
+    expect(await git(repo, ['rev-parse', 'HEAD'])).toBe(head);
+    expect((await git(repo, ['status', '--porcelain'])).trim()).toBe('');
+    expect(workflow.commitChanges).not.toHaveBeenCalled();
+    // Every lock taken was given back untouched.
+    expect(released(workflow.releaseLockUntouched)).toEqual([`${KB}/Index.md`, `${KB}/Projects/A`, `${KB}/Projects/A/One.md`]);
+    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
+    expect(workflow.releaseLock).not.toHaveBeenCalled();
+    expect(await read('Index.md')).toBe('[one](Projects/A/One.md)\n');
+  }, 20_000);
+
+  it('a file saved into the folder while the locks were being taken refuses the move, nothing moved', async () => {
+    const acquire = workflow.acquireLock as ReturnType<typeof vi.fn>;
+    let arrived = false;
+    acquire.mockImplementation(async () => {
+      // The first lock is the moment somebody else's save lands in the folder.
+      if (!arrived) {
+        arrived = true;
+        await put('Projects/A/Late.md', 'late\n');
+      }
+      return { acquired: true, lock: { holderName: 'Alice' } };
+    });
+    const head = await git(repo, ['rev-parse', 'HEAD']);
+    const err = await fsLayer().moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A').catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(MoveRacedError);
+    expect((err as Error).message).toContain(`"${KB}/Projects/A/Late.md" was added`);
+    expect(await git(repo, ['rev-parse', 'HEAD'])).toBe(head);
+    expect(workflow.commitChanges).not.toHaveBeenCalled();
+    expect(await read('Projects/A/Late.md')).toBe('late\n');
+    expect(await read('Index.md')).toBe('[one](Projects/A/One.md)\n');
+    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
+    expect(released(workflow.releaseLockUntouched).length).toBeGreaterThan(0);
+  });
+
+  it('a move that fails and cannot be undone releases every lock with the discard, and says both', async () => {
+    (workflow.commitChanges as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+      // Something takes the old place while the move is in flight, so the
+      // undo's rename finds its destination occupied.
+      await put('Projects/A/Taken.md', 'x\n');
+      throw new Error('commit exploded');
+    });
+    const err = await fsLayer().moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A').catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(MoveUndoError);
+    expect((err as Error).message).toContain('commit exploded');
+    expect((err as Error).message).toContain('could not be undone');
+    // Nothing is handed back as untouched: every path goes with the discard.
+    expect(workflow.releaseLockUntouched).not.toHaveBeenCalled();
+    const discarded = released(workflow.releaseLockNoCommit);
+    expect(discarded).toContain(`${KB}/Projects/A`);
+    expect(discarded).toContain(`${KB}/Topics/Deep/A/One.md`);
+    expect(discarded).toContain(`${KB}/Index.md`);
+  });
+
+  it('a commit that landed but could not be pushed enqueues the committed paths only; the folder locks go back untouched', async () => {
+    // The real commit lands; only its push is refused.
+    const commit = (workflow.commitChanges as ReturnType<typeof vi.fn>).getMockImplementation()!;
+    (workflow.commitChanges as ReturnType<typeof vi.fn>).mockImplementation(async (...args: unknown[]) => {
+      await commit(...args);
+      throw new PushNeedsAgentResolutionError('feature-test', `${KB}/Index.md`, 'refused', '(not attempted)', 'refused');
+    });
+    const commitsBefore = await git(repo, ['rev-list', '--count', 'HEAD']);
+    await expect(
+      fsLayer().moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A'),
+    ).rejects.toBeInstanceOf(PushNeedsAgentResolutionError);
+    // The commit stands — the tree is as committed, nothing rolled back —
+    // and only its push is owed.
+    expect(Number(await git(repo, ['rev-list', '--count', 'HEAD']))).toBe(Number(commitsBefore) + 1);
+    expect((await git(repo, ['status', '--porcelain'])).trim()).toBe('');
+    expect(await read('Topics/Deep/A/One.md')).toContain('../../../NodeTypes/Task.md');
+    const enqueued = released(workflow.releaseLock);
+    const untouched = released(workflow.releaseLockUntouched);
+    // Every file the commit named is enqueued…
+    for (const p of [`${KB}/Index.md`, `${KB}/Projects/A/One.md`, `${KB}/Topics/Deep/A/One.md`, `${KB}/Topics/Deep/A/pic.png`]) {
+      expect(enqueued).toContain(p);
+    }
+    // …and the folder locks, which name nothing committed, are not.
+    expect(enqueued).not.toContain(`${KB}/Projects/A`);
+    expect(enqueued).not.toContain(`${KB}/Topics/Deep/A`);
+    expect(untouched).toEqual([`${KB}/Projects/A`, `${KB}/Topics/Deep/A`]);
+  });
+
+  it('locks every file of a moved folder at its old and its new path', async () => {
+    await fsLayer().moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A');
+    const locked = (workflow.acquireLock as ReturnType<typeof vi.fn>).mock.calls.map((c) => c[2] as string);
+    for (const name of ['One.md', 'Two.md', 'pic.png']) {
+      expect(locked).toContain(`${KB}/Projects/A/${name}`);
+      expect(locked).toContain(`${KB}/Topics/Deep/A/${name}`);
+    }
+    expect(locked).toEqual([...locked].sort());
+  });
+
+  it('a lock store that throws gives back the locks already held, and changes nothing', async () => {
+    (workflow.acquireLock as ReturnType<typeof vi.fn>).mockImplementation(async (_w: string, _b: string, p: string) => {
+      if (p === `${KB}/Projects/A/One.md`) throw new Error('lock store down');
+      return { acquired: true, lock: { holderName: 'Alice' } };
+    });
+    await expect(
+      fsLayer().moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A'),
+    ).rejects.toThrow('lock store down');
+    expect(released(workflow.releaseLockUntouched)).toEqual([`${KB}/Index.md`, `${KB}/Projects/A`]);
+    expect((await git(repo, ['status', '--porcelain'])).trim()).toBe('');
+  });
+
+  it('every edit is judged again once the locks are held, and a refusal there changes nothing', async () => {
+    const acquire = workflow.acquireLock as ReturnType<typeof vi.fn>;
+    // A validator whose verdict depends on the state under the locks.
+    const validateWrite = vi.fn(async (p: string) => {
+      if (acquire.mock.calls.length > 0 && p.endsWith('Index.md')) throw new Error('refused under lock');
+    });
+    const head = await git(repo, ['rev-parse', 'HEAD']);
+    await expect(
+      fsLayer(validateWrite).moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A'),
+    ).rejects.toThrow('refused under lock');
+    expect(validateWrite.mock.calls.filter((c) => c[0] === `${KB}/Index.md`)).toHaveLength(2);
+    expect(await git(repo, ['rev-parse', 'HEAD'])).toBe(head);
+    expect((await git(repo, ['status', '--porcelain'])).trim()).toBe('');
+    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
+    expect(released(workflow.releaseLockUntouched)).toContain(`${KB}/Index.md`);
+  });
+
+  it('an edit whose bytes cannot be put back is released with the discard, not untouched', async () => {
+    (workflow.commitChanges as ReturnType<typeof vi.fn>).mockImplementationOnce(async () => {
+      // The restore of Index.md will fail: a folder now sits at its path.
+      await fs.rm(path.join(repo, 'Index.md'));
+      await fs.mkdir(path.join(repo, 'Index.md'));
+      throw new Error('commit exploded');
+    });
+    await expect(
+      fsLayer().moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A'),
+    ).rejects.toThrow('commit exploded');
+    expect(released(workflow.releaseLockNoCommit)).toEqual([`${KB}/Index.md`]);
+    expect(released(workflow.releaseLockUntouched)).not.toContain(`${KB}/Index.md`);
+    // The moved file's edit was put back, and its lock released untouched.
+    expect(await read('Projects/A/One.md')).toContain('../../NodeTypes/Task.md');
+    expect(released(workflow.releaseLockUntouched)).toContain(`${KB}/Projects/A/One.md`);
+  });
+
+  it('a check refusal under the locks changes nothing', async () => {
+    const head = await git(repo, ['rev-parse', 'HEAD']);
+    await expect(
+      fsLayer().moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A', async () => {
+        throw new Error('changed meanwhile');
+      }),
+    ).rejects.toThrow('changed meanwhile');
+    expect(await git(repo, ['rev-parse', 'HEAD'])).toBe(head);
+    expect((await git(repo, ['status', '--porcelain'])).trim()).toBe('');
+  });
+
+  it('a failing commit puts every byte back and undoes the move', async () => {
+    (workflow.commitChanges as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('commit exploded'));
+    await expect(
+      fsLayer().moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A'),
+    ).rejects.toThrow('commit exploded');
+    expect((await git(repo, ['status', '--porcelain', '--untracked-files=all'])).trim()).toBe('');
+    expect(await read('Index.md')).toBe('[one](Projects/A/One.md)\n');
+    expect(await read('Projects/A/One.md')).toContain('../../NodeTypes/Task.md');
+  });
+});

package/src/modules/kb-fs/locking-filesystem.ts

@@ -70,6 +70,57 @@ class CheckRefusal {
   constructor(readonly reason: unknown) {}
 }
 
+/**
+ * `moveWithEdits` could not take a lock: another writer held `path` past the
+ * retries. Nothing was moved or written.
+ */
+export class MoveLockedError extends Error {
+  constructor(
+    readonly path: string,
+    readonly holderName: string | null,
+  ) {
+    super(
+      `"${path}" is being edited by ${holderName ?? 'another user'}, so nothing was moved and no link was changed. ` +
+        'Try the move again later.',
+    );
+    this.name = 'MoveLockedError';
+  }
+}
+
+/**
+ * `moveWithEdits` found a file in the folder that was not there when the
+ * locks were planned: somebody saved into the folder meanwhile. Nothing was
+ * moved; the caller plans again against the folder as it is now.
+ */
+export class MoveRacedError extends Error {
+  constructor(readonly path: string) {
+    super(`"${path}" was added to the folder while the move was being prepared, so nothing was moved. Run the move again.`);
+    this.name = 'MoveRacedError';
+  }
+}
+
+/**
+ * `moveWithEdits` failed after the rename and could not put the folder back.
+ * The locks were released with the discard, so the working tree is reset to
+ * the last commit rather than left half-moved; the error carries both
+ * failures for the log.
+ */
+export class MoveUndoError extends Error {
+  constructor(
+    readonly src: string,
+    readonly dest: string,
+    readonly cause: unknown,
+    readonly undoFailure: unknown,
+  ) {
+    super(
+      `Moving "${src}" to "${dest}" failed (${cause instanceof Error ? cause.message : String(cause)}), and the move ` +
+        `could not be undone (${undoFailure instanceof Error ? undoFailure.message : String(undoFailure)}). ` +
+        'The working copy has been reset to the last commit; check the folder before trying again.',
+    );
+    this.name = 'MoveUndoError';
+  }
+}
+
 /**
  * A pre-disk write validator: called with the (workspace-relative path, full
  * candidate content) of a write; throw (or reject) to refuse it. `appliesTo`
@@ -389,6 +440,242 @@ export class LockingFilesystem extends GitGuardedFilesystem {
     }
   }
 
+  /**
+   * A move and the link edits it brings, as ONE change: `move_file` with link
+   * rewriting on. Where `moveFile` lands a move as two queued single-path
+   * commits (a delete, a create), this takes every lock first — both ends of
+   * the move, every file a moved folder holds at its old and its new path, and
+   * every file it edits — in deterministic order, renames,
+   * writes the edits, and commits the whole set synchronously in one commit,
+   * so git sees the move as a rename beside the edits.
+   *
+   * `edits[].path` is where each file sits AFTER the move (a moved file's
+   * edit lands at its new path); `edits[].lockAt` is where it sits now, and is
+   * the path locked. `check` runs once every lock is held and before anything
+   * changes — the caller confirms there that the bytes its edits were computed
+   * from are still the bytes on disk.
+   *
+   * Fail-closed: a lock still held by another writer after the retries throws
+   * {@link MoveLockedError} naming that path, with nothing moved and nothing
+   * written; a failure after the rename puts every edited file's bytes back and
+   * the move undone before the error leaves. Only edited text passes through
+   * memory: a folder's other files, binaries among them, are renamed on disk.
+   */
+  async moveWithEdits(
+    src: string,
+    dest: string,
+    edits: { path: string; lockAt: string; content: string }[],
+    summary: string,
+    check?: () => Promise<void>,
+  ): Promise<Change | null> {
+    const { workflow, workspaceId, branch, user } = this.lockContext;
+    await this.assertNotGitInternals(src);
+    await this.assertNotGitInternals(dest);
+    this.assertInsideRepo(dest);
+    for (const e of edits) {
+      await this.assertNotGitInternals(e.path);
+      this.assertInsideRepo(e.path);
+    }
+    await this.validateResultingWrite(dest, () => this.readFile(src));
+    if (this.lockContext.validateWrite) {
+      for (const e of edits) await this.lockContext.validateWrite(e.path, e.content);
+    }
+    // A folder's files are locked one by one at both ends: a save to one of
+    // them mid-move would otherwise recreate the old path, or ride this
+    // move's commit, whose scope names every one of them.
+    const movedNow = src === dest ? [] : await this.filesBelow(src);
+    const paths = [
+      ...new Set([
+        src,
+        dest,
+        ...movedNow.flatMap((f) => [f, dest + f.slice(src.length)]),
+        ...edits.map((e) => e.lockAt),
+      ]),
+    ].sort();
+    const acquired: string[] = [];
+    // Locked paths left holding bytes this move wrote and could not put back:
+    // released with the discard (reset to HEAD), so those bytes cannot ride
+    // the next save's commit as if they were this move's result.
+    const dirtyLeft = new Set<string>();
+    // The paths the commit names (set once it is built): the only ones a
+    // release with a commit may enqueue. The folder locks at either end
+    // coordinate and name nothing committed, so they go back untouched —
+    // enqueued, a later write under those folders would be this move's.
+    let scope: string[] = [];
+    const release = async (mode: 'untouched' | 'enqueue'): Promise<void> => {
+      for (const p of acquired) {
+        try {
+          if (mode === 'enqueue' && scope.includes(p)) await workflow.releaseLock(workspaceId, branch, p, user);
+          else if (mode === 'enqueue') await workflow.releaseLockUntouched(workspaceId, branch, p, user);
+          else if (dirtyLeft.has(p)) await workflow.releaseLockNoCommit(workspaceId, branch, p, user);
+          else await workflow.releaseLockUntouched(workspaceId, branch, p, user);
+        } catch (releaseErr) {
+          log.warn(`lock release failed for "${p}" during moveWithEdits:`, { err: releaseErr });
+        }
+      }
+    };
+    for (const p of paths) {
+      let holderName: string | null = null;
+      let ok = false;
+      try {
+        for (let attempt = 0; attempt < ACQUIRE_RETRY_ATTEMPTS; attempt++) {
+          const result = await workflow.acquireLock(workspaceId, branch, p, user);
+          if (result.acquired) {
+            ok = true;
+            break;
+          }
+          holderName = result.lock.holderName;
+          if (attempt < ACQUIRE_RETRY_ATTEMPTS - 1) await sleep(ACQUIRE_RETRY_DELAY_MS);
+        }
+      } catch (err) {
+        // The lock store failing is no reason to keep the locks already held
+        // until their TTL runs out.
+        await release('untouched');
+        throw err;
+      }
+      if (!ok) {
+        await release('untouched');
+        throw new MoveLockedError(p, holderName);
+      }
+      acquired.push(p);
+    }
+    // Judged again under the locks, on the bytes that land: a validator that
+    // reads the current file must see the state each edit replaces.
+    try {
+      // The folder's files, listed again now that every lock is held: a file
+      // saved into it between the listing above and the locks would ride
+      // this move's commit without its lock — refused, and the caller tries
+      // again against the folder as it is now.
+      if (src !== dest) {
+        const locked = new Set(paths);
+        const arrived = (await this.filesBelow(src)).find((f) => !locked.has(f));
+        if (arrived !== undefined) throw new MoveRacedError(arrived);
+      }
+      // Placement, re-judged where the rename happens: a link introduced on
+      // the way to either end since the caller's preflight would carry the
+      // rename outside the repository.
+      // The entries themselves included: an edit destination replaced by a
+      // link since planning would have the write follow it.
+      await this.assertNoLinkBelowBase(src);
+      await this.assertNoLinkBelowBase(dest);
+      for (const e of edits) await this.assertNoLinkBelowBase(e.path);
+      await this.validateResultingWrite(dest, () => this.readFile(src));
+      if (this.lockContext.validateWrite) {
+        for (const e of edits) await this.lockContext.validateWrite(e.path, e.content);
+      }
+      await check?.();
+    } catch (err) {
+      await release('untouched');
+      throw err;
+    }
+
+    // Done in this order, and undone in the reverse one.
+    let moved = false;
+    const written: { path: string; lockAt: string; before: Buffer | null }[] = [];
+    try {
+      await this.moveNoReplace(src, dest);
+      moved = true;
+      for (const e of edits) {
+        const before = await this.readIfExists(e.path);
+        written.push({ path: e.path, lockAt: e.lockAt, before });
+        await super.writeFile(e.path, e.content);
+      }
+      // The commit names every file at both ends: a folder's files one by one,
+      // because the scope matches files, not the folders holding them. From
+      // the files LOCKED, not the destination as it is now: a file saved into
+      // the new place since the rename is somebody else's, under no lock of
+      // this move, and stays out of its commit.
+      const movedFiles = src === dest ? [] : movedNow.map((f) => dest + f.slice(src.length));
+      scope = [
+        ...new Set([
+          ...movedFiles.flatMap((f) => [f, src + f.slice(dest.length)]),
+          ...edits.map((e) => e.path),
+        ]),
+      ].sort();
+      const change = await workflow.commitChanges(workspaceId, user, summary, scope);
+      await release('untouched');
+      if (change) this.lockContext.fileChanges?.emit({ workspaceId, branch, paths: scope, byUser: user });
+      return change;
+    } catch (err) {
+      if (err instanceof PushNeedsAgentResolutionError) {
+        // The commit landed; only its push needs help. Releasing with a commit
+        // arms the pending-commits worker's push retry (see `writeFiles`).
+        await release('enqueue');
+        throw err;
+      }
+      for (const w of written.reverse()) {
+        try {
+          if (w.before === null) {
+            const absolute = this.resolveAbsolutePath(w.path);
+            if (absolute) await fs.rm(absolute, { force: true });
+          } else {
+            await super.writeFile(w.path, w.before);
+          }
+        } catch (restoreErr) {
+          log.warn(`could not restore "${w.path}" after a failed move:`, { err: restoreErr });
+          dirtyLeft.add(w.path);
+          dirtyLeft.add(w.lockAt);
+        }
+      }
+      if (moved) {
+        try {
+          await this.moveNoReplace(dest, src);
+        } catch (undoErr) {
+          // The folder is still at its new place, holding bytes this move
+          // wrote. Nothing may release that as "untouched": every locked path
+          // is let go with the discard, so the half-done move is reset rather
+          // than left for a later writer to publish, and the failure says so.
+          log.warn(`could not undo the move of "${src}" after a failure:`, { err: undoErr });
+          for (const p of acquired) dirtyLeft.add(p);
+          await release('untouched');
+          throw new MoveUndoError(src, dest, err, undoErr);
+        }
+      }
+      await release('untouched');
+      throw err;
+    }
+  }
+
+  /**
+   * Refuse a path when any folder between this filesystem's root and it is a
+   * link — judged by `lstat` on each ancestor, under the locks, right before
+   * the rename that would otherwise follow the link out of the repository.
+   */
+  private async assertNoLinkBelowBase(inputPath: string): Promise<void> {
+    const absolute = this.resolveAbsolutePath(inputPath);
+    if (!absolute) return;
+    const base = path.resolve(this.basePath);
+    let current = path.resolve(absolute);
+    const ancestors: string[] = [];
+    while (current.startsWith(base) && current !== base) {
+      ancestors.push(current);
+      current = path.dirname(current);
+    }
+    for (const ancestor of ancestors) {
+      const stat = await lstatOrNull(ancestor);
+      if (stat?.isSymbolicLink()) {
+        throw new Error(`"${inputPath}" is reached through a link, so nothing was moved.`);
+      }
+    }
+  }
+
+  /** Every file at or under `inputPath` (workspace-relative), the path itself when it is a file. */
+  private async filesBelow(inputPath: string): Promise<string[]> {
+    const absolute = this.resolveAbsolutePath(inputPath);
+    if (!absolute) return [inputPath];
+    const stat = await lstatOrNull(absolute);
+    if (!stat?.isDirectory()) return [inputPath];
+    const out: string[] = [];
+    const walk = async (abs: string, rel: string): Promise<void> => {
+      for (const e of await fs.readdir(abs, { withFileTypes: true })) {
+        if (e.isDirectory()) await walk(path.join(abs, e.name), `${rel}/${e.name}`);
+        else out.push(`${rel}/${e.name}`);
+      }
+    };
+    await walk(absolute, inputPath);
+    return out;
+  }
+
   /**
    * Write several files and commit them as ONE atomic change — the multi-file
    * counterpart to `writeFile`, for the rare case where a set of files must