mixdog 1.3.1 → 1.3.3

package/src/runtime/shared/user-data-guard.mjs

@@ -1,23 +1,15 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
 import {
-  copyFileSync,
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  rmSync,
-  statSync,
-  writeFileSync,
-} from 'node:fs';
-import {
-  copyFile as copyFileP,
   mkdir as mkdirP,
+  readFile as readFileP,
   readdir as readdirP,
   rm as rmP,
   stat as statP,
 } from 'node:fs/promises';
-import { basename, dirname, join, resolve } from 'node:path';
+import { basename, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { createHash, randomUUID } from 'node:crypto';
+import { writeFileAtomicAsync, writeFileAtomicSync, writeJsonAtomicSync } from './atomic-file.mjs';
 import { isPlainObject } from './object.mjs';
 import { mixdogHome } from './plugin-paths.mjs';
 
@@ -155,15 +147,27 @@ function safeReason(reason) {
   );
 }
 
-/** instanceId of this data dir's init marker; null when absent or unreadable. */
+/** instanceId of this data dir's init marker; null only when absent. */
 function readInitInstanceId(dataDir) {
   if (!dataDir) return null;
+  const path = join(dataDir, INIT_MARKER);
+  let raw;
   try {
-    const marker = JSON.parse(readFileSync(join(dataDir, INIT_MARKER), 'utf8'));
-    return typeof marker?.instanceId === 'string' && marker.instanceId ? marker.instanceId : null;
-  } catch {
-    return null;
+    raw = readFileSync(path, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
   }
+  let marker;
+  try {
+    marker = JSON.parse(raw);
+  } catch (error) {
+    throw new SyntaxError(`[user-data] invalid initialization marker at ${path}`, { cause: error });
+  }
+  if (typeof marker?.instanceId !== 'string' || !marker.instanceId) {
+    throw new SyntaxError(`[user-data] initialization marker at ${path} must have a non-empty instanceId`);
+  }
+  return marker.instanceId;
 }
 
 export function hasUserDataInitMarker(dataDir) {
@@ -379,14 +383,26 @@ function copyTree(src, dst, copied) {
     return;
   }
   if (!st.isFile()) return;
-  mkdirSync(dirname(dst), { recursive: true });
-  copyFileSync(src, dst);
+  // A copy goes through an fsynced handle: a plain copy can leave a backup that
+  // is NUL exactly when a crash makes it needed.
+  writeFileAtomicSync(dst, readFileSync(src), { mode: st.mode & 0o777 });
   copied.push(dst);
 }
 
-/** Prune one data dir's scope only; other scopes and legacy entries stay. */
+// Only a published manifest makes a backup count toward retention.
+const manifestPath = (scopeDir, name) => join(scopeDir, name, BACKUP_MANIFEST);
+
+/** Prune one data dir's scope only; other scopes, legacy entries and
+ *  unfinished reservations stay. */
 function pruneBackups(scopeDir, names, own) {
-  for (const name of backupsToPrune(names, own)) {
+  const completed = names.filter((name) => {
+    try {
+      return statSync(manifestPath(scopeDir, name)).isFile();
+    } catch {
+      return false;
+    }
+  });
+  for (const name of backupsToPrune(completed, own)) {
     try {
       rmSync(join(scopeDir, name), { recursive: true, force: true });
     } catch {}
@@ -394,22 +410,20 @@ function pruneBackups(scopeDir, names, own) {
 }
 
 /**
- * Create the data dir's init marker unless one exists; returns its instanceId
- * (null when the data dir is gone or unwritable). Never creates the data dir.
+ * Create a missing init marker; return its instanceId, or null if the data dir
+ * is gone or the missing marker cannot be created. Never creates the data dir.
+ * Read/validation failures throw; an existing marker is never replaced.
  */
 export function markUserDataInitialized(dataDir) {
   const existing = readInitInstanceId(dataDir);
   if (existing || !dataDir || !existsSync(dataDir)) return existing;
   try {
-    writeFileSync(
-      join(dataDir, INIT_MARKER),
-      `${JSON.stringify(
-        { instanceId: randomUUID(), dataDir: resolve(dataDir), createdAt: new Date().toISOString() },
-        null,
-        2
-      )}\n`,
-      // An unreadable marker is replaced; a concurrent creator's valid one wins.
-      { encoding: 'utf8', flag: existsSync(join(dataDir, INIT_MARKER)) ? 'w' : 'wx' }
+    const marker = join(dataDir, INIT_MARKER);
+    writeJsonAtomicSync(
+      marker,
+      { instanceId: randomUUID(), dataDir: resolve(dataDir), createdAt: new Date().toISOString() },
+      // Another creator may have published since the absent read; it wins.
+      { createOnly: true }
     );
   } catch {}
   return readInitInstanceId(dataDir);
@@ -427,8 +441,8 @@ export function ensureUserDataInitialized(dataDir) {
   if (!dataDir) return;
   const key = normalizeDataDir(dataDir);
   if (ensuredDataDirs.has(key)) return;
-  ensuredDataDirs.add(key);
   if (!hasUserDataInitMarker(dataDir)) backupUserData(dataDir, 'initial-snapshot');
+  ensuredDataDirs.add(key);
 }
 
 function skipBackups() {
@@ -439,15 +453,12 @@ function skipBackups() {
 // manifest goes last, so an interrupted copy is never restorable.
 function finishBackup(dataDir, backupDir, reason) {
   const instanceId = markUserDataInitialized(dataDir);
-  writeFileSync(
-    join(backupDir, BACKUP_MANIFEST),
-    `${JSON.stringify(
-      { dataDir: resolve(dataDir), instanceId, reason, createdAt: new Date().toISOString() },
-      null,
-      2
-    )}\n`,
-    'utf8'
-  );
+  writeJsonAtomicSync(join(backupDir, BACKUP_MANIFEST), {
+    dataDir: resolve(dataDir),
+    instanceId,
+    reason,
+    createdAt: new Date().toISOString(),
+  });
   restoreLookupCache.delete(normalizeDataDir(dataDir));
   legacyEvidenceCache.delete(normalizeDataDir(dataDir));
 }
@@ -461,16 +472,24 @@ export function backupUserData(dataDir, reason = 'snapshot', { dirs = [] } = {})
   const scopeDir = scopeDirFor(dataDir);
   const { backupDir, names } = reserveBackupDir(scopeDir, reason);
   const copied = [];
-  for (const rel of USER_DATA_FILES) {
-    const src = join(dataDir, rel);
-    if (existsSync(src)) copyTree(src, join(backupDir, rel), copied);
-  }
-  for (const rel of [...USER_DATA_DIRS, ...dirs]) {
-    const src = join(dataDir, rel);
-    if (existsSync(src)) copyTree(src, join(backupDir, rel), copied);
+  try {
+    for (const rel of USER_DATA_FILES) {
+      const src = join(dataDir, rel);
+      if (existsSync(src)) copyTree(src, join(backupDir, rel), copied);
+    }
+    for (const rel of [...USER_DATA_DIRS, ...dirs]) {
+      const src = join(dataDir, rel);
+      if (existsSync(src)) copyTree(src, join(backupDir, rel), copied);
+    }
+    if (copied.length > 0) finishBackup(dataDir, backupDir, reason);
+  } catch (error) {
+    // Drop only this call's reservation; a failed cleanup must not mask the cause.
+    try {
+      rmSync(backupDir, { recursive: true, force: true });
+    } catch {}
+    throw error;
   }
   if (copied.length > 0) {
-    finishBackup(dataDir, backupDir, reason);
     pruneBackups(scopeDir, names, basename(backupDir));
     if (process.env.MIXDOG_SETUP_QUIET !== '1') {
       process.stderr.write(`[user-data-backup] ${reason}: copied ${copied.length} file(s) to ${backupDir}\n`);
@@ -494,13 +513,18 @@ async function copyTreeAsync(src, dst, copied) {
     return;
   }
   if (!st.isFile()) return;
-  await mkdirP(dirname(dst), { recursive: true });
-  await copyFileP(src, dst);
+  await writeFileAtomicAsync(dst, await readFileP(src), { mode: st.mode & 0o777 });
   copied.push(dst);
 }
 
 async function pruneBackupsAsync(scopeDir, names, own) {
-  for (const name of backupsToPrune(names, own)) {
+  const completed = [];
+  for (const name of names) {
+    try {
+      if ((await statP(manifestPath(scopeDir, name))).isFile()) completed.push(name);
+    } catch {}
+  }
+  for (const name of backupsToPrune(completed, own)) {
     try {
       await rmP(join(scopeDir, name), { recursive: true, force: true });
     } catch {}
@@ -513,16 +537,23 @@ export async function backupUserDataAsync(dataDir, reason = 'snapshot') {
   const scopeDir = scopeDirFor(dataDir);
   const { backupDir, names } = await reserveBackupDirAsync(scopeDir, reason);
   const copied = [];
-  for (const rel of USER_DATA_FILES) {
-    const src = join(dataDir, rel);
-    if (existsSync(src)) await copyTreeAsync(src, join(backupDir, rel), copied);
-  }
-  for (const rel of USER_DATA_DIRS) {
-    const src = join(dataDir, rel);
-    if (existsSync(src)) await copyTreeAsync(src, join(backupDir, rel), copied);
+  try {
+    for (const rel of USER_DATA_FILES) {
+      const src = join(dataDir, rel);
+      if (existsSync(src)) await copyTreeAsync(src, join(backupDir, rel), copied);
+    }
+    for (const rel of USER_DATA_DIRS) {
+      const src = join(dataDir, rel);
+      if (existsSync(src)) await copyTreeAsync(src, join(backupDir, rel), copied);
+    }
+    if (copied.length > 0) finishBackup(dataDir, backupDir, reason);
+  } catch (error) {
+    try {
+      await rmP(backupDir, { recursive: true, force: true });
+    } catch {}
+    throw error;
   }
   if (copied.length > 0) {
-    finishBackup(dataDir, backupDir, reason);
     await pruneBackupsAsync(scopeDir, names, basename(backupDir));
     if (process.env.MIXDOG_SETUP_QUIET !== '1') {
       process.stderr.write(`[user-data-backup] ${reason}: copied ${copied.length} file(s) to ${backupDir}\n`);

package/src/runtime/shared/utf8-cut.mjs

@@ -0,0 +1,10 @@
+/**
+ * `text` without its trailing U+FFFD characters: what a byte cut through a
+ * multi-byte sequence leaves behind. A loop, not `/\uFFFD+$/`, which is
+ * quadratic on a long run of them.
+ */
+export function stripTrailingReplacementChars(text) {
+  let end = text.length;
+  while (end > 0 && text[end - 1] === '\uFFFD') end -= 1;
+  return end === text.length ? text : text.slice(0, end);
+}

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

@@ -1,13 +1,13 @@
 import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
 import { setTimeout as delay } from 'node:timers/promises';
-import { readFileSync, renameSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
-import { withFileLockSync, writeJsonAtomicSync } from '../atomic-file.mjs';
+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 { registryPath } from './registry.mjs';
+import { readRegistrySync } from './registry.mjs';
 
 const FILE = 'mixdog-workspace-admission.json';
 const overlaps = (a, b) => isWithin(a, b) || isWithin(b, a);
@@ -24,97 +24,277 @@ export function isExternalCheckout(folder) {
   if (!layout || samePath(layout.gitDir, layout.commonDir)) return false;
   let entries;
   try {
-    entries = JSON.parse(readFileSync(registryPath(), 'utf8'))?.entries ?? {};
-  } catch (error) {
-    if (error?.code !== 'ENOENT') throw worktreeRefusal('workspace-admission-unreadable');
-    entries = {};
+    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 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);
+
+// 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;
+
 /**
- * Reads the ledger under its lock. A missing ledger is empty. A ledger that is
- * not JSON is a torn write (a crash or power loss after the rename committed
- * the file's size but not its bytes leaves it NUL-filled on NTFS): nothing in
- * it can be recovered and every lease it held belongs to a process that died
- * with it, so refusing forever would only lock the project out. It is moved
- * aside as `<FILE>.corrupt-<time>` for inspection and admission starts over
- * empty. A ledger that cannot be read at all (permissions, I/O, a directory in
- * its place) is not an empty one and still refuses, as does one that moves
- * aside unsuccessfully: an unreadable file is never overwritten.
+ * 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 readLedger(path) {
-  let text;
+function readCopy(path, primary) {
+  let bytes;
   try {
-    text = readFileSync(path, 'utf8');
+    bytes = readFileSync(path);
   } catch (error) {
-    if (error?.code === 'ENOENT') return { version: 1, leases: [] };
-    throw worktreeRefusal('workspace-admission-unreadable');
+    if (error?.code === 'ENOENT') return { path, leases: [] };
+    throw unverifiable();
   }
+  let ledger = null;
   try {
-    return JSON.parse(text);
+    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 };
+}
+
+/**
+ * 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;
+}
+
+/**
+ * #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 {
-      renameSync(path, `${path}.corrupt-${Date.now()}`);
+      writeFileAtomicSync(aside, copy.bytes);
     } catch {
-      throw worktreeRefusal('workspace-admission-unreadable');
+      throw unverifiable();
     }
-    return { version: 1, leases: [] };
+    process.stderr.write(`[state] ${copy.path} is damaged; kept as ${aside}\n`);
   }
 }
 
-function mutate(commonDir, update) {
-  const path = join(commonDir, FILE);
+/** 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;
+  }
+}
+
+function settle(tokens) {
+  for (const token of tokens) pending.delete(token);
+  syncHealTimer();
+}
+
+/**
+ * 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.
+ */
+function mutate(commonDir, update = () => {}) {
+  const paths = copyPaths(commonDir);
   return withFileLockSync(
-    `${path}.lock`,
+    `${paths[0]}.lock`,
     () => {
-      const state = readLedger(path);
-      if (
-        state?.version !== 1 ||
-        !Array.isArray(state.leases) ||
-        state.leases.some(
-          (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)
-        )
-      ) {
-        throw worktreeRefusal('workspace-admission-unreadable');
+      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();
       }
-      // 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.
-      state.leases = state.leases.filter((lease) => isPidAliveOrUnknown(lease.pid));
-      const result = update(state.leases);
-      writeJsonAtomicSync(path, state, { lock: false });
+      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.
+    }
+  }
+  syncHealTimer();
+}
+
+function syncHealTimer() {
+  if (held.size || pending.size) {
+    healTimer ??= setInterval(healHeld, healIntervalMs());
+    healTimer.unref?.();
+  } else if (healTimer) {
+    clearInterval(healTimer);
+    healTimer = null;
+  }
+}
+
+function track(commonDir, lease) {
+  held.set(leaseKey(lease), { commonDir, lease });
+  syncHealTimer();
+}
+
+// Forgotten as held first, so nothing puts the lease back; its token stays
+// pending until both copies dropped it.
 function release(commonDir, token) {
   let done = false;
   return () => {
     if (done) return;
-    mutate(commonDir, (leases) => {
-      for (let i = leases.length - 1; i >= 0; i--) if (leases[i].token === token) leases.splice(i, 1);
-    });
     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.
+    }
+    syncHealTimer();
   };
 }
 
 /**
  * Readers share a checkout freely. Null means a management writer currently
- * owns it; a reader in an external checkout is never held back.
+ * owns it; a reader in an external checkout is never held back. 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.
  */
 export function tryAdmitWorkspaceActivity(sessionId, cwd, { pid = process.pid, kind = 'turn' } = {}) {
   if (!['turn', 'command'].includes(kind)) throw new TypeError('Invalid workspace reader kind.');
@@ -123,12 +303,15 @@ export function tryAdmitWorkspaceActivity(sessionId, cwd, { pid = process.pid, k
   const external = isExternalCheckout(cwd);
   const path = canonicalPath(cwd);
   const token = randomUUID();
+  const lease = { kind, sessionId, pid, token, path };
   const admitted = mutate(layout.commonDir, (leases) => {
-    if (!external && leases.some((lease) => lease.kind === 'management' && overlaps(lease.path, path))) return false;
-    leases.push({ kind, sessionId, pid, token, path });
+    if (!external && leases.some((other) => other.kind === 'management' && overlaps(other.path, path))) return false;
+    leases.push(lease);
     return true;
   });
-  return admitted ? release(layout.commonDir, token) : null;
+  if (!admitted) return null;
+  track(layout.commonDir, lease);
+  return release(layout.commonDir, token);
 }
 
 export async function admitWorkspaceActivity(sessionId, cwd, signal, options) {
@@ -166,17 +349,24 @@ export function holdWorkspaceActivity(folders, { sessionId = null } = {}) {
   try {
     for (const [commonDir, paths] of [...groups].sort(([a], [b]) => a.localeCompare(b))) {
       const token = randomUUID();
-      mutate(commonDir, (leases) => {
+      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) leases.push({ kind: 'management', pid: process.pid, token, path });
+          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) {