@worca/app 1.2.0 → 1.3.0-rc.2

package/src/core/memory-sync.mjs

@@ -0,0 +1,300 @@
+// The per-run memory MOUNT (agent-memory-design.md §4.1, amendment A1) and the
+// hash-baselined SYNC-BACK (§5). Pure over injected paths: `root` is the store
+// (memory-store.mjs' layout), `mount` is `<runCwd>/.claude/rules/worca` (memoryMountPath). No DB, no
+// orchestrator state, no settings reads — the harness passes caps and paths.
+import { mkdir, rm, cp, readFile, writeFile, stat, rename, unlink, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import {
+  GLOBAL_SCOPE, projectScope, scopeDir, listMemory, listMemoryDir, hashText,
+  repairMemoryFile, parseMemoryFile, writeMemory, removeMemory, snapshotScope, MemoryError,
+} from './memory-store.mjs';
+import { MEMORY_DEFRAG_WORKFLOW_ID } from './graph/builtin-workflows.mjs';
+
+/**
+ * Where the mount lives INSIDE a run's cwd (native-rules revision, 2026-09-13): Claude Code
+ * discovers `<cwd>/.claude/rules/**` recursively, honours `paths:` frontmatter (comma-separated
+ * string included) and hands the files to Task sub-agents — probed on claude 2.1.270 from a git
+ * worktree cwd and from a non-git run root. `worca/` namespaces the mount away from a project's
+ * own committed rules. Forward slashes on purpose: the string is also the git pathspec of the
+ * §8.8 exclusion set (`:(exclude).claude/rules/worca`).
+ */
+export const MEMORY_RULES_REL = '.claude/rules/worca';
+/** `<cwd>/.claude/rules/worca` with the platform separator. */
+export function memoryMountPath(cwd) { return join(cwd, ...MEMORY_RULES_REL.split('/')); }
+/**
+ * The §8.8 injected-path record of the mount. `kind: 'memory'` is EXCLUDED from every commit,
+ * intent-to-add staging and result diff (run-harness `_excludePathspecs`), REMOVED at teardown
+ * (`removeInjectedPaths`) and NEVER rescued (`rescueModifiedMounts` handles the skill/claudeMd
+ * kinds only — sync-back is this mount's rescue). `source: null`: there is no one source file.
+ */
+export const MEMORY_INJECTED_ENTRY = Object.freeze({ path: MEMORY_RULES_REL, kind: 'memory', source: null });
+
+export const baselineKey = (rel, name) => `${rel}/${name}.md`;
+const byKey = (a, b) => (a.projectKey < b.projectKey ? -1 : a.projectKey > b.projectKey ? 1 : 0);
+
+/**
+ * Which store scopes a run mounts, and under which mount-relative dir.
+ * Single run: global/ + project/ (D6). Workspace run: global/ + projects/<key>/ per
+ * member, sorted by projectKey (the orchestrator's member order). `memoryScope`
+ * (P2's defrag option) narrows to exactly one dir; 'project' needs a single-project run.
+ */
+export function mountDirs({ members = [], isWorkspace = false, memoryScope = null } = {}) {
+  const out = [{ scope: GLOBAL_SCOPE, rel: 'global', label: 'Global' }];
+  if (isWorkspace) {
+    for (const m of [...members].sort(byKey)) {
+      out.push({ scope: projectScope(m.projectKey), rel: `projects/${m.projectKey}`, label: `Project ${m.projectName || m.projectKey}` });
+    }
+  } else if (members[0]) {
+    const m = members[0];
+    out.push({ scope: projectScope(m.projectKey), rel: 'project', label: `Project ${m.projectName || m.projectKey}` });
+  }
+  if (memoryScope === 'global') return out.filter((d) => d.rel === 'global');
+  if (memoryScope === 'project') {
+    if (isWorkspace) throw new Error('memoryScope "project" needs a single-project run');
+    return out.filter((d) => d.rel === 'project');
+  }
+  return out;
+}
+
+export const MEMORY_SCOPES = Object.freeze(['global', 'project']);
+
+/**
+ * The run-option gate (agent-memory-design.md §7.3), shared by POST /api/run, the CLI, Ask's
+ * proposal validator and the harness constructor: null when the combination is legal, else the
+ * reason — an HTTP 400 / CLI usage error / proposal error, verbatim. `memoryScope` is only ever
+ * legal with the Memory defragment workflow, that workflow always needs it, and a defragment
+ * run is a single-project run (the mount is one scope dir: mountDirs).
+ */
+export function validateMemoryScope({ workflowId, memoryScope, isWorkspace = false } = {}) {
+  const has = memoryScope !== undefined && memoryScope !== null && memoryScope !== '';
+  const defrag = workflowId === MEMORY_DEFRAG_WORKFLOW_ID;
+  if (has && !MEMORY_SCOPES.includes(memoryScope)) return 'memoryScope must be "global" or "project"';
+  if (has && !defrag) return `memoryScope is only valid with the Memory defragment workflow (${MEMORY_DEFRAG_WORKFLOW_ID})`;
+  if (defrag && !has) return 'the Memory defragment workflow needs memoryScope ("global" or "project")';
+  if (has && isWorkspace) return 'a memory defragment run targets one project, not a workspace';
+  return null;
+}
+
+/**
+ * (Re)create the mount from the store — the rm is scoped to the `worca/` subtree, so a project's
+ * own `.claude/rules/*.md` beside it is never touched: every dir exists even when empty (the
+ * pointer block tells the agent it is writable), stale content from a previous segment
+ * is removed first (the caller syncs back BEFORE remounting on resume), files are
+ * COPIED (never linked). Returns the baseline `{ '<rel>/<name>.md': sha1 }`.
+ * `gitIgnore: true` writes `<mount>/.gitignore` = `*` FIRST (before any file is copied, so a
+ * mount that fails half way never leaves files without their ignore — an ignore without files
+ * is harmless, bare files inside a checkout are not): the mount then sits inside a checkout
+ * invisibly — an agent's own `git add -A`, a staging pre-commit hook and the reviewer's
+ * `git status` all skip it. Not a memory file: `listMemoryDir` lists `*.md` only, so sync-back
+ * neither syncs it nor reads it as a deletion. The §8.8 `:(exclude)` pathspec stays as defence
+ * in depth (a hand-deleted sentinel, an older git).
+ */
+export async function mountMemory({ root, mount, dirs, onError, gitIgnore = false }) {
+  // (Windows: an indexer/AV may hold a handle for a moment.)
+  await rm(mount, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+  await mkdir(mount, { recursive: true });
+  if (gitIgnore) await writeFile(join(mount, '.gitignore'), '*\n', 'utf8');
+  const baseline = {};
+  let files = 0;
+  for (const d of dirs) {
+    const dest = join(mount, d.rel);
+    await mkdir(dest, { recursive: true });
+    for (const e of await listMemory(root, d.scope, { onError })) {
+      await cp(join(scopeDir(root, d.scope), `${e.name}.md`), join(dest, `${e.name}.md`));
+      baseline[baselineKey(d.rel, e.name)] = e.hash;
+      files++;
+    }
+  }
+  return { mount, dirs, baseline, files };
+}
+
+/**
+ * The NON-destructive twin of mountMemory, for a mount a process may be READING while we refresh
+ * it (the Ask chat's --add-dir base, memory-deps.mjs refreshAskMemoryMount): every store file is
+ * written atomically by name (temp + rename), files no longer in the store are unlinked, dirs are
+ * created and never removed. No `.gitignore` sentinel — an Ask mount is not inside a checkout.
+ * No baseline — nothing syncs back from an Ask mount.
+ * Failure is PER FILE: a target that cannot be written keeps its previous copy (a stale rule still
+ * loads; a file that never landed is simply absent this turn), its temp is unlinked and its name is
+ * reported. Returns `{ files, failed }` where `files` is what the mount SHOULD hold (the store
+ * entries of the scope set) and `failed` the names that could not be refreshed this call.
+ */
+export async function refreshMount({ root, mount, dirs, onError }) {
+  let files = 0;
+  const failed = [];
+  for (const d of dirs) {
+    const dest = join(mount, d.rel);
+    await mkdir(dest, { recursive: true });
+    const entries = await listMemory(root, d.scope, { onError });
+    // `keep` is built from what we actually WROTE or deliberately kept — an entry that vanished
+    // between the listing and the read is not in it, so its stale mount copy is swept THIS call.
+    const keep = new Set();
+    for (const e of entries) {
+      const text = await readFile(join(scopeDir(root, d.scope), `${e.name}.md`), 'utf8').catch(() => null);
+      if (text === null) continue;                                    // vanished between the listing and the read
+      files++;
+      const target = join(dest, `${e.name}.md`);
+      keep.add(`${e.name}.md`);                                       // written below, or kept as the previous copy on failure
+      const tmp = `${target}.tmp-${process.pid}-${Date.now()}`;
+      try {
+        await writeFile(tmp, text, 'utf8');
+        await rename(tmp, target);
+      } catch (err) {
+        await unlink(tmp).catch(() => {});
+        failed.push(e.name);
+        onError?.(target, err);
+      }
+    }
+    // Stale files go. A name of THIS shape (`x.md.tmp-<pid>-<ms>`) is another writer's in-flight rename,
+    // never a memory file (those end in `.md`) — a memory file named `a.tmp-b` lands as `a.tmp-b.md` and is swept.
+    for (const f of await readdir(dest).catch(() => [])) {
+      if (keep.has(f) || /\.md\.tmp-\d+-\d+$/.test(f)) continue;
+      await unlink(join(dest, f)).catch(() => {});
+    }
+  }
+  return { files, failed };
+}
+
+// ── one writer per store root per process ────────────────────────────────────
+// A run's parallel executions (scheduler maxParallel, composite slices) and several
+// live runs hosted by one server process all sync into the same store. A promise
+// chain per root is enough for a single-user tool (no lock file); it keeps two
+// syncs from diffing against the same baseline and writing the same file twice.
+const storeQueues = new Map();   // root -> settled tail
+export function withStoreLock(root, fn) {
+  const tail = storeQueues.get(root) || Promise.resolve();
+  const run = tail.then(fn);
+  const settled = run.catch(() => {});
+  storeQueues.set(root, settled);
+  settled.then(() => { if (storeQueues.get(root) === settled) storeQueues.delete(root); });
+  return run;
+}
+
+const REJECTED_INVALID = 'rejected:invalid';
+/** Keep `isHash`: `storeHashOf` is defined in terms of it and is its only remaining caller. */
+const isHash = (v) => typeof v === 'string' && !v.startsWith('rejected:');
+/** The store hash a baseline value still vouches for: a plain hash, or the third segment of a
+ *  `rejected:<mountHash>:<storeHash>` marker (the store held the file when its overwrite was
+ *  refused, and that copy is what a later deletion may mirror — spec §5 step 5). null for
+ *  `rejected:invalid` and for P1's two-part `rejected:<mountHash>` (the store never vouched). */
+const storeHashOf = (v) => (isHash(v) ? v : ((typeof v === 'string' && v.split(':')[2]) || null));
+
+/** Totals over a list of Change entries — one shape for results.json and the History detail. */
+export function memoryTotals(changes) {
+  const totals = { added: 0, modified: 0, deleted: 0, rejected: 0 };
+  for (const c of Array.isArray(changes) ? changes : []) for (const k of Object.keys(totals)) totals[k] += Array.isArray(c[k]) ? c[k].length : 0;
+  return totals;
+}
+
+/**
+ * Sync the mount back into the store (§5 steps 1–6), serialised per store root. Per mount dir:
+ *  - new/changed file: name-repair warning, scope-full / hard-cap / case-twin checks, ONE
+ *    snapshot per scope per sync (taken lazily before the first accepted write), store write
+ *    via writeMemory; the repaired text is written back into the mount so both sides carry
+ *    one hash. Added vs modified is decided by the STORE, never by the baseline.
+ *  - store changed since baseline AND mount changed: the run wins (the store's version is
+ *    in the snapshot) — warned by name.
+ *  - deleted in the mount: removed from the store only when the store still matches the
+ *    baseline; otherwise kept + warned. A key whose last write was rejected is dropped with
+ *    a warning (the store never took that text).
+ *  - a file the store refuses (invalid name, cap, twin, scope full, or a store-side fs
+ *    error) stays in the mount, is baselined as `rejected:<mountHash>[:<storeHash>]` (the store
+ *    hash rides along when the store held the file, so a later mount deletion of that file
+ *    still mirrors; reported ONCE per text, re-tried whenever the text — or the cap — changes)
+ *    and never reaches the store.
+ *  - a mount file the run EMPTIED is a DELETION request (amendment B19): the memory tool set
+ *    has no unlink, and no legitimate memory file is empty (every writer renders a fence), so
+ *    the key is handed to the deletion pass above. A NEW empty file is simply ignored; this
+ *    arm runs BEFORE the scope-full pre-check, so a full scope never turns it into a rejection.
+ *  - a mount file that cannot be READ is skipped this sync with its baseline untouched.
+ * Never throws for one file's sake; a listing error is reported through `onError`.
+ */
+export function syncBack(o) { return withStoreLock(o.root, () => syncBackUnlocked(o)); }
+
+async function syncBackUnlocked({ root, mount, dirs, baseline, source, now, caps, onWarn, onError }) {
+  const next = { ...baseline };
+  const added = [], modified = [], deleted = [], rejected = [];
+  const warn = (t) => { if (typeof onWarn === 'function') onWarn(t); };
+  for (const d of dirs) {
+    const dir = join(mount, d.rel);
+    // A scope dir that is GONE is never an agent deleting every file in it (agents
+    // delete files, not the mount): a remount that failed after its rm, or a ledger
+    // older than the mount. Skip it with its baseline untouched — never mirror deletions.
+    const present = await stat(dir).then((s) => s.isDirectory(), () => false);
+    if (!present) { warn(`memory: mount dir ${d.rel} is missing — skipped this sync (nothing deleted)`); continue; }
+    const junk = [];
+    const current = await listMemoryDir(dir, { onError: (p, err) => { if (err?.code === 'ENAME') junk.push(p); else onError?.(p, err); } });
+    const seen = new Set();
+    for (const p of junk) {
+      const name = p.split(/[\\/]/).pop().replace(/\.md$/i, '');
+      const key = baselineKey(d.rel, name);
+      seen.add(key);                                                        // never reaches the deletion pass
+      if (baseline[key] !== REJECTED_INVALID) rejected.push({ scope: d.rel, name, reason: 'invalid name (letters, digits, ".", "_", "-" only; no leading or trailing dot; not a Windows device name)' });
+      next[key] = REJECTED_INVALID;
+    }
+    const store = new Map((await listMemory(root, d.scope, { onError })).map((e) => [e.name, e.hash]));
+    let snapped = false;
+    const snapshotOnce = async () => { if (!snapped) { snapped = true; await snapshotScope(root, d.scope, { source, now }); } };
+    for (const e of current) {
+      const key = baselineKey(d.rel, e.name);
+      seen.add(key);
+      if (next[key] === e.hash) continue;                                     // unchanged since the last sync
+      const inStore = store.has(e.name);
+      // The marker keeps the STORE hash (when there is one) so the same text is not re-reported
+      // on the next sync (the marker must be stable) and a later mount deletion can still tell
+      // whether the store copy is the one this run mounted.
+      const storeHash = storeHashOf(baseline[key]);
+      const marker = `rejected:${e.hash}${storeHash ? `:${storeHash}` : ''}`;
+      const reject = (reason) => { if (baseline[key] !== marker) rejected.push({ scope: d.rel, name: e.name, reason }); next[key] = marker; };
+      let text;
+      try { text = await readFile(join(dir, `${e.name}.md`), 'utf8'); }
+      catch (err) {
+        if (err?.code === 'ENOENT' || err?.code === 'ENOTDIR') continue;     // vanished between the listing and the read
+        warn(`memory: cannot read ${key}: ${err?.code || err?.message || err} — skipped this sync`); continue;
+      }
+      // B19: a mount file the agent EMPTIED is a deletion request — the memory tool set has
+      // no unlink (Write/Edit only), and no legitimate memory file is empty (every writer
+      // renders a fence). Hand the key to the deletion pass: it mirrors the removal only
+      // when the store copy is unchanged since the mount (spec §5 step 5), else keeps + warns.
+      // A NEW empty file is simply ignored (the deletion pass sees no baseline for it).
+      if (!text.trim()) { seen.delete(key); continue; }
+      // The scope-full pre-check comes AFTER the read and the B19 arm: a file the run EMPTIED is a
+      // deletion request, never a new file, so a full scope must not turn it into a rejection.
+      if (!inStore && store.size >= (caps?.maxFilesPerScope ?? Infinity)) { reject(`scope is full (${caps.maxFilesPerScope} files)`); continue; }
+      const declared = parseMemoryFile(text).meta.name;
+      if (declared && declared !== e.name) warn(`memory: ${key} declares name "${declared}" — repaired to the filename stem "${e.name}"`);
+      if (inStore && storeHash && store.get(e.name) !== storeHash) {
+        warn(`memory: ${key} changed in the store since this run mounted it — the run's version wins (the store's version is kept in .history)`);
+      }
+      try {
+        await writeMemory(root, d.scope, e.name, text, { source, now, caps, snapshot: snapshotOnce });
+        const repaired = repairMemoryFile(text, { name: e.name, source, now, hookMaxChars: caps?.hookMaxChars });
+        if (repaired.changed) await writeFile(join(dir, `${e.name}.md`), repaired.text, 'utf8');
+        const h = hashText(repaired.text);
+        next[key] = h;
+        store.set(e.name, h);
+        (inStore ? modified : added).push({ scope: d.rel, name: e.name });
+      } catch (err) {
+        reject(err instanceof MemoryError ? err.message.replace(/^memory: /, '') : `could not write to the store (${err?.code || err?.name || 'error'})`);
+      }
+    }
+    for (const key of Object.keys(baseline)) {
+      if (!key.startsWith(`${d.rel}/`) || seen.has(key)) continue;
+      const name = key.slice(d.rel.length + 1).replace(/\.md$/, '');
+      if (!store.has(name)) { delete next[key]; continue; }                   // already gone from the store (or never accepted)
+      const storeHash = storeHashOf(baseline[key]);
+      if (storeHash === null) {                                               // the store never vouched for this key (P1 marker / invalid name)
+        warn(`memory: ${key} was deleted by the run after a rejected write — the store's version is kept`);
+        delete next[key]; continue;
+      }
+      if (store.get(name) !== storeHash) {
+        warn(`memory: ${key} was deleted by the run but changed in the store since this run mounted it — kept`);
+        delete next[key]; continue;
+      }
+      await removeMemory(root, d.scope, name, { source, now, snapshot: snapshotOnce });
+      delete next[key];
+      deleted.push({ scope: d.rel, name });
+    }
+  }
+  return { baseline: next, added, modified, deleted, rejected, total: added.length + modified.length + deleted.length };
+}

package/src/core/metrics/ledger.mjs

@@ -0,0 +1,47 @@
+// src/core/metrics/ledger.mjs
+// Per-run team-metrics status for the History header (§4.11): pending | recorded | skipped.
+import { readFileSync, writeFileSync, renameSync, mkdirSync, readdirSync, statSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { worcaHome } from '../projects.mjs';
+
+const RUN_ID_RE = /^[A-Za-z0-9._-]{1,64}$/;
+
+export function ledgerFile(runId) {
+  if (!RUN_ID_RE.test(String(runId))) throw new RangeError(`bad run id: ${runId}`);
+  return join(worcaHome(), 'metrics', 'ledger', `${runId}.json`);
+}
+
+export function writeRunLedger(runId, entry) {
+  const file = ledgerFile(runId);
+  mkdirSync(join(file, '..'), { recursive: true });
+  const tmp = `${file}.${randomBytes(4).toString('hex')}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ ...entry, at: new Date().toISOString() }) + '\n', 'utf8');
+  renameSync(tmp, file);
+}
+
+/** @returns {{state:'recorded'|'pending'|'skipped'|'not-enabled', slug?:string, reason?:string, detail?:string}} */
+export function readRunLedger(runId) {
+  try {
+    const v = JSON.parse(readFileSync(ledgerFile(runId), 'utf8'));
+    if (v && ['recorded', 'pending', 'skipped'].includes(v.state)) return v;
+  } catch { /* absent or unreadable */ }
+  return { state: 'not-enabled' };
+}
+
+export const LEDGER_RETENTION_MS = 180 * 24 * 60 * 60_000;
+
+/** One file per run, forever, is a leak (§4.11 only needs the History header). Drop old entries. */
+export function sweepRunLedger({ now = Date.now(), maxAgeMs = LEDGER_RETENTION_MS } = {}) {
+  const dir = join(worcaHome(), 'metrics', 'ledger');
+  let names;
+  try { names = readdirSync(dir); } catch { return 0; }
+  let dropped = 0;
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue;
+    try {
+      if (now - statSync(join(dir, name)).mtimeMs > maxAgeMs) { rmSync(join(dir, name), { force: true }); dropped += 1; }
+    } catch { /* raced with another sweep */ }
+  }
+  return dropped;
+}

package/src/core/metrics/lock.mjs

@@ -0,0 +1,117 @@
+// src/core/metrics/lock.mjs
+// Cross-process advisory lock: O_EXCL create of a lock file holding {pid, token, at}. The CLI
+// and the UI server may both finish runs and flush the same slug (§4.5).
+// - The holder HEARTBEATS `at` while it holds the lock, so a long flush (5 × fetch+push) is
+//   never mistaken for a stale lock, and a reused pid cannot pin a dead lock forever.
+// - Stale = holder pid is dead, or the heartbeat is older than `staleMs`.
+// - Breaking a stale lock goes through a `.break` mutex and re-checks the observed content,
+//   so two waiters can never both delete-and-recreate (the second would delete a live lock).
+// - Release removes the file only if it still carries our token.
+//
+// Two honest limits (decision 29):
+// (a) `acquireLock` does `mkdir(dirname(file), { recursive: true })` unconditionally, and a
+//     caller may take this lock before any record exists in the directory it creates — so an
+//     enabled project can end up with an empty outbox directory. This is deliberate; do not
+//     "fix" it by skipping the mkdir or deferring it.
+// (b) `breakStale`'s content re-check is NOT atomic: between reading the observed content and
+//     `rm`ing the file, a live holder can heartbeat and have its lock deleted out from under it.
+//     The `.break` mutex only removes breaker-vs-breaker races, not holder-vs-breaker; the
+//     window is sub-millisecond and only reachable after `staleMs` (2 min) of apparent silence
+//     from a live process. Do not attempt to close this window.
+import { open, readFile, writeFile, rm, stat, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+export const LOCK_STALE_MS = 2 * 60_000;
+export const LOCK_HEARTBEAT_MS = 20_000;
+const BREAK_STALE_MS = 30_000;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+
+/** @returns {Promise<{stale:boolean, raw:string|null}>} */
+async function inspect(file, staleMs) {
+  let raw;
+  try { raw = await readFile(file, 'utf8'); } catch { return { stale: false, raw: null } }
+  try {
+    const { pid, at } = JSON.parse(raw);
+    if (Number.isInteger(pid) && pid !== process.pid && !pidAlive(pid)) return { stale: true, raw };
+    return { stale: Date.now() - Date.parse(at) > staleMs, raw };
+  } catch {
+    // Unparsable: possibly mid-write by its creator — judge by mtime only.
+    try { return { stale: Date.now() - (await stat(file)).mtimeMs > staleMs, raw }; } catch { return { stale: false, raw } }
+  }
+}
+
+/** @returns {Promise<boolean>} true when this caller did the break (retry at once), false when someone else holds `.break` (poll). */
+async function breakStale(file, observed) {
+  const brk = `${file}.break`;
+  let fh;
+  try { fh = await open(brk, 'wx'); } catch (e) {
+    if (e.code !== 'EEXIST') throw e;
+    const st = await stat(brk).catch(() => null);
+    if (st && Date.now() - st.mtimeMs > BREAK_STALE_MS) await rm(brk, { force: true });
+    return false; // someone else is breaking it; the caller sleeps and polls again
+  }
+  try {
+    if ((await readFile(file, 'utf8').catch(() => null)) === observed) await rm(file, { force: true });
+  } finally {
+    await fh.close();
+    await rm(brk, { force: true });
+  }
+  return true;
+}
+
+/** @returns {Promise<() => Promise<void>>} release function (idempotent) */
+export async function acquireLock(file, { staleMs = LOCK_STALE_MS, heartbeatMs = LOCK_HEARTBEAT_MS, timeoutMs = 120_000, pollMs = 50 } = {}) {
+  await mkdir(dirname(file), { recursive: true });
+  const deadline = Date.now() + timeoutMs;
+  const token = randomBytes(8).toString('hex');
+  const body = () => JSON.stringify({ pid: process.pid, token, at: new Date().toISOString() });
+  for (;;) {
+    try {
+      const fh = await open(file, 'wx');
+      await fh.writeFile(body());
+      await fh.close();
+      const ours = async () => {
+        try { return JSON.parse(await readFile(file, 'utf8')).token === token; } catch { return false; }
+      };
+      let released = false;
+      let beating = null;
+      // One heartbeat at a time, and release() awaits the in-flight one: otherwise a write that
+      // finishes after release()'s rm recreates the lock with a live pid and pins the slug for
+      // LOCK_STALE_MS (reproduced 11/400 with heartbeatMs:1).
+      const beat = setInterval(() => {
+        if (released || beating) return;
+        beating = ours()
+          .then((y) => (y && !released ? writeFile(file, body()) : null))
+          .catch(() => {})
+          .finally(() => { beating = null; });
+      }, heartbeatMs);
+      beat.unref?.();
+      return async () => {
+        if (released) return;
+        released = true;
+        clearInterval(beat);
+        if (beating) await beating;
+        if (await ours()) await rm(file, { force: true });
+      };
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      const { stale, raw } = await inspect(file, staleMs);
+      if (stale && raw != null && await breakStale(file, raw)) continue;
+      if (Date.now() > deadline) {
+        throw Object.assign(new Error(`team metrics lock is busy: ${file}`), { code: 'LOCK_TIMEOUT' });
+      }
+      await sleep(pollMs + Math.floor(Math.random() * pollMs));
+    }
+  }
+}
+
+export async function withLock(file, fn, opts) {
+  const release = await acquireLock(file, opts);
+  try { return await fn(); } finally { await release(); }
+}