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

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

@@ -42,6 +42,7 @@ import {
   type WriteOptions,
 } from '@mastra/core/workspace';
 import type { AuthUser, Change, IWorkflowService } from '@bevel-software/platform-shared';
+import { PushNeedsAgentResolutionError } from './workflow.errors.js';
 import type { FileChangeNotifier } from './file-change-notifier.js';
 import type { CreationGrantPlan, ICreatorAccess } from '../access/creator-access.js';
 
@@ -167,6 +168,10 @@ export class LockingFilesystem extends LocalFilesystem {
    * `git commit`, then push), and release WITHOUT a per-file commit. Fail-closed:
    * if any lock can't be acquired, or a write/commit throws, nothing is committed
    * (the failure-path `releaseLockNoCommit` discards the uncommitted bytes).
+   * The ONE exception is `PushNeedsAgentResolutionError` — a POST-commit
+   * failure (the commit landed, the push didn't): locks release via
+   * `releaseLock` so the enqueued release commit arms the pending-commits
+   * worker's push retry, and the error still propagates to the caller.
    *
    * `writes[].path` is workspace-relative (like `writeFile`). We do the disk
    * write here; `commitChanges` only stages + commits what's on disk (the git
@@ -210,13 +215,50 @@ export class LockingFilesystem extends LocalFilesystem {
     // locked too (a delete mutates that path just like a write).
     const paths = [...new Set([...writes.map((w) => w.path), ...deletes])].sort();
     const acquired: string[] = [];
-    const releaseAll = async (): Promise<void> => {
+    // Paths whose on-disk bytes THIS batch replaced (caller writes/deletes,
+    // recorded just before each disk op so a mid-write throw still counts).
+    // Deliberately NOT the seed paths: a seed write is an additive merge of
+    // the CURRENT bytes, and a failed one restores its pre-image itself —
+    // only a seed whose restore ALSO failed joins the discard set, via
+    // `failedSeedDiscards` (see the seed loop).
+    const dirtied = new Set<string>();
+    // Seed paths left holding known-partial bytes: the seed write threw
+    // mid-write AND the pre-image restore failed too. These must release
+    // with the discard so the corrupt bytes can't outlive the batch.
+    const failedSeedDiscards = new Set<string>();
+    // Release every acquired lock, each with the semantics its outcome
+    // earned. Three shapes (mirroring the three WorkflowService releases):
+    //
+    //   'discard'   → releaseLockNoCommit: resets the path's working tree to
+    //     HEAD. Only for bytes this batch itself owns — its committed paths
+    //     (clean tree, the discard no-ops), its own failed writes, and a
+    //     failed-restore seed (fail-closed: partial bytes must not land).
+    //   'enqueue'   → releaseLock: enqueues a commit-on-release row. Only
+    //     for the push-retry unwind, and only on the batch's OWN committed
+    //     paths — the enqueued row is the vehicle that retries the push.
+    //   'untouched' → releaseLockUntouched: drops the lock row and nothing
+    //     else. For every path the batch merely LOCKED (a creator seed that
+    //     no-op'd or fully restored itself, a caller path never reached):
+    //     such a path may hold a PRIOR save's dirty bytes whose commit is
+    //     still queued — a discard would silently destroy that landed save,
+    //     and an enqueue would re-attribute its queued row to THIS user and
+    //     reset its retry ladder.
+    const releaseAll = async (
+      modeOf: (p: string) => 'discard' | 'enqueue' | 'untouched',
+    ): Promise<void> => {
       for (const p of acquired) {
         try {
-          await workflow.releaseLockNoCommit(workspaceId, branch, p, user);
+          const mode = modeOf(p);
+          if (mode === 'discard') {
+            await workflow.releaseLockNoCommit(workspaceId, branch, p, user);
+          } else if (mode === 'enqueue') {
+            await workflow.releaseLock(workspaceId, branch, p, user);
+          } else {
+            await workflow.releaseLockUntouched(workspaceId, branch, p, user);
+          }
         } catch (releaseErr) {
           console.warn(
-            `[locking-fs] releaseLockNoCommit failed for "${p}" during writeFiles:`,
+            `[locking-fs] lock release failed for "${p}" during writeFiles:`,
             releaseErr instanceof Error ? releaseErr.message : releaseErr,
           );
         }
@@ -237,7 +279,9 @@ export class LockingFilesystem extends LocalFilesystem {
         if (attempt < ACQUIRE_RETRY_ATTEMPTS - 1) await sleep(ACQUIRE_RETRY_DELAY_MS);
       }
       if (!ok) {
-        await releaseAll();
+        // Nothing written yet — every held lock is a merely-locked path, so
+        // the unwind must leave disk and queue exactly as they are.
+        await releaseAll(() => 'untouched');
         throw new Error(
           `Skipped editing "${p}" — locked by ${holderName ?? 'another user'}. ` +
             `Continuing with other edits; try this one again later.`,
@@ -263,55 +307,173 @@ export class LockingFilesystem extends LocalFilesystem {
       }
     }
 
+    // The paths this batch actually TOUCHED — the caller's writes + deletes,
+    // plus each seed whose bytes really landed below. Kept separate from
+    // `acquired` (which only tracks held LOCKS): a seed lock is taken before
+    // we know whether the seed write happens, and scoping the commit to a
+    // merely-locked path would sweep in another save's still-queued dirty
+    // bytes on that path under this batch's author/summary.
+    const touched = [...paths];
+    // Seeds whose bytes LANDED, with the pre-image read under their lock:
+    // if the batch's commit then fails, these must be rolled back to that
+    // pre-image (not to HEAD — the pre-image may be a prior save's queued
+    // bytes) so an uncommitted grant can't sit on disk as if it were real.
+    const landedSeeds = new Map<string, { current: string; existedBefore: boolean }>();
     let change: Change | null;
     try {
       // Write/delete every file to disk inside the locks (workspace-relative;
       // LocalFilesystem resolves against basePath), then commit + push the whole
       // set as ONE change. `commitChanges` only stages + commits what's on disk.
-      for (const w of writes) await super.writeFile(w.path, w.content);
-      for (const p of deletes) await super.deleteFile(p);
+      for (const w of writes) {
+        dirtied.add(w.path);
+        await super.writeFile(w.path, w.content);
+      }
+      for (const p of deletes) {
+        dirtied.add(p);
+        await super.deleteFile(p);
+      }
       // Seeds merge into the CURRENT on-disk bytes (read under the lock) so a
       // concurrent creator's grant survives; per-seed failures are best-effort.
       for (const [p, apply] of seeds) {
-        try {
-          let current = '';
-          const absolute = this.resolveAbsolutePath(p);
-          if (absolute) {
-            try {
-              current = await fs.readFile(absolute, 'utf-8');
-            } catch {
-              // Not there yet — the normal case for a brand-new directory.
-            }
+        let current = '';
+        let existedBefore = false;
+        const absolute = this.resolveAbsolutePath(p);
+        if (absolute) {
+          try {
+            current = await fs.readFile(absolute, 'utf-8');
+            existedBefore = true;
+          } catch {
+            // Not there yet — the normal case for a brand-new directory.
           }
-          const next = apply(current);
-          if (next !== current) await super.writeFile(p, next);
+        }
+        let next: string;
+        try {
+          next = apply(current);
+        } catch (err) {
+          // Plan failed before any bytes moved — the path is untouched.
+          console.warn(
+            `[locking-fs] creator access.md seed failed for "${p}":`,
+            err instanceof Error ? err.message : err,
+          );
+          continue;
+        }
+        if (next === current) continue;
+        try {
+          await super.writeFile(p, next);
+          touched.push(p);
+          landedSeeds.set(p, { current, existedBefore });
         } catch (err) {
+          // The write itself threw — it may have died MID-WRITE, leaving
+          // partial bytes on disk. Left alone, those bytes would ride the
+          // path's release (or the next save) as if they were real content.
+          // Restore the pre-image we read under this very lock: on success
+          // the path is byte-identical to before the batch and releases as
+          // merely-locked; only when even the restore fails does the path
+          // join the discard set (reset to HEAD on release — fail-closed,
+          // partial bytes must never land). Residual risk, documented: in
+          // that double-failure case a prior save's still-queued dirty bytes
+          // on this path are lost to the discard — accepted, because the
+          // alternative is committing known-corrupt bytes under their name.
           console.warn(
             `[locking-fs] creator access.md seed failed for "${p}":`,
             err instanceof Error ? err.message : err,
           );
+          let restored = false;
+          try {
+            if (existedBefore) {
+              await super.writeFile(p, current);
+              restored = true;
+            } else if (absolute) {
+              // Didn't exist before — remove whatever the failed write left.
+              await fs.rm(absolute, { force: true });
+              restored = true;
+            }
+          } catch {
+            // Fall through to the discard set.
+          }
+          if (!restored) {
+            failedSeedDiscards.add(p);
+            console.warn(
+              `[locking-fs] could not restore pre-seed bytes for "${p}" — releasing with discard`,
+            );
+          }
         }
       }
-      change = await workflow.commitChanges(workspaceId, user, summary);
+      // Scope the commit to this batch's own paths (caller paths + landed
+      // seeds): on the shared per-branch workspace another save's bytes may be
+      // dirty with their commit still queued, and an unscoped commit would
+      // sweep them in under this batch's author/summary.
+      change = await workflow.commitChanges(workspaceId, user, summary, touched);
       if (seeds.size > 0) this.lockContext.creatorAccess?.noteAccessFileWritten(workspaceId);
     } catch (err) {
-      // A write or the commit threw — nothing should land. releaseLockNoCommit
-      // discards the uncommitted bytes for each acquired path.
-      await releaseAll();
+      if (err instanceof PushNeedsAgentResolutionError) {
+        // POST-commit failure: the commit LANDED and only the push needs help
+        // (thrown "with the commit intact"). Routing this through the discard
+        // release would strand the landed commit with nothing to retry the
+        // push — the next identical write no-ops against the committed bytes
+        // and the change stays unpublished forever. Release the batch's OWN
+        // committed paths WITH commit-on-release instead (the same posture
+        // AdminLockedCommits takes): each enqueued release commit no-ops on
+        // the clean tree, and the pending-commits worker then notices the
+        // unpushed commits and re-runs the cooperative push ladder. Merely-
+        // locked paths still release untouched — arming the retry never
+        // justifies re-attributing someone else's queued row (see
+        // releaseAll), and `touched` is never empty here (the commit that
+        // just landed had to have paths in scope).
+        const committed = new Set(touched);
+        await releaseAll((p) =>
+          committed.has(p) ? 'enqueue' : failedSeedDiscards.has(p) ? 'discard' : 'untouched',
+        );
+        throw err;
+      }
+      // A write or the commit threw — nothing of THIS batch should land.
+      // Landed seed bytes are uncommitted now too: roll each back to the
+      // pre-image read under its lock (which may be a prior save's queued
+      // bytes — a discard to HEAD would destroy those), and only a seed
+      // whose rollback ALSO fails joins the discard set, same fail-closed
+      // posture as a failed seed write.
+      for (const [p, pre] of landedSeeds) {
+        try {
+          if (pre.existedBefore) {
+            await super.writeFile(p, pre.current);
+          } else {
+            const absolute = this.resolveAbsolutePath(p);
+            if (absolute) await fs.rm(absolute, { force: true });
+          }
+        } catch {
+          failedSeedDiscards.add(p);
+          console.warn(
+            `[locking-fs] could not roll back seed bytes for "${p}" after a failed batch — releasing with discard`,
+          );
+        }
+      }
+      // The batch's own dirtied paths (and any failed-restore seed) release
+      // no-commit (the discard reverts them). Merely-locked paths — rolled-
+      // back seeds included — release untouched (see releaseAll).
+      await releaseAll((p) =>
+        dirtied.has(p) || failedSeedDiscards.has(p) ? 'discard' : 'untouched',
+      );
       throw err;
     }
-    // Commit already landed synchronously — release WITHOUT a per-file commit,
-    // else `releaseLock` would enqueue a second (duplicate) commit per path.
-    await releaseAll();
+    // Commit already landed synchronously — the `touched` paths are clean
+    // (nothing to discard, nothing to enqueue), so they release no-commit
+    // like the batch's other own-bytes paths; the discard no-ops on the
+    // clean tree, and a failed-restore seed's discard reverts its partial
+    // bytes. A seed lock whose write no-op'd (or fully restored itself)
+    // releases untouched: it was never this batch's to discard OR enqueue.
+    const committed = new Set(touched);
+    await releaseAll((p) =>
+      committed.has(p) || failedSeedDiscards.has(p) ? 'discard' : 'untouched',
+    );
     // This batch path commits via `commitChanges`, NOT the per-file queue, so it
     // skips `runPendingCommit`'s emit — fire the post-commit hook here with the
     // WHOLE batch as one event, so an expensive subscriber (id-repair rebuilds the
     // id index) reacts once per batch, not once per file. A no-op commit (clean
     // tree) changed nothing, so it emits nothing.
     if (change) {
-      // `acquired` = caller paths + any creator-grant seeds that landed in the
+      // `touched` = caller paths + any creator-grant seeds that landed in the
       // same commit — the exact set this batch may have touched.
-      this.lockContext.fileChanges?.emit({ workspaceId, branch, paths: acquired, byUser: user });
+      this.lockContext.fileChanges?.emit({ workspaceId, branch, paths: touched, byUser: user });
     }
     return change;
   }

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

@@ -34,7 +34,7 @@
  *                                                    (status='needs_attention')
  */
 
-import { and, eq, isNull, or, sql } from 'drizzle-orm';
+import { and, eq, inArray, isNull, or, sql } from 'drizzle-orm';
 import type { Database } from '../database/connection.js';
 import { pendingCommits } from '../database/schema.js';
 
@@ -411,6 +411,32 @@ export class PendingCommitsService {
     return rows[0]?.count ?? 0;
   }
 
+  /**
+   * Is a LIVE row — `pending` or `running`, the statuses the worker will
+   * still drive — queued for `(workspaceId, branch, path)`? A
+   * `needs_attention` row deliberately does NOT count: its ladder has
+   * escalated to a human and nothing will retry it, so a caller asking
+   * "is my landed-but-unpushed commit going to be published?" must hear no.
+   * Backs `IWorkflowService.hasQueuedCommit` (the synced-groups committer's
+   * armed-retry proof) and the coordination-release discard guard.
+   */
+  async hasLiveRowFor(rawWorkspaceId: string, branch: string, path: string): Promise<boolean> {
+    const workspaceId = canonicalWorkspaceId(rawWorkspaceId);
+    const rows = await this.db
+      .select({ id: pendingCommits.id })
+      .from(pendingCommits)
+      .where(
+        and(
+          eq(pendingCommits.workspaceId, workspaceId),
+          eq(pendingCommits.branch, branch),
+          eq(pendingCommits.path, path),
+          inArray(pendingCommits.status, ['pending', 'running']),
+        ),
+      )
+      .limit(1);
+    return rows.length > 0;
+  }
+
   /**
    * Is there ANY row (regardless of status) for this workspace? Used by the
    * git status path to tell an EXPECTED dirty working tree (files saved to

package/src/modules/workflow/review-workflow/__tests__/approval-states.test.ts

@@ -166,7 +166,6 @@ function makeAccessControl(byPath: EligibilityByPath): IAccessControl {
     findEmailByHash: async () => null,
     kbPrincipals: async () => ({ plugins: [], people: [] }),
     validateRolesYaml: () => ({ ok: true }),
-    referencesToRole: async () => [],
   };
 }
 

package/src/modules/workflow/review-workflow/__tests__/cancel-pr.test.ts

@@ -55,7 +55,6 @@ function makeAccessControl(adminEmails: string[] = []): IAccessControl {
     findEmailByHash: async () => null,
     kbPrincipals: async () => ({ plugins: [], people: [] }),
     validateRolesYaml: () => ({ ok: true }),
-    referencesToRole: async () => [],
   };
 }
 

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

@@ -463,8 +463,9 @@ export class WorkflowService implements IWorkflowService {
     workspaceId: string,
     user: AuthUser,
     summary: string,
+    onlyPaths?: string[],
   ): Promise<Change | null> {
-    const change = await this.git.commitChanges(workspaceId, user, summary);
+    const change = await this.git.commitChanges(workspaceId, user, summary, onlyPaths);
     // Same recovery as the per-file queue: a bare push here could strand the
     // just-made local commit (committed but never shared — breaking save=share)
     // on any non-fast-forward race. Pull-rebase + retry recovers the common
@@ -563,6 +564,7 @@ export class WorkflowService implements IWorkflowService {
     branch: string,
     targetPath: string,
     user: AuthUser,
+    opts?: { coordination?: boolean },
   ): Promise<AcquireLockResult> {
     // **Permission check at lock acquisition, not at commit time.** Under the
     // "disk is the source of truth" rule, once a write has landed on disk we
@@ -579,12 +581,22 @@ export class WorkflowService implements IWorkflowService {
     // boundary lives. Checking at HEAD (not at the working tree) so a user
     // can't grant themselves access by editing `roles.yaml` in the same
     // session.
-    if (isProtectedBranch(branch)) {
+    //
+    // **Coordination acquires skip the gate** (see the interface doc): the
+    // caller wants only mutual exclusion with the path's writer — e.g. the
+    // roles admin holding machine-owned `synced-groups.yaml` steady across
+    // its IdP-mode recheck — and will never write the path. Gating those on
+    // write permission would make a pure serialization hold impossible for
+    // exactly the paths (machine-owned ones) that need it most. No write
+    // authority flows from the hold: the mode is persisted on the lock row
+    // and `commitFileWhileLocked` / `releaseLock` refuse to treat a
+    // coordination hold as write possession (see those methods).
+    if (isProtectedBranch(branch) && !opts?.coordination) {
       // `assertCanWriteAtPath` throws AccessDeniedError on denial, with the
       // eligible-writers payload so the frontend can render a useful refusal.
       await this.assertCanWriteAtPath(workspaceId, branch, user.email, targetPath);
     }
-    const result = await this.fileLocks.acquire(workspaceId, branch, targetPath, user);
+    const result = await this.fileLocks.acquire(workspaceId, branch, targetPath, user, opts);
     if (result.acquired) {
       console.log(
         `[lock] ACQUIRE ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → acquired`,
@@ -650,6 +662,17 @@ export class WorkflowService implements IWorkflowService {
         { kind: 'lock-not-held', branch, path: targetPath },
       );
     }
+    // A coordination hold is NOT write possession (see `acquireLock`): it was
+    // acquired past the write-authorization gate on the promise that nothing
+    // gets written under it. Treating it like an edit lock here would let the
+    // holder checkpoint bytes onto a path — machine-owned files included —
+    // whose write rule they never passed.
+    if (lock.mode === 'coordination') {
+      throw new WorkflowValidationError(
+        `Cannot commit "${targetPath}": the lock is a coordination hold, which grants no write authority.`,
+        { kind: 'coordination-hold', branch, path: targetPath },
+      );
+    }
     const change = await this.git.commitFile(workspaceId, user, targetPath, summary);
     // Push the autosave commit so other users on the branch see it
     // without waiting for the eventual lock release. Best-effort, same
@@ -758,6 +781,24 @@ export class WorkflowService implements IWorkflowService {
         { kind: 'lock-not-held', branch, path: targetPath },
       );
     }
+    // Releasing a coordination hold must NEVER enqueue a commit: the hold was
+    // granted past the write-authorization gate (see `acquireLock`) on the
+    // promise that nothing gets written under it, so a release commit would
+    // publish whatever bytes are on disk — an unauthorized route write, a
+    // prior save's still-queued work — under this caller's name. Refusing
+    // (rather than silently degrading) surfaces the caller bug loudly; the
+    // sanctioned releases for a coordination hold are `releaseLockNoCommit`
+    // and `releaseLockUntouched`. Worst case a refused caller strands the
+    // row until its TTL.
+    if (lock.mode === 'coordination') {
+      console.warn(
+        `[lock] RELEASE refused ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → coordination hold (no commit may be enqueued)`,
+      );
+      throw new WorkflowValidationError(
+        `Cannot release lock on "${targetPath}" with a commit: it is a coordination hold. Use releaseLockNoCommit.`,
+        { kind: 'coordination-hold', branch, path: targetPath },
+      );
+    }
     // Order matters here:
     //   1. Drop the lock row. Other sessions can re-acquire immediately.
     //   2. Enqueue the commit. Worker will pick it up on next sweep.
@@ -940,20 +981,46 @@ export class WorkflowService implements IWorkflowService {
     // acquirer under the wrong author. The system's invariant is now:
     // every release leaves the working tree clean. If we're not
     // committing the bytes, we're throwing them away.
-    try {
-      await this.git.discardPath(workspaceId, targetPath);
-    } catch (err) {
-      // Best-effort: a discard failure is logged but doesn't block the
-      // lock release. Worst case the working tree stays dirty for one
-      // path until the next save on it cleans up.
-      console.warn(
-        `[workflow] discardPath failed for workspace=${workspaceId} branch=${branch} path=${targetPath}:`,
-        err instanceof Error ? err.message : err,
-      );
+    //
+    // One refinement for COORDINATION holds: the holder never legitimately
+    // wrote the path (the write paths refuse coordination possession), so
+    // anything dirty there is either bytes smuggled in around the workflow —
+    // which the discard rightly wipes — or a PRIOR save's work whose commit
+    // is still queued. Only the queue can tell those apart: when a live
+    // pending-commit row exists for the path, the dirty bytes are that
+    // queued save's and the discard would silently destroy a landed edit,
+    // so we skip it and let the worker publish them.
+    let skipDiscard = false;
+    if (lock.mode === 'coordination') {
+      try {
+        skipDiscard = await this.pendingCommits.hasLiveRowFor(workspaceId, branch, targetPath);
+      } catch (err) {
+        // Queue unreadable — fall back to the discard (the strict default:
+        // never let a coordination hold end with publishable stray bytes).
+        console.warn(
+          `[workflow] pending-commit lookup failed for workspace=${workspaceId} path=${targetPath}; discarding:`,
+          err instanceof Error ? err.message : err,
+        );
+      }
+    }
+    let discarded = false;
+    if (!skipDiscard) {
+      try {
+        await this.git.discardPath(workspaceId, targetPath);
+        discarded = true;
+      } catch (err) {
+        // Best-effort: a discard failure is logged but doesn't block the
+        // lock release. Worst case the working tree stays dirty for one
+        // path until the next save on it cleans up.
+        console.warn(
+          `[workflow] discardPath failed for workspace=${workspaceId} branch=${branch} path=${targetPath}:`,
+          err instanceof Error ? err.message : err,
+        );
+      }
     }
     await this.fileLocks.release(workspaceId, branch, targetPath, user);
     console.log(
-      `[lock] RELEASE-NO-COMMIT done ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → discarded + released`,
+      `[lock] RELEASE-NO-COMMIT done ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → ${discarded ? 'discarded + released' : 'released (working tree untouched)'}`,
     );
     this.events?.emit({
       kind: 'lock-released',
@@ -962,16 +1029,69 @@ export class WorkflowService implements IWorkflowService {
       path: targetPath,
     });
     // The disk just changed (revert / removal). Tell anyone watching so
-    // their open tabs refresh to the post-discard state.
+    // their open tabs refresh to the post-discard state — but only when the
+    // discard actually RAN: a skipped one (coordination hold shielding a
+    // queued save's bytes) or a failed one left the disk exactly as it was,
+    // and announcing a change would trigger refresh/invalidation for nothing.
+    if (discarded) {
+      this.events?.emit({
+        kind: 'file-changed',
+        workspaceId,
+        branch,
+        path: targetPath,
+        newSha: null,
+        byUserId: user.id,
+        byUserName: user.name,
+      });
+    }
+  }
+
+  /**
+   * Third release shape (see the interface doc): the caller held the lock
+   * but never touched the path, so the release must leave BOTH the disk and
+   * the commit queue exactly as they are. `releaseLock` would enqueue a
+   * commit — re-attributing a prior save's still-queued dirty bytes to this
+   * caller and resetting that row's retry ladder; `releaseLockNoCommit`
+   * would discard to HEAD — destroying those same bytes. This drops the
+   * lock row, nothing else. Same idempotent non-holder no-op (and emit
+   * discipline) as `releaseLockNoCommit`.
+   */
+  async releaseLockUntouched(
+    workspaceId: string,
+    branch: string,
+    targetPath: string,
+    user: AuthUser,
+  ): Promise<void> {
+    console.log(
+      `[lock] RELEASE-UNTOUCHED start ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id}`,
+    );
+    const lock = await this.fileLocks.get(workspaceId, branch, targetPath);
+    if (!lock || lock.holderUserId !== user.id) {
+      console.log(
+        `[lock] RELEASE-UNTOUCHED no-op ws=${workspaceId} path=${targetPath} → ${lock ? `held by ${lock.holderName}` : 'no lock row'}`,
+      );
+      return;
+    }
+    await this.fileLocks.release(workspaceId, branch, targetPath, user);
+    console.log(
+      `[lock] RELEASE-UNTOUCHED done ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → released (disk + queue untouched)`,
+    );
     this.events?.emit({
-      kind: 'file-changed',
+      kind: 'lock-released',
       workspaceId,
       branch,
       path: targetPath,
-      newSha: null,
-      byUserId: user.id,
-      byUserName: user.name,
     });
+    // No `file-changed` here on purpose — unlike the no-commit release,
+    // nothing on disk moved.
+  }
+
+  hasQueuedCommit(workspaceId: string, branch: string, targetPath: string): Promise<boolean> {
+    return this.pendingCommits.hasLiveRowFor(workspaceId, branch, targetPath);
+  }
+
+  hasUnpushedCommits(workspaceId: string): Promise<boolean> {
+    return this.git.hasUnpushedCommits(workspaceId);
   }
 
   getLock(
@@ -1958,7 +2078,7 @@ export class WorkflowService implements IWorkflowService {
         }
 
         // Commit ONLY roles.yaml via commitFile (`git add -- roles.yaml`), never
-        // `commitChanges` (`git add -A`): on this shared per-branch workspace other
+        // an unscoped `commitChanges` (`git add -A`): on this shared per-branch workspace other
         // files may be dirty from a concurrent same-branch save, and `add -A` would
         // sweep those unrelated edits into our "preserve roles.yaml" commit under the
         // wrong author/message. Feature branch → the protected-branch gate doesn't