mixdog 1.4.1 → 1.4.2

package/src/runtime/shared/worktrees/activity-gate.mjs

@@ -1,334 +1,262 @@
-import { randomUUID } from 'node:crypto';
-import { readFileSync } from 'node:fs';
+/**
+ * Workspace admission: the turn, command and management leases of a Git
+ * repository (activity-ledger.mjs keeps their ledger). One admission thread
+ * per process (activity-ledger-worker.mjs) owns every lease the process holds
+ * and runs the ledger's locked read-modify-publish, one request at a time in
+ * the order the requests were made. The fsynced writes therefore never block
+ * this thread's event loop, and no two threads of the process ever update the
+ * ledger at once.
+ *
+ * The asynchronous API posts its request and settles with the outcome. The
+ * synchronous API posts the same request and blocks (Atomics.wait) until it
+ * is answered, for at most MIXDOG_ADMISSION_SYNC_TIMEOUT_MS: a request still
+ * running then is reported with an unknown outcome — a grant is withdrawn by
+ * the admission thread once it finishes, a release still lands. A grant or
+ * release is answered only once both copies hold its outcome (or it was
+ * refused). If the admission thread stops, every outstanding and later
+ * request fails (workspace-admission-unreadable) until the process restarts:
+ * it is never restarted, since a ledger lock it held still names this live
+ * process. The exit waits (bounded the same way) for the requests already
+ * posted, so a release made just before exiting still lands.
+ */
 import { setTimeout as delay } from 'node:timers/promises';
-import { isAbsolute, join } from 'node:path';
-import { parseJsonText, quarantinePath, withFileLockSync, writeFileAtomicSync } from '../atomic-file.mjs';
-import { isPidAliveOrUnknown } from '../pid-liveness.mjs';
-import { findGitLayout } from './git-head.mjs';
-import { canonicalPath, isWithin, samePath } from './paths.mjs';
-import { worktreeError, worktreeRefusal } from './contract.mjs';
-import { readRegistrySync } from './registry.mjs';
+import { MessageChannel, receiveMessageOnPort, SHARE_ENV, Worker } from 'node:worker_threads';
+import { WorktreeError, worktreeRefusal } from './contract.mjs';
+import { envMs, LEDGER_SLOTS as SLOT } from './activity-ledger.mjs';
 
-const FILE = 'mixdog-workspace-admission.json';
-const overlaps = (a, b) => isWithin(a, b) || isWithin(b, a);
+export { isExternalCheckout } from './activity-ledger.mjs';
 
-/**
- * The admission policy's external exception: a linked checkout Mixdog did not
- * create (not a project's main folder, not a registered managed worktree) is
- * not lock-blocked by what is held elsewhere. Management takes no lease on it
- * and its readers are admitted whatever is held outside it; its running
- * readers still refuse a management action that touches it. A management lease
- * published inside the checkout itself (another profile, or a registry
- * recovered empty) still refuses its readers.
- */
-export function isExternalCheckout(folder) {
-  const layout = findGitLayout(folder, { strict: true });
-  if (!layout || samePath(layout.gitDir, layout.commonDir)) return false;
-  let entries;
-  try {
-    entries = readRegistrySync().entries;
-  } catch {
-    // A damaged registry is kept aside and reads as a restored or empty one;
-    // only a real I/O failure (access denied, in use) lands here.
-    throw worktreeRefusal('workspace-admission-unreadable');
-  }
-  return !Object.values(entries).some(
-    (record) => typeof record?.path === 'string' && samePath(record.path, layout.topLevel)
-  );
-}
+// The longest a synchronous caller (or the exit) waits for the admission
+// thread, the requests queued ahead of it included: each is bounded by the
+// ledger lock timeout (file-lock.mjs, MIXDOG_LOCK_TIMEOUT_MS) and the atomic
+// writes' rename retries. A chosen ceiling, not a measurement: reaching it is
+// the typed `outcome: 'unknown'` refusal, and MIXDOG_ADMISSION_SYNC_TIMEOUT_MS
+// sets it.
+const syncTimeoutMs = () => envMs('MIXDOG_ADMISSION_SYNC_TIMEOUT_MS', 60_000);
 
-/*
- * The admission ledger lists every turn, command and management lease of a
- * repository. It is kept in two copies with the same content in the Git
- * common directory: `mixdog-workspace-admission.json` and its `.management`
- * mirror. A grant returns its release only once both copies hold it, and a
- * release is forgotten only once both copies dropped it, so damage to either
- * copy alone never loses an acknowledged lease. `recoveredAt` marks a ledger
- * that may be missing leases because no complete copy survived: readers still
- * run, management refuses, and only a quiescent reset that removes both
- * copies clears it (docs/git-github-integration.md). Time, healing and
- * releases never do.
- */
-const VERSION = 2;
-const isLease = (lease) =>
-  !!lease &&
-  ['turn', 'command', 'management'].includes(lease.kind) &&
-  typeof lease.token === 'string' &&
-  Number.isSafeInteger(lease.pid) &&
-  lease.pid > 0 &&
-  typeof lease.path === 'string' &&
-  isAbsolute(lease.path);
-// Only a pid PROVEN dead (ESRCH) drops its lease, whatever its kind; an
-// unprobeable pid still counts as running. A live runtime keeps a command
-// whose tree it cannot verify reserved under its own (live) pid until the
-// tree is confirmed gone, so a lease that outlives every pid belongs to a
-// restarted runtime that can no longer release it.
-const aliveLease = (lease) => isPidAliveOrUnknown(lease.pid);
-// A management hold shares one token across its folders, so a lease is
-// identified by token and path.
-const leaseKey = (lease) => `${lease.token}\0${lease.path}`;
-const unverifiable = () => worktreeRefusal('workspace-admission-unreadable');
-const copyPaths = (commonDir) => {
-  const primary = join(commonDir, FILE);
-  return [primary, `${primary}.management`];
-};
-const envMs = (name, fallback) => {
-  const value = Number(process.env[name]);
-  return Number.isFinite(value) && value > 0 ? value : fallback;
-};
-const healIntervalMs = () => envMs('MIXDOG_ADMISSION_HEAL_MS', 2_000);
+// `outcome: 'unknown'`: the request was posted and may have landed.
+const unknownOutcome = (details = {}) =>
+  worktreeRefusal('workspace-admission-unreadable', { ...details, outcome: 'unknown' });
+const stoppedError = (posted) =>
+  posted
+    ? unknownOutcome({ admission: 'stopped' })
+    : worktreeRefusal('workspace-admission-unreadable', { admission: 'stopped' });
 
-// The leases this process holds, put back into a ledger that lost them, and
-// the tokens it released or failed to grant whose removal from both copies is
-// not confirmed yet (token -> common dir), retried until it is.
-const held = new Map();
-const pending = new Map();
-let healTimer = null;
+let gate = null;
 
-/**
- * One copy as read under the ledger lock. A copy that cannot be read (access
- * denied, in use, a directory) or that a newer build wrote refuses everything
- * and is never written: neither may pass for an empty ledger. Anything else
- * that is not a ledger, or holds an invalid lease record, is damaged; its
- * valid records still count. A copy is complete when it accounts for every
- * acknowledged lease: intact, not uncertain, and version 2 — or the version 1
- * primary, since the version 1 mirror held management leases only.
- */
-function readCopy(path, primary) {
-  let bytes;
+function startGate() {
+  if (gate) return gate;
+  const slots = new Int32Array(new SharedArrayBuffer(SLOT.COUNT * Int32Array.BYTES_PER_ELEMENT));
+  const { port1, port2 } = new MessageChannel();
+  let worker;
   try {
-    bytes = readFileSync(path);
-  } catch (error) {
-    if (error?.code === 'ENOENT') return { path, leases: [] };
-    throw unverifiable();
+    worker = new Worker(new URL('./activity-ledger-worker.mjs', import.meta.url), {
+      env: SHARE_ENV,
+      execArgv: [],
+      workerData: {
+        slots: slots.buffer,
+        syncPort: port2,
+        // Tests only: load the fixed fault hook beside the worker (never shipped).
+        faultHook: process.env.MIXDOG_ADMISSION_TEST_FAULT_HOOK === '1',
+      },
+      transferList: [port2],
+    });
+  } catch (cause) {
+    // Nothing ran: the next request tries again.
+    throw Object.assign(worktreeRefusal('workspace-admission-unreadable', { admission: 'unavailable' }), { cause });
   }
-  let ledger = null;
-  try {
-    ledger = parseJsonText(bytes.toString('utf8'));
-  } catch {
-    // Unparseable: damaged below.
-  }
-  if (Number.isSafeInteger(ledger?.version) && ledger.version > VERSION) throw unverifiable();
-  if (![1, VERSION].includes(ledger?.version) || !Array.isArray(ledger.leases)) {
-    return { path, bytes, leases: [], damaged: true };
-  }
-  const leases = ledger.leases.filter(isLease);
-  const damaged = leases.length !== ledger.leases.length;
-  const uncertain = Object.hasOwn(ledger, 'recoveredAt');
-  const complete = !damaged && !uncertain && (ledger.version === VERSION || primary);
-  return { path, bytes, leases, damaged, uncertain, complete, recoveredAt: ledger.recoveredAt };
+  const current = { worker, slots, syncPort: port1, lastId: 0, posted: 0, waiting: new Map(), stopped: null };
+  gate = current;
+  worker.on('message', (answer) => settleAnswer(current, answer));
+  worker.on('error', (error) => stopGate(current, error));
+  worker.on('exit', (code) => stopGate(current, new Error(`exit code ${code}`)));
+  // Kept alive by outstanding asynchronous requests only (request); after the
+  // listeners, since attaching a 'message' listener refs the worker again.
+  worker.unref();
+  process.on('exit', () => drainOnExit(current));
+  return current;
 }
 
-/**
- * The ledger recovered from both copies: the union of their valid lease
- * records (one copy lacking a lease never drops it), less proven-dead pids
- * and this process's pending removals, plus the leases this process holds.
- * It stays uncertain when either copy is, and becomes so when a copy exists
- * but none is complete. Both copies missing reads as a new repository.
- */
-function recover(commonDir, copies) {
-  const own = [...held.values()].filter((entry) => entry.commonDir === commonDir).map((entry) => entry.lease);
-  const leases = new Map();
-  for (const lease of [...copies.flatMap((copy) => copy.leases), ...own]) {
-    const key = leaseKey(lease);
-    if (!leases.has(key) && pending.get(lease.token) !== commonDir && aliveLease(lease)) leases.set(key, lease);
-  }
-  const ledger = { version: VERSION, leases: [...leases.values()] };
-  const uncertain =
-    copies.some((copy) => copy.uncertain) ||
-    (copies.some((copy) => copy.bytes) && !copies.some((copy) => copy.complete));
-  if (uncertain) ledger.recoveredAt = copies.map((copy) => copy.recoveredAt).find(Number.isFinite) ?? Date.now();
-  return ledger;
+function stopGate(current, cause) {
+  if (current.stopped) return;
+  current.stopped = cause;
+  process.stderr.write(
+    `[state] the workspace admission thread stopped (${cause?.message ?? cause}); workspace activity is refused until restart\n`
+  );
+  const waiting = [...current.waiting.values()];
+  current.waiting.clear();
+  for (const entry of waiting) entry.reject(stoppedError(true));
 }
 
-/**
- * #117: the bytes of a damaged copy are copied aside as `<copy>.corrupt-<ts>`
- * before it is rewritten. If they cannot be kept, nothing is written and
- * everything refuses.
- */
-function keepDamagedAside(copies) {
-  for (const copy of copies.filter((each) => each.damaged)) {
-    const aside = quarantinePath(copy.path);
-    try {
-      writeFileAtomicSync(aside, copy.bytes);
-    } catch {
-      throw unverifiable();
-    }
-    process.stderr.write(`[state] ${copy.path} is damaged; kept as ${aside}\n`);
-  }
+function revive(error) {
+  if (error.name === 'WorktreeError') return new WorktreeError(error.code, error.message, error.details);
+  const revived = new ({ TypeError, RangeError }[error.name] ?? Error)(error.message);
+  if (error.code !== undefined) revived.code = error.code;
+  return revived;
+}
+
+function post(current, op, args, sync) {
+  current.lastId = current.lastId >= 0x3fffffff ? 1 : current.lastId + 1;
+  const id = current.lastId;
+  if (sync) Atomics.store(current.slots, SLOT.SYNC, id);
+  current.worker.postMessage({ id, op, args, sync });
+  current.posted = (current.posted + 1) | 0;
+  return id;
 }
 
-/** Writes the primary, then the mirror; a copy that already holds the ledger is left alone. */
-function publish(copies, ledger) {
-  const text = Buffer.from(`${JSON.stringify(ledger, null, 2)}\n`);
-  for (const copy of copies) {
-    if (copy.bytes?.equals(text)) continue;
-    copy.bytes = null; // Unknown until the write lands.
-    writeFileAtomicSync(copy.path, text);
-    copy.bytes = text;
+/** Posts the request at the call, so it runs after every earlier request of this process. */
+function request(op, args) {
+  let current;
+  try {
+    current = startGate();
+  } catch (error) {
+    return Promise.reject(error);
   }
+  if (current.stopped) return Promise.reject(stoppedError(false));
+  return new Promise((resolve, reject) => {
+    const id = post(current, op, args, false);
+    current.waiting.set(id, { resolve, reject });
+    if (current.waiting.size === 1) current.worker.ref();
+  });
 }
 
-function settle(tokens) {
-  for (const token of tokens) pending.delete(token);
-  syncHealTimer();
+function settleAnswer(current, { id, value, error }) {
+  const entry = current.waiting.get(id);
+  if (!entry) return;
+  current.waiting.delete(id);
+  if (!current.waiting.size) current.worker.unref();
+  if (error) entry.reject(revive(error));
+  else entry.resolve(value);
 }
 
 /**
- * Runs `update(leases, { unknown })` on the recovered ledger under the
- * primary copy's lock and publishes the result to both copies before
- * returning. `unknown`: the ledger may be missing leases. A refused update
- * still publishes the repaired ledger. A grant that cannot be published is
- * refused: its leases become pending removals and the ledger without them is
- * published again; whatever that leaves behind is withdrawn by the next
- * mutation or heal tick, which also blocks every later grant until it lands.
+ * The request answered while this thread blocks. The admission thread never
+ * waits for this one, so the wait ends with its answer, its stop, or the
+ * deadline — after which the request no longer counts as this caller's: the
+ * admission thread withdraws a grant it then completes (activity-ledger-worker).
  */
-function mutate(commonDir, update = () => {}) {
-  const paths = copyPaths(commonDir);
-  return withFileLockSync(
-    `${paths[0]}.lock`,
-    () => {
-      const copies = paths.map((path, index) => readCopy(path, index === 0));
-      keepDamagedAside(copies);
-      const withdrawn = [...pending].filter(([, dir]) => dir === commonDir).map(([token]) => token);
-      const base = recover(commonDir, copies);
-      const leases = [...base.leases];
-      let result;
-      let refusal = null;
-      try {
-        result = update(leases, { unknown: Object.hasOwn(base, 'recoveredAt') });
-      } catch (error) {
-        refusal = error;
-      }
-      const granted = refusal ? [] : leases.filter((lease) => !base.leases.includes(lease));
-      try {
-        publish(copies, refusal ? base : { ...base, leases });
-        settle(withdrawn);
-      } catch (error) {
-        process.stderr.write(`[state] ${paths[0]} could not be published (${error?.message})\n`);
-        if (refusal) throw refusal;
-        for (const lease of granted) pending.set(lease.token, commonDir);
-        if (granted.length) {
-          try {
-            publish(copies, base);
-            settle([...withdrawn, ...granted.map((lease) => lease.token)]);
-          } catch {
-            syncHealTimer();
-          }
-        }
-        throw unverifiable();
-      }
-      if (refusal) throw refusal;
-      return result;
-    },
-    { strictOwner: true }
-  );
-}
-
-// Without the lock, a cheap check that both copies are the same current
-// ledger holding every live lease this process holds there and none of the
-// tokens it is withdrawing. Repair, never proof that the ledger is complete.
-function inSync(commonDir) {
-  let ledger;
-  try {
-    const [primary, mirror] = copyPaths(commonDir).map((path) => readFileSync(path));
-    if (!primary.equals(mirror)) return false;
-    ledger = parseJsonText(primary.toString('utf8'));
-  } catch {
-    return false;
-  }
-  if (ledger?.version !== VERSION || !Array.isArray(ledger.leases)) return false;
-  const stored = new Set(ledger.leases.filter(isLease).map(leaseKey));
-  return (
-    [...held].every(([key, entry]) => entry.commonDir !== commonDir || stored.has(key) || !aliveLease(entry.lease)) &&
-    !ledger.leases.some((lease) => pending.get(lease?.token) === commonDir)
-  );
-}
-
-function healHeld() {
-  const dirs = new Set([...[...held.values()].map((entry) => entry.commonDir), ...pending.values()]);
-  for (const commonDir of dirs) {
-    if (inSync(commonDir)) continue;
-    try {
-      mutate(commonDir);
-    } catch {
-      // Retried on the next tick.
+function callSync(op, args) {
+  const current = startGate();
+  if (current.stopped) throw stoppedError(false);
+  const { slots } = current;
+  const id = post(current, op, args, true);
+  const deadline = Date.now() + syncTimeoutMs();
+  for (;;) {
+    const seen = Atomics.load(slots, SLOT.ANSWERED);
+    for (
+      let received = receiveMessageOnPort(current.syncPort);
+      received;
+      received = receiveMessageOnPort(current.syncPort)
+    ) {
+      if (received.message.id !== id) continue;
+      if (received.message.error) throw revive(received.message.error);
+      return received.message.value;
+    }
+    if (Atomics.load(slots, SLOT.STOPPED) === 1) {
+      stopGate(current, new Error('stopped while a synchronous request waited'));
+      throw stoppedError(true);
     }
+    let left = deadline - Date.now();
+    if (left <= 0) {
+      if (Atomics.compareExchange(slots, SLOT.SYNC, id, 0) === id) throw unknownOutcome();
+      // The admission thread already claimed the slot (SYNC is -id): the
+      // answer is on its way and its notify wakes this wait; 1 s only bounds
+      // a missed wake.
+      left = 1_000;
+    }
+    Atomics.wait(slots, SLOT.ANSWERED, seen, left);
   }
-  syncHealTimer();
 }
 
-function syncHealTimer() {
-  if (held.size || pending.size) {
-    healTimer ??= setInterval(healHeld, healIntervalMs());
-    healTimer.unref?.();
-  } else if (healTimer) {
-    clearInterval(healTimer);
-    healTimer = null;
+// `exit` listeners run synchronously while the admission thread still runs:
+// the requests already posted (a release made just before exiting) are let
+// finish. Not a durability mechanism — every grant was answered only once it
+// was written — and a forced termination skips it: a release then left
+// behind belongs to a dead pid, which the next reader drops.
+function drainOnExit(current) {
+  const { slots } = current;
+  const deadline = Date.now() + syncTimeoutMs();
+  for (;;) {
+    const done = Atomics.load(slots, SLOT.DONE);
+    if (done === current.posted || current.stopped || Atomics.load(slots, SLOT.STOPPED) === 1) return;
+    const left = deadline - Date.now();
+    if (left <= 0) return;
+    Atomics.wait(slots, SLOT.DONE, done, left);
   }
 }
 
-function track(commonDir, lease) {
-  held.set(leaseKey(lease), { commonDir, lease });
-  syncHealTimer();
-}
+const handled = (promise) => {
+  promise.catch(() => {});
+  return promise;
+};
 
-// Forgotten as held first, so nothing puts the lease back; its token stays
-// pending until both copies dropped it.
-function release(commonDir, token) {
+/**
+ * The release of a synchronous grant: returns once the removal was attempted
+ * (one that did not land is retried by the admission thread, as always).
+ * Throws only when the admission thread stopped.
+ */
+function syncRelease(leases) {
   let done = false;
   return () => {
-    if (done) return;
+    if (done || !leases.length) return;
     done = true;
-    for (const [key, entry] of held) if (entry.lease.token === token) held.delete(key);
-    pending.set(token, commonDir);
     try {
-      mutate(commonDir);
-    } catch {
-      // Retried by the next mutation or heal tick.
+      callSync('release', { leases });
+    } catch (error) {
+      if (error?.details?.outcome !== 'unknown' || error.details.admission === 'stopped') throw error;
+      process.stderr.write('[state] a workspace release outlasted the synchronous wait; it lands in its turn\n');
     }
-    syncHealTimer();
   };
 }
 
+/**
+ * The release of an asynchronous grant, requested at the call (so it lands
+ * before any later request of this process). Settles once the removal was
+ * attempted; rejects only when the admission thread stopped. Every call
+ * returns the same promise, which never goes unhandled.
+ */
+function asyncRelease(leases) {
+  let released = null;
+  return () => (released ??= leases.length ? handled(request('release', { leases })) : Promise.resolve());
+}
+
+function readerArgs(sessionId, cwd, { pid = process.pid, kind = 'turn' } = {}) {
+  if (!['turn', 'command'].includes(kind)) throw new TypeError('Invalid workspace reader kind.');
+  return { sessionId, cwd, pid, kind };
+}
+
 /**
  * Readers share a checkout freely. Null means a management writer currently
  * owns it; a reader in an external checkout is admitted whatever is held
  * outside that checkout, but refused by a management lease inside it. Throws
  * `workspace-admission-unreadable` when the ledger cannot be read, was
  * written by a newer build, or the grant could not be made durable in both
- * copies: no work may run unrecorded.
+ * copies: no work may run unrecorded. Blocks until answered;
+ * tryAdmitWorkspaceActivityAsync does not.
  */
-export function tryAdmitWorkspaceActivity(sessionId, cwd, { pid = process.pid, kind = 'turn' } = {}) {
-  if (!['turn', 'command'].includes(kind)) throw new TypeError('Invalid workspace reader kind.');
-  const layout = findGitLayout(cwd, { strict: true });
-  if (!layout) return () => {};
-  const external = isExternalCheckout(cwd);
-  const path = canonicalPath(cwd);
-  const token = randomUUID();
-  const lease = { kind, sessionId, pid, token, path };
-  // External is this profile's registry view: management another profile (or
-  // a registry recovered empty) published inside this very checkout still holds.
-  const checkout = canonicalPath(layout.topLevel);
-  const held = (other) => (external ? isWithin(checkout, other.path) : overlaps(other.path, path));
-  const admitted = mutate(layout.commonDir, (leases) => {
-    if (leases.some((other) => other.kind === 'management' && held(other))) return false;
-    leases.push(lease);
-    return true;
-  });
-  if (!admitted) return null;
-  track(layout.commonDir, lease);
-  return release(layout.commonDir, token);
+export function tryAdmitWorkspaceActivity(sessionId, cwd, options) {
+  const granted = callSync('admit', readerArgs(sessionId, cwd, options));
+  return granted && syncRelease(granted.leases);
+}
+
+/** tryAdmitWorkspaceActivity without blocking; its release settles once the removal was attempted. */
+export async function tryAdmitWorkspaceActivityAsync(sessionId, cwd, options) {
+  const granted = await request('admit', readerArgs(sessionId, cwd, options));
+  return granted && asyncRelease(granted.leases);
 }
 
+/** Waits (polling) until a reader is admitted; an abort registers nothing. Its release is asynchronous. */
 export async function admitWorkspaceActivity(sessionId, cwd, signal, options) {
   for (;;) {
     signal?.throwIfAborted();
-    const leave = tryAdmitWorkspaceActivity(sessionId, cwd, options);
+    const leave = await tryAdmitWorkspaceActivityAsync(sessionId, cwd, options);
     if (leave) {
       if (signal?.aborted) {
-        leave();
-        signal.throwIfAborted();
+        try {
+          await leave();
+        } finally {
+          signal.throwIfAborted();
+        }
       }
       return leave;
     }
@@ -341,46 +269,15 @@ export async function admitWorkspaceActivity(sessionId, cwd, signal, options) {
  * exclude later readers until the returned release is called. External
  * checkouts are only checked, never held. `sessionId`: the acting session,
  * whose own readers in this process do not count (its idleness is the
- * caller's check).
+ * caller's check). Blocks until answered; holdWorkspaceActivityAsync does not.
  */
 export function holdWorkspaceActivity(folders, { sessionId = null } = {}) {
-  const groups = new Map();
-  for (const folder of folders) {
-    const layout = findGitLayout(folder, { strict: true });
-    if (!layout) throw worktreeError('WORKTREE_UNSUPPORTED_REPO');
-    const paths = groups.get(layout.commonDir) ?? [];
-    paths.push({ path: canonicalPath(folder), external: isExternalCheckout(folder) });
-    groups.set(layout.commonDir, paths);
-  }
-  const releases = [];
-  try {
-    for (const [commonDir, paths] of [...groups].sort(([a], [b]) => a.localeCompare(b))) {
-      const token = randomUUID();
-      const taken = [];
-      mutate(commonDir, (leases, { unknown }) => {
-        const conflicts = leases.filter(
-          (lease) =>
-            !(sessionId && lease.sessionId === sessionId && lease.pid === process.pid) &&
-            paths.some(({ path }) => overlaps(path, lease.path))
-        );
-        if (conflicts.length) throw worktreeRefusal('folder-in-use');
-        // The ledger may be missing a live foreign lease: refused until reset.
-        if (unknown) throw unverifiable();
-        for (const { path, external } of paths) {
-          if (external) continue;
-          const lease = { kind: 'management', pid: process.pid, token, path };
-          leases.push(lease);
-          taken.push(lease);
-        }
-      });
-      for (const lease of taken) track(commonDir, lease);
-      releases.push(release(commonDir, token));
-    }
-  } catch (error) {
-    releaseAll(releases);
-    throw error;
-  }
-  return () => releaseAll(releases);
+  return syncRelease(callSync('hold', { folders: [...folders], sessionId }).leases);
+}
+
+/** holdWorkspaceActivity without blocking; its release settles once every removal was attempted. */
+export async function holdWorkspaceActivityAsync(folders, { sessionId = null } = {}) {
+  return asyncRelease((await request('hold', { folders: [...folders], sessionId })).leases);
 }
 
 /** Runs every release in reverse order even when one throws; the first failure is rethrown after all ran. */