@bevel-software/platform-core-backend 0.10.0 → 0.11.0

package/src/modules/workflow/__tests__/locking-filesystem.test.ts

@@ -3,7 +3,9 @@ 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 { LocalFilesystem } from '@mastra/core/workspace';
 import { LockingFilesystem } from '../locking-filesystem.js';
+import { PushNeedsAgentResolutionError } from '../workflow.errors.js';
 
 const USER: AuthUser = {
   id: 'user-1',
@@ -27,6 +29,7 @@ function makeWorkflow(): IWorkflowService {
     }),
     releaseLock: vi.fn().mockResolvedValue(null),
     releaseLockNoCommit: vi.fn().mockResolvedValue(undefined),
+    releaseLockUntouched: vi.fn().mockResolvedValue(undefined),
     heartbeatLock: vi.fn(),
     getLock: vi.fn(),
     commitFileWhileLocked: vi.fn(),
@@ -280,6 +283,39 @@ describe('LockingFilesystem.writeFiles — batch with deletes + one batched chan
     expect(emitted).toHaveLength(0);
   });
 
+  it('a POST-commit push failure releases WITH commit-on-release (arms the worker retry), never the discard path', async () => {
+    // PushNeedsAgentResolutionError means the commit LANDED and only the push
+    // needs help. Routing it through releaseLockNoCommit would leave the
+    // landed commit with no retry vehicle — the next identical write would
+    // no-op against the committed bytes and the change stays unpublished
+    // forever. The batch must releaseLock (the enqueued release commit no-ops
+    // on the clean tree and the worker's unpushed-commits check re-runs the
+    // push ladder) and still propagate the error.
+    const workflow = makeWorkflow();
+    (workflow.commitChanges as ReturnType<typeof vi.fn>).mockRejectedValue(
+      new PushNeedsAgentResolutionError('feat', 'A.md', 'non-fast-forward', 'rebase failed'),
+    );
+    const emitted: unknown[] = [];
+    const fsLayer = new LockingFilesystem(
+      { basePath: root, contained: true },
+      {
+        workflow,
+        workspaceId: 'ws-feat',
+        branch: 'feat',
+        user: USER,
+        fileChanges: { emit: (c: unknown) => emitted.push(c) } as never,
+      },
+    );
+
+    await expect(
+      fsLayer.writeFiles([{ path: 'A.md', content: 'x' }], 'batch'),
+    ).rejects.toBeInstanceOf(PushNeedsAgentResolutionError);
+
+    expect(workflow.releaseLock).toHaveBeenCalledWith('ws-feat', 'feat', 'A.md', USER);
+    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
+    expect(emitted).toHaveLength(0);
+  });
+
   it('emits nothing on a no-op commit (clean tree)', async () => {
     const workflow = makeWorkflow();
     (workflow.commitChanges as ReturnType<typeof vi.fn>).mockResolvedValue(null);
@@ -431,6 +467,306 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     expect(creatorAccess.noteAccessFileWritten).toHaveBeenCalledWith('ws-feat');
   });
 
+  it('a NO-OP seed stays OUT of the commit scope (its dirty bytes must never ride this batch)', async () => {
+    // The seed's access.md already carries the grant — apply() returns the
+    // current bytes unchanged. The lock is still taken (and released), but the
+    // path must NOT be passed to commitChanges: on the shared workspace it may
+    // be dirty from ANOTHER save whose commit is still queued, and scoping the
+    // batch to a merely-locked path would sweep those bytes in under this
+    // batch's author/summary.
+    await fs.mkdir(path.join(root, 'KnowledgeBase/Mine'), { recursive: true });
+    const seedContent = '---\nread:\n  - Alice <alice@example.com>\n---\n';
+    await fs.writeFile(path.join(root, 'KnowledgeBase/Mine/access.md'), seedContent);
+    const workflow = makeWorkflow();
+    const creatorAccess = makeCreatorAccess();
+    creatorAccess.planForCreate.mockResolvedValue({
+      kind: 'seed-access-md',
+      wsRelPath: 'KnowledgeBase/Mine/access.md',
+      apply: (current: string) => current, // grant already present → no-op
+    });
+    const emitted: { paths: string[] }[] = [];
+    const fsLayer = new LockingFilesystem(
+      { basePath: root, contained: true },
+      {
+        workflow,
+        workspaceId: 'ws-feat',
+        branch: 'feat',
+        user: USER,
+        creatorAccess,
+        fileChanges: { emit: (c: { paths: string[] }) => emitted.push(c) } as never,
+      },
+    );
+    await fsLayer.writeFiles([{ path: 'KnowledgeBase/Mine/doc.md', content: 'body' }], 'batch');
+
+    // The seed's lock cycle still ran (acquired + released)...
+    const locked = (workflow.acquireLock as ReturnType<typeof vi.fn>).mock.calls.map((c) => c[2]);
+    expect(locked).toContain('KnowledgeBase/Mine/access.md');
+    // ...but the commit is scoped to the caller's path only.
+    const commitPaths = (workflow.commitChanges as ReturnType<typeof vi.fn>).mock.calls[0][3];
+    expect(commitPaths).toEqual(['KnowledgeBase/Mine/doc.md']);
+    expect(emitted[0].paths).toEqual(['KnowledgeBase/Mine/doc.md']);
+    // The seeded file is untouched.
+    expect(await fs.readFile(path.join(root, 'KnowledgeBase/Mine/access.md'), 'utf-8')).toBe(
+      seedContent,
+    );
+  });
+
+  it('a NO-OP seed lock releases UNTOUCHED — a prior save\'s queued bytes must survive as-is', async () => {
+    // The prior-save-pending scenario: a previous save on the access.md
+    // released its lock via releaseLock, so its bytes are DIRTY on the shared
+    // workspace with the commit still queued. This batch then takes the seed
+    // lock, finds the grant already present (apply() no-ops), and commits
+    // only its own paths. Releasing the seed lock with NO-COMMIT semantics
+    // would git-discard the path back to HEAD — silently destroying the prior
+    // save. Releasing it with COMMIT-ON-RELEASE would be almost as bad: the
+    // enqueue refreshes the existing pending row's author to THIS user and
+    // resets its retry ladder — the prior save's bytes would publish under
+    // the wrong name. The seed lock must release UNTOUCHED (drop the lock
+    // row, leave disk and queue exactly as they are).
+    await fs.mkdir(path.join(root, 'KnowledgeBase/Mine'), { recursive: true });
+    const priorSave = '---\nread:\n  - Alice <alice@example.com>\n---\nprior queued bytes\n';
+    await fs.writeFile(path.join(root, 'KnowledgeBase/Mine/access.md'), priorSave);
+    const workflow = makeWorkflow();
+    const creatorAccess = makeCreatorAccess();
+    creatorAccess.planForCreate.mockResolvedValue({
+      kind: 'seed-access-md',
+      wsRelPath: 'KnowledgeBase/Mine/access.md',
+      apply: (current: string) => current, // grant already present → no-op
+    });
+    const fsLayer = new LockingFilesystem(
+      { basePath: root, contained: true },
+      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, creatorAccess },
+    );
+    await fsLayer.writeFiles([{ path: 'KnowledgeBase/Mine/doc.md', content: 'body' }], 'batch');
+
+    // The batch's OWN committed path releases no-commit (clean — discard no-ops)...
+    expect(workflow.releaseLockNoCommit).toHaveBeenCalledWith(
+      'ws-feat', 'feat', 'KnowledgeBase/Mine/doc.md', USER,
+    );
+    // ...but the merely-locked seed path releases UNTOUCHED — never the
+    // enqueue, never the discard.
+    expect(workflow.releaseLockUntouched).toHaveBeenCalledWith(
+      'ws-feat', 'feat', 'KnowledgeBase/Mine/access.md', USER,
+    );
+    expect(workflow.releaseLock).not.toHaveBeenCalled();
+    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalledWith(
+      'ws-feat', 'feat', 'KnowledgeBase/Mine/access.md', USER,
+    );
+  });
+
+  it('locks acquired before an acquire CONTENTION release UNTOUCHED (nothing written yet)', async () => {
+    // First path acquires, second is contended: nothing has been written, so
+    // the first path may hold ONLY someone else's still-queued bytes — the
+    // unwind must neither discard them nor enqueue them under this user.
+    const workflow = makeWorkflow();
+    (workflow.acquireLock as ReturnType<typeof vi.fn>)
+      .mockResolvedValueOnce({ acquired: true, lock: { holderUserId: 'user-1', holderName: 'Alice' } })
+      .mockResolvedValue({ acquired: false, lock: { holderUserId: 'bob', holderName: 'Bob' } });
+    const fsLayer = new LockingFilesystem(
+      { basePath: root, contained: true },
+      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER },
+    );
+    await expect(
+      fsLayer.writeFiles(
+        [
+          { path: 'A.md', content: 'a' },
+          { path: 'B.md', content: 'b' },
+        ],
+        'batch',
+      ),
+    ).rejects.toThrow(/locked by Bob/);
+    expect(workflow.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', 'A.md', USER);
+    expect(workflow.releaseLock).not.toHaveBeenCalled();
+    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
+  }, 10_000);
+
+  it('a seed write that dies MID-WRITE restores the pre-image and releases UNTOUCHED', async () => {
+    // The partial-write hazard: super.writeFile throws after touching disk,
+    // leaving bytes that are neither the old content nor the new. The seed
+    // loop read the pre-image under this very lock, so it can put it back —
+    // after which the path is byte-identical to before the batch and must
+    // release untouched (a prior save's queued bytes, if any, survive).
+    await fs.mkdir(path.join(root, 'KnowledgeBase/Mine'), { recursive: true });
+    const priorBytes = 'prior queued bytes\n';
+    const seedPath = 'KnowledgeBase/Mine/access.md';
+    await fs.writeFile(path.join(root, seedPath), priorBytes);
+    const workflow = makeWorkflow();
+    const creatorAccess = makeCreatorAccess();
+    creatorAccess.planForCreate.mockResolvedValue({
+      kind: 'seed-access-md',
+      wsRelPath: seedPath,
+      apply: (current: string) => current + 'read: Alice\n',
+    });
+    const fsLayer = new LockingFilesystem(
+      { basePath: root, contained: true },
+      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, creatorAccess },
+    );
+    // Fail the SEED write once (simulating a mid-write death that left
+    // partial bytes); every other write — including the restore — passes
+    // through to the real filesystem.
+    const original = LocalFilesystem.prototype.writeFile;
+    let failedOnce = false;
+    const spy = vi
+      .spyOn(LocalFilesystem.prototype, 'writeFile')
+      .mockImplementation(async function (this: unknown, p, c, o) {
+        if (p === seedPath && !failedOnce) {
+          failedOnce = true;
+          await original.call(this as LocalFilesystem, p, 'PARTIAL');
+          throw new Error('disk exploded mid-write');
+        }
+        return original.call(this as LocalFilesystem, p, c, o);
+      });
+    try {
+      await fsLayer.writeFiles([{ path: 'KnowledgeBase/Mine/doc.md', content: 'body' }], 'batch');
+    } finally {
+      spy.mockRestore();
+    }
+    // Pre-image restored — the partial bytes did not outlive the batch.
+    expect(await fs.readFile(path.join(root, seedPath), 'utf-8')).toBe(priorBytes);
+    // The failed seed stays OUT of the commit scope and releases untouched.
+    const commitPaths = (workflow.commitChanges as ReturnType<typeof vi.fn>).mock.calls[0][3];
+    expect(commitPaths).toEqual(['KnowledgeBase/Mine/doc.md']);
+    expect(workflow.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', seedPath, USER);
+    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalledWith(
+      'ws-feat', 'feat', seedPath, USER,
+    );
+    expect(workflow.releaseLock).not.toHaveBeenCalled();
+  });
+
+  it('a LANDED seed rolls back to its pre-image when the batch commit fails — grant bytes must not outlive the batch uncommitted', async () => {
+    // The gap this pins: the seed write SUCCEEDED (path in `touched`) but
+    // `commitChanges` then failed, so nothing of the batch was committed.
+    // Releasing the seed untouched would leave its uncommitted grant bytes
+    // on disk as if they were real; discarding to HEAD would destroy a prior
+    // save's queued bytes. The right restore is the pre-image read under the
+    // seed's own lock.
+    await fs.mkdir(path.join(root, 'KnowledgeBase/Mine'), { recursive: true });
+    const priorBytes = 'prior queued bytes\n';
+    const seedPath = 'KnowledgeBase/Mine/access.md';
+    await fs.writeFile(path.join(root, seedPath), priorBytes);
+    const workflow = makeWorkflow();
+    (workflow.commitChanges as ReturnType<typeof vi.fn>).mockRejectedValue(
+      new Error('commit exploded'),
+    );
+    const creatorAccess = makeCreatorAccess();
+    creatorAccess.planForCreate.mockResolvedValue({
+      kind: 'seed-access-md',
+      wsRelPath: seedPath,
+      apply: (current: string) => current + 'read: Alice\n',
+    });
+    const fsLayer = new LockingFilesystem(
+      { basePath: root, contained: true },
+      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, creatorAccess },
+    );
+    await expect(
+      fsLayer.writeFiles([{ path: 'KnowledgeBase/Mine/doc.md', content: 'body' }], 'batch'),
+    ).rejects.toThrow('commit exploded');
+    // The landed grant was rolled back to the pre-image, byte-identical…
+    expect(await fs.readFile(path.join(root, seedPath), 'utf-8')).toBe(priorBytes);
+    // …and the seed releases UNTOUCHED (the prior queued bytes are not this
+    // batch's to discard), while the caller's own write releases via discard.
+    expect(workflow.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', seedPath, USER);
+    expect(workflow.releaseLockNoCommit).toHaveBeenCalledWith(
+      'ws-feat', 'feat', 'KnowledgeBase/Mine/doc.md', USER,
+    );
+    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalledWith(
+      'ws-feat', 'feat', seedPath, USER,
+    );
+  });
+
+  it('a seed whose write AND restore both fail releases with DISCARD — partial bytes must never land', async () => {
+    // The double-failure residual: the seed write died mid-write and even the
+    // pre-image restore failed, so the path holds known-partial bytes. The
+    // release must reset it to HEAD (releaseLockNoCommit) — never enqueue the
+    // corrupt bytes as a commit, never leave them for the next acquirer.
+    await fs.mkdir(path.join(root, 'KnowledgeBase/Mine'), { recursive: true });
+    const seedPath = 'KnowledgeBase/Mine/access.md';
+    await fs.writeFile(path.join(root, seedPath), 'prior\n');
+    const workflow = makeWorkflow();
+    const creatorAccess = makeCreatorAccess();
+    creatorAccess.planForCreate.mockResolvedValue({
+      kind: 'seed-access-md',
+      wsRelPath: seedPath,
+      apply: (current: string) => current + 'read: Alice\n',
+    });
+    const fsLayer = new LockingFilesystem(
+      { basePath: root, contained: true },
+      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, creatorAccess },
+    );
+    const original = LocalFilesystem.prototype.writeFile;
+    const spy = vi
+      .spyOn(LocalFilesystem.prototype, 'writeFile')
+      .mockImplementation(async function (this: unknown, p, c, o) {
+        if (p === seedPath) throw new Error('disk exploded'); // seed write AND restore
+        return original.call(this as LocalFilesystem, p, c, o);
+      });
+    try {
+      await fsLayer.writeFiles([{ path: 'KnowledgeBase/Mine/doc.md', content: 'body' }], 'batch');
+    } finally {
+      spy.mockRestore();
+    }
+    // The unrecoverable seed path releases via the discard, everything else
+    // untouched-or-no-commit as usual; the batch itself still succeeds.
+    expect(workflow.releaseLockNoCommit).toHaveBeenCalledWith('ws-feat', 'feat', seedPath, USER);
+    expect(workflow.releaseLockUntouched).not.toHaveBeenCalledWith(
+      'ws-feat', 'feat', seedPath, USER,
+    );
+    expect(workflow.releaseLock).not.toHaveBeenCalled();
+    const commitPaths = (workflow.commitChanges as ReturnType<typeof vi.fn>).mock.calls[0][3];
+    expect(commitPaths).toEqual(['KnowledgeBase/Mine/doc.md']);
+  });
+
+  it('push-retry unwind: committed paths re-arm via releaseLock, a merely-locked seed stays untouched', async () => {
+    // PushNeedsAgentResolutionError with a no-op seed in the batch: the
+    // committed caller path must release commit-on-release (that enqueued row
+    // IS the push-retry vehicle), while the seed that never wrote must NOT be
+    // swept into the same enqueue — its path may carry a prior save's queued
+    // row that a fresh enqueue would re-attribute and reset.
+    await fs.mkdir(path.join(root, 'KnowledgeBase/Mine'), { recursive: true });
+    const seedPath = 'KnowledgeBase/Mine/access.md';
+    await fs.writeFile(path.join(root, seedPath), 'grant already present\n');
+    const workflow = makeWorkflow();
+    (workflow.commitChanges as ReturnType<typeof vi.fn>).mockRejectedValue(
+      new PushNeedsAgentResolutionError('feat', '(batch)', 'non-fast-forward', 'rebase failed'),
+    );
+    const creatorAccess = makeCreatorAccess();
+    creatorAccess.planForCreate.mockResolvedValue({
+      kind: 'seed-access-md',
+      wsRelPath: seedPath,
+      apply: (current: string) => current, // no-op — merely locked
+    });
+    const fsLayer = new LockingFilesystem(
+      { basePath: root, contained: true },
+      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, creatorAccess },
+    );
+    await expect(
+      fsLayer.writeFiles([{ path: 'KnowledgeBase/Mine/doc.md', content: 'body' }], 'batch'),
+    ).rejects.toBeInstanceOf(PushNeedsAgentResolutionError);
+    expect(workflow.releaseLock).toHaveBeenCalledWith(
+      'ws-feat', 'feat', 'KnowledgeBase/Mine/doc.md', USER,
+    );
+    expect(workflow.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', seedPath, USER);
+    expect(workflow.releaseLock).not.toHaveBeenCalledWith('ws-feat', 'feat', seedPath, USER);
+    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
+  });
+
+  it('a LANDED seed rides the commit scope with the caller paths', async () => {
+    const workflow = makeWorkflow();
+    const creatorAccess = makeCreatorAccess();
+    creatorAccess.planForCreate.mockResolvedValue({
+      kind: 'seed-access-md',
+      wsRelPath: 'KnowledgeBase/Mine/access.md',
+      apply: () => '---\nread:\n  - Alice <alice@example.com>\n---\n',
+    });
+    const fsLayer = new LockingFilesystem(
+      { basePath: root, contained: true },
+      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, creatorAccess },
+    );
+    await fsLayer.writeFiles([{ path: 'KnowledgeBase/Mine/doc.md', content: 'body' }], 'batch');
+    const commitPaths = (workflow.commitChanges as ReturnType<typeof vi.fn>).mock.calls[0][3];
+    expect(commitPaths).toEqual(['KnowledgeBase/Mine/doc.md', 'KnowledgeBase/Mine/access.md']);
+  });
+
   it('a planner failure never blocks the write', async () => {
     const workflow = makeWorkflow();
     const creatorAccess = makeCreatorAccess();

package/src/modules/workflow/__tests__/preserve-roles-yaml.test.ts

@@ -37,7 +37,7 @@ function noopAccessControl(): IAccessControl {
     canDownload: vi.fn(), canOwner: vi.fn(), eligibleOwners: vi.fn(), eligibleDownloaders: vi.fn(),
     eligibleWriters: vi.fn(), eligibleWriterEmails: vi.fn(), eligibleOwnerEmails: vi.fn(),
     grantSources: vi.fn(), invalidate: vi.fn(), findEmailByHash: vi.fn(), kbPrincipals: vi.fn(),
-    validateRolesYaml: vi.fn(), referencesToRole: vi.fn(), canWriteAtRef: vi.fn(),
+    validateRolesYaml: vi.fn(), canWriteAtRef: vi.fn(),
     canWriteBatchAtRef: vi.fn(), eligibleWritersAtRef: vi.fn(), eligibleWritersForPathsAtRef: vi.fn(),
   } as unknown as IAccessControl;
 }

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

@@ -175,6 +175,38 @@ describe('WorkflowService.commitFileWhileLocked', () => {
     expect(emitSpy).not.toHaveBeenCalled();
   });
 
+  it('REFUSES a coordination hold — it is not write possession', async () => {
+    // A coordination hold skipped the write-authorization gate on acquire
+    // (pure mutex, see acquireLock). Letting the same holder checkpoint
+    // bytes through it would publish to a path — machine-owned files
+    // included — whose write rule they never passed.
+    const git = makeGit();
+    const locks = {
+      ...makeFileLocks(USER.id),
+      get: vi.fn().mockResolvedValue({
+        branch: 'feat/x',
+        path: 'foo.md',
+        holderUserId: USER.id,
+        holderName: 'Alice',
+        mode: 'coordination',
+        acquiredAt: '',
+        lastHeartbeatAt: '',
+        expiresAt: '',
+      }),
+    } as unknown as FileLockService;
+    const svc = makeFacade(git, locks, events);
+
+    const err = await svc
+      .commitFileWhileLocked('ws-1', 'feat/x', 'foo.md', USER)
+      .then(() => null)
+      .catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(WorkflowValidationError);
+    expect((err as WorkflowValidationError).payload?.kind).toBe('coordination-hold');
+    expect(git.commitFile).not.toHaveBeenCalled();
+    expect(git.push).not.toHaveBeenCalled();
+    expect(emitSpy).not.toHaveBeenCalled();
+  });
+
   it('still emits file-changed when push fails with a non-recoverable error (commit landed locally)', async () => {
     // Autosave is best-effort on push. If we can't ship the bytes upstream
     // (e.g. transient auth failure), we still emit `file-changed` so the

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

@@ -95,7 +95,6 @@ function makeAccessControl(): IAccessControl {
     findEmailByHash: vi.fn().mockResolvedValue(null),
     kbPrincipals: vi.fn().mockResolvedValue({ plugins: [], people: [] }),
     validateRolesYaml: vi.fn().mockReturnValue({ ok: true }),
-    referencesToRole: vi.fn().mockResolvedValue([]),
     canWriteAtRef: vi.fn().mockResolvedValue(null),
     canWriteBatchAtRef: vi.fn().mockResolvedValue(null),
     eligibleWritersAtRef: vi.fn().mockResolvedValue(null),
@@ -387,7 +386,19 @@ describe('WorkflowService — file lock delegation', () => {
     const fileLocks = makeFileLockService();
     const svc = new WorkflowService(makeDb(), makeGit(), makePrs(), makeReviewWorkflow(), makeWorkspaceService(), makeAccessControl(), fileLocks, makePendingCommits(), 'knowledge-base');
     await svc.acquireLock('w1', 'b', 'p', makeUser());
-    expect(fileLocks.acquire).toHaveBeenCalledWith('w1', 'b', 'p', expect.objectContaining({ email: 'alice@example.com' }));
+    expect(fileLocks.acquire).toHaveBeenCalledWith('w1', 'b', 'p', expect.objectContaining({ email: 'alice@example.com' }), undefined);
+  });
+
+  it('acquireLock forwards the coordination flag so the lock row persists its mode', async () => {
+    // The mode must reach the store: an in-memory-only distinction would let
+    // a coordination hold masquerade as an edit lock on the very next read
+    // (which is how the write paths decide what the holder may do).
+    const fileLocks = makeFileLockService();
+    const svc = new WorkflowService(makeDb(), makeGit(), makePrs(), makeReviewWorkflow(), makeWorkspaceService(), makeAccessControl(), fileLocks, makePendingCommits(), 'knowledge-base');
+    await svc.acquireLock('w1', 'b', 'p', makeUser(), { coordination: true });
+    expect(fileLocks.acquire).toHaveBeenCalledWith(
+      'w1', 'b', 'p', expect.objectContaining({ email: 'alice@example.com' }), { coordination: true },
+    );
   });
 
   it('getLock delegates to FileLockService.get', async () => {

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

@@ -47,7 +47,10 @@ const CHANGE: Change = {
   committedAt: '2026-04-20T00:00:00.000Z',
 };
 
-function makeFileLocks(holderUserId: string): FileLockService {
+function makeFileLocks(
+  holderUserId: string,
+  mode: 'edit' | 'coordination' = 'edit',
+): FileLockService {
   return {
     acquire: vi.fn(),
     heartbeat: vi.fn(),
@@ -57,6 +60,7 @@ function makeFileLocks(holderUserId: string): FileLockService {
       path: 'foo.md',
       holderUserId,
       holderName: 'Alice',
+      mode,
       acquiredAt: '',
       lastHeartbeatAt: '',
       expiresAt: '',
@@ -75,6 +79,7 @@ function makePending(): PendingCommitsService {
     markNeedsAttention: vi.fn().mockResolvedValue(undefined),
     listNeedsAttention: vi.fn().mockResolvedValue([]),
     countPending: vi.fn().mockResolvedValue(0),
+    hasLiveRowFor: vi.fn().mockResolvedValue(false),
     startupReconcile: vi.fn().mockResolvedValue(undefined),
   } as unknown as PendingCommitsService;
 }
@@ -93,6 +98,7 @@ function makeGit(overrides: Partial<{
   let pushCalls = 0;
   return {
     commitFile: vi.fn().mockResolvedValue(commitFileResult),
+    discardPath: vi.fn().mockResolvedValue(undefined),
     hasUnpushedCommits: vi.fn().mockResolvedValue(overrides.hasUnpushedCommits ?? false),
     push: vi.fn().mockImplementation(async () => {
       pushCalls++;
@@ -241,6 +247,138 @@ describe('WorkflowService.releaseLock — new (enqueue, no synchronous commit)',
     // is still held, and we'd lie to any SSE subscriber by emitting.
     expect(emitSpy).not.toHaveBeenCalled();
   });
+
+  it('REFUSES to release a coordination hold — never enqueues, never drops the row', async () => {
+    // A coordination hold was acquired PAST the write-authorization gate on
+    // the promise that nothing gets written under it. If releaseLock treated
+    // it like an edit lock, the enqueued release commit would publish
+    // whatever bytes sit on disk — on machine-owned paths included — under
+    // this caller's name. The sanctioned release is releaseLockNoCommit.
+    const git = makeGit();
+    const locks = makeFileLocks(USER.id, 'coordination');
+    const pending = makePending();
+    const svc = makeFacade(git, locks, pending, events);
+
+    const err = await svc
+      .releaseLock('ws-1', 'feat/x', 'foo.md', USER)
+      .then(() => null)
+      .catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(WorkflowValidationError);
+    expect((err as WorkflowValidationError).payload?.kind).toBe('coordination-hold');
+    expect(pending.enqueue).not.toHaveBeenCalled();
+    expect(locks.release).not.toHaveBeenCalled();
+    expect(emitSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe('WorkflowService.releaseLockUntouched — drop the row, leave disk AND queue alone', () => {
+  let events: WorkflowEventBus;
+  let emitSpy: MockInstance;
+
+  beforeEach(() => {
+    events = new WorkflowEventBus();
+    emitSpy = vi.spyOn(events, 'emit');
+  });
+
+  it('releases the lock without enqueueing or discarding, emits lock-released only', async () => {
+    const git = makeGit();
+    const locks = makeFileLocks(USER.id);
+    const pending = makePending();
+    const svc = makeFacade(git, locks, pending, events);
+
+    await svc.releaseLockUntouched('ws-1', 'feat/x', 'foo.md', USER);
+
+    expect(locks.release).toHaveBeenCalledTimes(1);
+    // The whole point: a prior save's dirty bytes on this path must survive
+    // (no discard) without being re-attributed to this caller (no enqueue).
+    expect(pending.enqueue).not.toHaveBeenCalled();
+    expect(git.discardPath).not.toHaveBeenCalled();
+    expect(git.commitFile).not.toHaveBeenCalled();
+    expect(git.push).not.toHaveBeenCalled();
+    expect(emitSpy.mock.calls.map((c) => (c[0] as { kind: string }).kind)).toEqual(['lock-released']);
+  });
+
+  it('no-ops (idempotent) when the caller does not hold the lock', async () => {
+    const git = makeGit();
+    const locks = makeFileLocks('someone-else');
+    const pending = makePending();
+    const svc = makeFacade(git, locks, pending, events);
+
+    await expect(
+      svc.releaseLockUntouched('ws-1', 'feat/x', 'foo.md', USER),
+    ).resolves.toBeUndefined();
+    expect(locks.release).not.toHaveBeenCalled();
+    expect(emitSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe('WorkflowService.releaseLockNoCommit — coordination-hold discard guard', () => {
+  let events: WorkflowEventBus;
+
+  beforeEach(() => {
+    events = new WorkflowEventBus();
+  });
+
+  it('discards as usual on an EDIT hold, without consulting the queue', async () => {
+    const git = makeGit();
+    const pending = makePending();
+    const svc = makeFacade(git, makeFileLocks(USER.id), pending, events);
+
+    await svc.releaseLockNoCommit('ws-1', 'feat/x', 'foo.md', USER);
+
+    expect(git.discardPath).toHaveBeenCalledWith('ws-1', 'foo.md');
+    expect(pending.hasLiveRowFor).not.toHaveBeenCalled();
+  });
+
+  it('discards a coordination hold when the queue has NO live row (wipes smuggled bytes)', async () => {
+    const git = makeGit();
+    const pending = makePending();
+    const emitSpy = vi.spyOn(events, 'emit');
+    const svc = makeFacade(git, makeFileLocks(USER.id, 'coordination'), pending, events);
+
+    await svc.releaseLockNoCommit('ws-1', 'feat/x', 'foo.md', USER);
+
+    expect(pending.hasLiveRowFor).toHaveBeenCalledWith('ws-1', 'feat/x', 'foo.md');
+    expect(git.discardPath).toHaveBeenCalledWith('ws-1', 'foo.md');
+    // The disk really changed here, so watchers are told.
+    expect(emitSpy.mock.calls.map((c) => (c[0] as { kind: string }).kind)).toEqual([
+      'lock-released',
+      'file-changed',
+    ]);
+  });
+
+  it('SKIPS the discard on a coordination hold when a live queued row exists (a prior save owns the bytes)', async () => {
+    // The coordination holder never legitimately wrote the path, so dirty
+    // bytes covered by a live pending-commit row belong to an EARLIER save
+    // whose commit hasn't drained yet — discarding to HEAD would silently
+    // destroy that landed edit.
+    const git = makeGit();
+    const pending = makePending();
+    (pending.hasLiveRowFor as ReturnType<typeof vi.fn>).mockResolvedValue(true);
+    const emitSpy = vi.spyOn(events, 'emit');
+    const svc = makeFacade(git, makeFileLocks(USER.id, 'coordination'), pending, events);
+
+    await svc.releaseLockNoCommit('ws-1', 'feat/x', 'foo.md', USER);
+
+    expect(git.discardPath).not.toHaveBeenCalled();
+    // The lock still releases — only the discard is skipped. And since the
+    // disk did NOT change, no file-changed goes out: announcing one would
+    // false-refresh every watcher of a file that is exactly as it was.
+    expect(emitSpy.mock.calls.map((c) => (c[0] as { kind: string }).kind)).toEqual([
+      'lock-released',
+    ]);
+  });
+});
+
+describe('WorkflowService.hasQueuedCommit', () => {
+  it('delegates to the pending-commits queue per (workspace, branch, path)', async () => {
+    const pending = makePending();
+    (pending.hasLiveRowFor as ReturnType<typeof vi.fn>).mockResolvedValue(true);
+    const svc = makeFacade(makeGit(), makeFileLocks(USER.id), pending, new WorkflowEventBus());
+
+    await expect(svc.hasQueuedCommit('ws-1', 'feat/x', 'foo.md')).resolves.toBe(true);
+    expect(pending.hasLiveRowFor).toHaveBeenCalledWith('ws-1', 'feat/x', 'foo.md');
+  });
 });
 
 describe('WorkflowService.runPendingCommit — worker entry point', () => {

package/src/modules/workflow/file-lock.service.ts

@@ -38,6 +38,9 @@ function rowToFileLock(row: typeof fileLocks.$inferSelect): FileLock {
     path: row.path,
     holderUserId: row.holderUserId,
     holderName: row.holderName,
+    // The column carries a NOT NULL 'edit' default, so rows predating the
+    // mode column read back as plain edit locks — the strictest reading.
+    mode: row.mode === 'coordination' ? 'coordination' : 'edit',
     acquiredAt: row.acquiredAt.toISOString(),
     lastHeartbeatAt: row.lastHeartbeatAt.toISOString(),
     expiresAt: row.expiresAt.toISOString(),
@@ -58,12 +61,21 @@ export class FileLockService {
    *     "Locked by X" without a follow-up call.
    *   - Existing row, live, same user: refresh TTL + `{ acquired: true }`
    *     so re-acquiring your own lock is idempotent.
+   *
+   * `opts.coordination` stamps the row's `mode` as `'coordination'` — a
+   * pure-mutex hold that grants no write authority (see
+   * `IWorkflowService.acquireLock`). The mode is persisted so the workflow
+   * service's write paths can refuse to treat the hold as write possession
+   * for the row's whole lifetime; a takeover of an expired row re-stamps the
+   * mode, so a stale coordination row can't launder a later edit acquire
+   * (or vice versa).
    */
   async acquire(
     workspaceId: string,
     branch: string,
     targetPath: string,
     user: AuthUser,
+    opts?: { coordination?: boolean },
   ): Promise<AcquireLockResult> {
     const now = new Date();
     const expiresAt = new Date(now.getTime() + LOCK_TTL_MS);
@@ -96,6 +108,7 @@ export class FileLockService {
     // `heartbeat()` (which has its own same-user UPDATE), and the
     // editor's save flow detects "I already hold it" via `getLock` in
     // `workspace.routes.withLock` rather than re-acquiring.
+    const mode = opts?.coordination ? 'coordination' : 'edit';
     const upsertResult = await this.db
       .insert(fileLocks)
       .values({
@@ -104,6 +117,7 @@ export class FileLockService {
         path: targetPath,
         holderUserId: user.id,
         holderName: user.name,
+        mode,
         acquiredAt: now,
         lastHeartbeatAt: now,
         expiresAt,
@@ -113,6 +127,7 @@ export class FileLockService {
         set: {
           holderUserId: user.id,
           holderName: user.name,
+          mode,
           acquiredAt: now,
           lastHeartbeatAt: now,
           expiresAt,