agents-can-communicate 0.1.0

package/node_modules/@agents-can-communicate/storage-filesystem/src/recovery.mjs

@@ -0,0 +1,114 @@
+import path from "node:path";
+
+import { AccError, EXIT, validateRecord } from "@agents-can-communicate/protocol";
+
+import { listDirectoryEntries, listJsonFiles, readJsonIfPresent } from "./atomic-json.mjs";
+import { readStoreIdentity } from "./identity.mjs";
+import { readOpenJournals, rollForward } from "./journal.mjs";
+import { assertEventBinding, assertStateBinding } from "./record-id.mjs";
+import { storePaths } from "./store.mjs";
+import { withWriterMutex } from "./writer-mutex.mjs";
+
+/** @typedef {{ healthy: boolean, repaired: string[], blocked: string[],
+ * corrupt: string[] }} RepairReport */
+
+const report = ({ repaired = [], blocked = [], corrupt = [] }) => ({
+  healthy: blocked.length === 0 && corrupt.length === 0,
+  repaired: [...repaired].sort(),
+  blocked: [...blocked].sort(),
+  corrupt: [...corrupt].sort(),
+});
+
+async function inspect(root) {
+  const paths = storePaths(root);
+  const blocked = [];
+  const corrupt = [];
+  let pending = [];
+
+  // Identity first. A store whose version or identity does not validate is
+  // never mutated, so an operator repairing the wrong directory fails closed
+  // instead of rewriting someone else's state.
+  let identity = null;
+  try {
+    identity = await readStoreIdentity(paths);
+  } catch (error) {
+    blocked.push(path.join(root, "protocol.json"));
+    return { paths, identity: null, pending, blocked, corrupt, reason: error.message };
+  }
+  if (identity === null) blocked.push(path.join(root, "protocol.json"));
+
+  try {
+    pending = await readOpenJournals(paths, root);
+  } catch (error) {
+    corrupt.push(paths.journal);
+    return { paths, identity, pending: [], blocked, corrupt, reason: error.message };
+  }
+
+  for (const kind of (await listDirectoryEntries(paths.state, { root }))
+    .filter(entry => entry.isDirectory()).map(entry => entry.name)) {
+    for (const filePath of await listJsonFiles(path.join(paths.state, kind), { root })) {
+      try {
+        const found = await readJsonIfPresent(filePath, root);
+        const envelope = assertStateBinding(found.value, kind,
+          path.basename(filePath, ".json"), filePath);
+        validateRecord(envelope.kind, envelope.record);
+      } catch {
+        corrupt.push(filePath);
+      }
+    }
+  }
+
+  let expected = 1;
+  for (const filePath of await listJsonFiles(paths.events, { root })) {
+    try {
+      const found = await readJsonIfPresent(filePath, root);
+      const event = assertEventBinding(found.value, filePath);
+      validateRecord("event", event);
+      // A gap can only survive a completed roll-forward if a file was removed
+      // by hand, so it is corruption rather than a pending publication.
+      if (Number(event.sequence) !== expected && pending.length === 0) corrupt.push(filePath);
+      expected = Number(event.sequence) + 1;
+    } catch {
+      corrupt.push(filePath);
+    }
+  }
+
+  return { paths, identity, pending, blocked, corrupt, reason: null };
+}
+
+export async function diagnoseFilesystemStore({ root }) {
+  const state = await inspect(root);
+  return report({
+    blocked: state.blocked,
+    corrupt: state.corrupt,
+    repaired: state.pending.map(entry => entry.transactionId),
+  });
+}
+
+export async function repairFilesystemStore({ root, clock }) {
+  const state = await inspect(root);
+  if (state.blocked.length > 0 || state.corrupt.length > 0) {
+    // Fail closed. Completing a journal on top of state we cannot even read
+    // would turn an ambiguous store into a confidently wrong one.
+    return report({ blocked: state.blocked, corrupt: state.corrupt });
+  }
+  if (state.pending.length === 0) return report({});
+
+  const repaired = await withWriterMutex(state.paths, { root, tmpDir: state.paths.tmp, clock },
+    async () => {
+      const completed = [];
+      for (const entry of await readOpenJournals(state.paths, root)) {
+        await rollForward(state.paths, { root, tmpDir: state.paths.tmp, clock }, entry);
+        completed.push(entry.transactionId);
+      }
+      return completed;
+    });
+  return report({ repaired });
+}
+
+export function assertRepairable(reportValue) {
+  if (!reportValue.healthy) {
+    throw new AccError(EXIT.DATA, "store state is ambiguous; repair is blocked", reportValue);
+  }
+  return reportValue;
+}

package/node_modules/@agents-can-communicate/storage-filesystem/src/safe-directory.mjs

@@ -0,0 +1,80 @@
+import { lstat, mkdir, realpath } from "node:fs/promises";
+import path from "node:path";
+
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+// Ported from the reconciled prototype without semantic change. Every managed
+// path is validated segment by segment against the canonical root, so a
+// symlinked ancestor cannot redirect a read or a publication outside the store.
+function invalidDirectory(message, directory, root, cause) {
+  return new AccError(EXIT.DATA, message, {
+    directory,
+    root,
+    ...(cause === undefined ? {} : { cause }),
+  });
+}
+
+function relativeWithin(root, directory) {
+  const relative = path.relative(root, directory);
+  if (relative === "" || (!path.isAbsolute(relative)
+    && relative !== ".." && !relative.startsWith(`..${path.sep}`))) return relative;
+  throw invalidDirectory("managed directory escapes the store root", directory, root);
+}
+
+function absolutePath(value, name, root = value) {
+  if (typeof value !== "string" || !path.isAbsolute(value)) {
+    throw invalidDirectory(`${name} must be absolute`, value, root);
+  }
+  return path.normalize(value);
+}
+
+async function inspectRealDirectory(directory, root, create) {
+  let details;
+  try {
+    details = await lstat(directory);
+  } catch (error) {
+    if (error.code === "ENOENT" && !create) throw error;
+    if (error.code !== "ENOENT") {
+      throw invalidDirectory("cannot inspect managed directory", directory, root, error.message);
+    }
+    try {
+      await mkdir(directory);
+    } catch (mkdirError) {
+      if (mkdirError.code !== "EEXIST") {
+        throw invalidDirectory("cannot create managed directory", directory, root,
+          mkdirError.message);
+      }
+    }
+    details = await lstat(directory);
+  }
+  if (!details.isDirectory() || details.isSymbolicLink()) {
+    throw invalidDirectory("managed directory is not a real directory", directory, root);
+  }
+  return details;
+}
+
+async function inspectManagedDirectory(rootPath, directoryPath, create) {
+  const root = absolutePath(rootPath, "managed root");
+  const directory = absolutePath(directoryPath, "managed directory", root);
+  const relative = relativeWithin(root, directory);
+  let details = await inspectRealDirectory(root, root, create);
+  const canonicalRoot = await realpath(root);
+  let current = root;
+  for (const segment of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    details = await inspectRealDirectory(current, root, create);
+    const expected = path.join(canonicalRoot, path.relative(root, current));
+    if (await realpath(current) !== expected) {
+      throw invalidDirectory("managed directory escapes the canonical store root", current, root);
+    }
+  }
+  return { directory, stat: details };
+}
+
+export async function assertManagedDirectory(rootPath, directoryPath) {
+  return inspectManagedDirectory(rootPath, directoryPath, false);
+}
+
+export async function ensureManagedDirectory(rootPath, directoryPath) {
+  return (await inspectManagedDirectory(rootPath, directoryPath, true)).directory;
+}

package/node_modules/@agents-can-communicate/storage-filesystem/src/safe-file.mjs

@@ -0,0 +1,55 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import path from "node:path";
+
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+import { assertManagedDirectory } from "./safe-directory.mjs";
+
+function sameDirectory(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+// O_NOFOLLOW plus a before/after identity check on the parent: the bytes
+// returned come from the handle that was opened, not from whatever the path
+// resolves to afterwards. The injected opener is the seam the crash-window and
+// race tests use, and stays the final argument.
+export async function readRegularNoFollow(filePath, root, openFile = open) {
+  const parent = path.dirname(filePath);
+  const before = await assertManagedDirectory(root, parent);
+  let handle;
+  try {
+    handle = await openFile(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+  } catch (error) {
+    if (error.code === "ENOENT") throw error;
+    throw new AccError(EXIT.DATA, "cannot safely open regular file",
+      { filePath, cause: error.message });
+  }
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile()) {
+      throw new AccError(EXIT.DATA, "record is not a regular file", { filePath });
+    }
+    const after = await assertManagedDirectory(root, parent);
+    if (!sameDirectory(before.stat, after.stat)) {
+      throw new AccError(EXIT.DATA, "record parent directory changed while opening",
+        { filePath, root });
+    }
+    return await handle.readFile();
+  } catch (error) {
+    if (error instanceof AccError || error.code === "ENOENT") throw error;
+    throw new AccError(EXIT.DATA, "cannot safely read regular file",
+      { filePath, cause: error.message });
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function readJsonNoFollow(filePath, root, openFile = open) {
+  const bytes = await readRegularNoFollow(filePath, root, openFile);
+  try {
+    return { value: JSON.parse(bytes.toString("utf8")), bytes };
+  } catch (error) {
+    throw new AccError(EXIT.DATA, "invalid JSON record", { filePath, cause: error.message });
+  }
+}

package/node_modules/@agents-can-communicate/storage-filesystem/src/store.mjs

@@ -0,0 +1,292 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+
+import { AccError, EXIT, validateRecord } from "@agents-can-communicate/protocol";
+
+import { encode, listDirectoryEntries, listJsonFiles, publishAtomic, readJsonIfPresent,
+  removeIfPresent } from "./atomic-json.mjs";
+import { requireStoreIdentity } from "./identity.mjs";
+import { journalEntry, readOpenJournals, rollForward, writeJournalEntry } from "./journal.mjs";
+import { assertEventBinding, assertStateBinding, eventPath, stateEnvelope, statePath }
+  from "./record-id.mjs";
+import { ensureManagedDirectory } from "./safe-directory.mjs";
+import { withWriterMutex } from "./writer-mutex.mjs";
+
+const SEQUENCE_WIDTH = 16;
+export const ZERO_CURSOR = "0".repeat(SEQUENCE_WIDTH);
+// No quarantine area. One was created in every workspace, named in the path
+// typedef, and written to by nothing: repair deliberately refuses to move a
+// corrupt record, so nothing ever had a reason to put one aside. An empty
+// directory that reads as a feature is the same mistake as an attention kind
+// with no rule behind it. If quarantining is ever built, it comes back with it.
+const DIRECTORIES = ["state", "events", "journal", "locks", "ephemeral", "tmp"];
+
+const pad = value => String(value).padStart(SEQUENCE_WIDTH, "0");
+
+export function storePaths(root) {
+  return Object.freeze(Object.fromEntries([["root", root],
+    ...DIRECTORIES.map(name => [name, path.join(root, name)])]));
+}
+
+async function listState(paths, root, kind) {
+  const envelopes = [];
+  for (const filePath of await listJsonFiles(path.join(paths.state, kind), { root })) {
+    const found = await readJsonIfPresent(filePath, root);
+    if (found === null) continue;
+    envelopes.push(assertStateBinding(found.value, kind,
+      path.basename(filePath, ".json"), filePath));
+  }
+  return envelopes;
+}
+
+async function loadAllState(paths, root, wanted = null) {
+  const loaded = new Map();
+  const kinds = (await listDirectoryEntries(paths.state, { root }))
+    .filter(entry => entry.isDirectory()).map(entry => entry.name)
+    .filter(kind => wanted === null || wanted.has(kind));
+  for (const kind of kinds) {
+    for (const envelope of await listState(paths, root, kind)) {
+      loaded.set(`${envelope.kind}:${envelope.id}`, envelope);
+    }
+  }
+  return loaded;
+}
+
+async function nextSequence(paths, root) {
+  const last = (await listJsonFiles(paths.events, { root })).at(-1);
+  return last === undefined ? 1 : Number(path.basename(last, ".json")) + 1;
+}
+
+export async function openFilesystemStore({ root, clock, ids, workspaceId, failAt }) {
+  const paths = storePaths(root);
+  // The caller owns the root path, so its ancestors are created here. Inside the
+  // root, containment rules apply and each level is created individually so a
+  // symlinked ancestor cannot be created past.
+  await mkdir(root, { recursive: true });
+  for (const name of DIRECTORIES) await ensureManagedDirectory(root, paths[name]);
+  // Identity is settled before any read or write. Adopting a directory that
+  // already belongs to another workspace is the failure this fails closed on.
+  await requireStoreIdentity(paths, { workspaceId, clock });
+  const publishOptions = { root, tmpDir: paths.tmp, clock, failAt };
+
+  // Any journal left behind by a crashed writer is completed before the store
+  // serves a single read, so callers never observe a half-published
+  // transaction even on the first open after a crash. Recovery is a write, so
+  // it holds the writer mutex: two processes opening the same store at once
+  // must not roll the same journal forward concurrently.
+  await recoverOpenJournals();
+
+  async function recoverOpenJournals() {
+    const open = await readOpenJournals(paths, root);
+    if (open.length === 0) return [];
+    return withWriterMutex(paths, { root, tmpDir: paths.tmp, clock }, async () => {
+      const completed = [];
+      for (const entry of await readOpenJournals(paths, root)) {
+        completed.push(...await rollForward(paths, { root, tmpDir: paths.tmp, clock }, entry));
+      }
+      return completed;
+    });
+  }
+
+  /**
+   * Run a write, having read the kinds it declared and no others.
+   *
+   * A transaction used to read every record the workspace held, for the
+   * generation checks `put` makes. That put the cost of `acc message` in
+   * proportion to everything the workspace already contained - 400 messages
+   * written one after another took 163 seconds, the last of them half a second
+   * each - and some of these transactions run inside hooks, where the budget is
+   * five seconds and running out means failing open.
+   *
+   * `kinds` is enforced, not merely honoured: reaching for an undeclared kind
+   * throws. A silent empty list would be the worst of both, since every check
+   * these transactions make reads as "nothing conflicts" when it finds nothing.
+   * Declaring nothing reads everything, which is what this always did.
+   */
+  async function transaction(callback, { kinds } = {}) {
+    const wanted = kinds === undefined ? null : new Set(kinds);
+    const declared = kind => {
+      if (wanted !== null && !wanted.has(kind)) {
+        throw new AccError(EXIT.DATA,
+          `this transaction did not declare ${kind}, so it was never read`,
+          { kind, declared: [...wanted] });
+      }
+      return kind;
+    };
+    return withWriterMutex(paths, publishOptions, async () => {
+      // Reads are loaded once per transaction so get, list, and the generation
+      // that put() compares against all describe the same instant.
+      const loaded = await loadAllState(paths, root, wanted);
+      const staged = new Map();
+      const events = [];
+      let sequence = await nextSequence(paths, root);
+      const firstSequence = pad(sequence);
+      const entryFor = key => {
+        const entry = staged.get(key) ?? loaded.get(key) ?? null;
+        return entry?.removed === true ? null : entry;
+      };
+
+      const tx = Object.freeze({
+        get(kind, id) {
+          declared(kind);
+          return entryFor(`${kind}:${id}`)?.record ?? null;
+        },
+        generationOf(kind, id) {
+          declared(kind);
+          return entryFor(`${kind}:${id}`)?.generation ?? null;
+        },
+        list(kind, predicate = () => true) {
+          declared(kind);
+          const merged = new Map();
+          for (const source of [loaded, staged]) {
+            for (const [key, entry] of source) {
+              if (entry.kind === kind) merged.set(key, entry);
+            }
+          }
+          return [...merged.values()].filter(entry => entry.removed !== true)
+            .map(entry => entry.record).filter(predicate);
+        },
+        put(kind, id, record, expectedGeneration = null) {
+          declared(kind);
+          const key = `${kind}:${id}`;
+          const actual = entryFor(key)?.generation ?? null;
+          if (actual !== expectedGeneration) {
+            throw new AccError(EXIT.CONFLICT, `${kind} ${id} changed under this transaction`,
+              { kind, id, expectedGeneration, actualGeneration: actual });
+          }
+          validateRecord(kind, record);
+          const generation = ids.next("generation");
+          staged.set(key, { kind, id, record, generation });
+          return generation;
+        },
+        remove(kind, id, expectedGeneration = null) {
+          declared(kind);
+          const key = `${kind}:${id}`;
+          const actual = entryFor(key)?.generation ?? null;
+          if (actual !== expectedGeneration) {
+            throw new AccError(EXIT.CONFLICT, `${kind} ${id} changed under this transaction`,
+              { kind, id, expectedGeneration, actualGeneration: actual });
+          }
+          staged.set(key, { kind, id, removed: true });
+        },
+        append(event) {
+          const stamped = { ...event, sequence: pad(sequence) };
+          sequence += 1;
+          validateRecord("event", stamped);
+          events.push(stamped);
+          return stamped;
+        },
+      });
+
+      const result = await callback(tx);
+
+      // Events are published before state records on purpose: the event log is
+      // the authority, and a crash between the two is the window the journal
+      // ceiling in eventsSince has to hide.
+      const publications = [
+        ...events.map(event => ({
+          path: path.relative(root, eventPath(paths, event.sequence)),
+          bytes: encode(event),
+          replace: false,
+        })),
+        ...[...staged.values()].map(entry => (entry.removed === true
+          ? { path: path.relative(root, statePath(paths, entry.kind, entry.id)), remove: true }
+          : {
+            path: path.relative(root, statePath(paths, entry.kind, entry.id)),
+            bytes: encode(stateEnvelope(entry.kind, entry.id, entry.generation, entry.record)),
+            replace: true,
+          })),
+      ];
+      if (publications.length === 0) return result;
+
+      const entry = journalEntry(ids.next("transaction"), firstSequence, publications,
+        clock.now());
+      await writeJournalEntry(paths, publishOptions, entry);
+      await failAt?.("after-journal");
+      await rollForward(paths, publishOptions, entry);
+      return result;
+    });
+  }
+
+  async function eventsSince(workspace, cursor, limit) {
+    const after = cursor ?? ZERO_CURSOR;
+    // An open journal marks a transaction that is decided but not fully
+    // published. Bounding the page below its first sequence is what keeps a
+    // partially published transaction invisible to every reader.
+    const ceiling = (await readOpenJournals(paths, root)).at(0)?.firstSequence ?? null;
+    const events = [];
+    for (const filePath of await listJsonFiles(paths.events, { root })) {
+      const sequence = path.basename(filePath, ".json");
+      if (sequence <= after) continue;
+      if (ceiling !== null && sequence >= ceiling) break;
+      const found = await readJsonIfPresent(filePath, root);
+      if (found === null) continue;
+      const event = assertEventBinding(found.value, filePath);
+      if (event.workspaceId !== workspace) continue;
+      events.push(event);
+      if (events.length === limit) break;
+    }
+    return { cursor: events.at(-1)?.sequence ?? after, events };
+  }
+
+  /**
+   * Read the durable state, or the part of it a caller actually needs.
+   *
+   * Every kind is read by default, which is what most callers want and what
+   * this always did. `kinds` exists because one caller runs in front of every
+   * file an agent writes: reading the whole store there made the write guard
+   * cost grow with the number of messages the workspace had ever carried, and
+   * the hook budget is five seconds after which it allows the write.
+   */
+  async function snapshot(workspace, { kinds } = {}) {
+    const wanted = kinds === undefined ? null : new Set(kinds);
+    const of = async kind => {
+      if (wanted !== null && !wanted.has(kind)) return [];
+      return (await listState(paths, root, kind))
+        .map(envelope => envelope.record)
+        .filter(record => record.workspaceId === workspace);
+    };
+    return {
+      workspace: (await of("workspace"))[0] ?? null,
+      participants: await of("participant"),
+      sessions: await of("session"),
+      intents: await of("intent"),
+      workstreams: await of("workstream"),
+      tasks: await of("task"),
+      claims: await of("claim"),
+      messages: await of("message"),
+      receipts: await of("receipt"),
+      decisions: await of("decision"),
+      handoffs: await of("handoff"),
+    };
+  }
+
+  // Ephemeral records are published by replace and never journalled: they carry
+  // no history, append no events, and are expected to disappear.
+  const ephemeralPath = (kind, id) => path.join(paths.ephemeral, kind, `${id}.json`);
+  const ephemeral = Object.freeze({
+    async get(kind, id) {
+      const found = await readJsonIfPresent(ephemeralPath(kind, id), root);
+      return found?.value ?? null;
+    },
+    async put(kind, id, record) {
+      await publishAtomic(ephemeralPath(kind, id), encode(record),
+        { root, tmpDir: paths.tmp, replace: true });
+      return record;
+    },
+    async delete(kind, id) {
+      await removeIfPresent(ephemeralPath(kind, id));
+    },
+    async list(kind) {
+      const records = [];
+      for (const filePath of await listJsonFiles(path.join(paths.ephemeral, kind), { root })) {
+        const found = await readJsonIfPresent(filePath, root);
+        if (found !== null) records.push(found.value);
+      }
+      return records;
+    },
+  });
+
+  return Object.freeze({ transaction, eventsSince, snapshot, ephemeral, paths, root,
+    workspaceId });
+}

package/node_modules/@agents-can-communicate/storage-filesystem/src/writer-mutex.mjs

@@ -0,0 +1,87 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, rm } from "node:fs/promises";
+import path from "node:path";
+
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+import { encode, publishAtomic, readJsonIfPresent } from "./atomic-json.mjs";
+import { ensureManagedDirectory } from "./safe-directory.mjs";
+
+const STALE_MS = 60_000;
+const OWNER = "owner.json";
+
+// Directory creation is the atomic primitive: mkdir either creates or fails
+// with EEXIST, with no window in between. Ported from the reconciled
+// prototype's repair mutex and reused here as the per-workspace writer lock.
+function defaultPidIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code !== "ESRCH";
+  }
+}
+
+async function readOwner(directory, root) {
+  const found = await readJsonIfPresent(path.join(directory, OWNER), root);
+  return found?.value ?? null;
+}
+
+/**
+ * Reclaim a lock nobody is holding.
+ *
+ * A hook is a process a client is free to kill, and clients do: they all put a
+ * timeout on it. Killed mid-write, it leaves this directory behind with its own
+ * pid in it. Requiring the lock to be *both* dead and a minute old meant that
+ * for the next sixty seconds no write in the workspace could proceed - no
+ * intent, no claim, no message, and no session could attach. Hooks fail open,
+ * so none of it was visible: the session simply never appeared, and `acc
+ * status` went on reporting the ones that had.
+ *
+ * A dead owner is reclaimed at once. There is nothing to wait for: the lock
+ * holds no state beyond its own owner file, and the process that would have
+ * finished the write is gone.
+ *
+ * The age still matters for the one case liveness cannot answer. A pid is
+ * recycled, so a dead owner's number can come back attached to something
+ * unrelated, and then `pidIsAlive` says yes forever. Sixty seconds is far longer
+ * than any write here takes - the hook budget is five - so a holder that old is
+ * not a writer that is still going.
+ */
+async function takeStaleOwnership(directory, root, owner, now, pidIsAlive) {
+  if (owner === null) return false;
+  const age = Date.parse(now) - Date.parse(owner.acquiredAt);
+  if (pidIsAlive(owner.pid) && !(age > STALE_MS)) return false;
+  await rm(directory, { recursive: true, force: true });
+  return true;
+}
+
+export async function withWriterMutex(paths, options, operation) {
+  const { root, clock, pidIsAlive = defaultPidIsAlive, uuid = randomUUID,
+    attempts = 50, waitMs = 20 } = options;
+  const directory = path.join(paths.locks, "writer.lock");
+  await ensureManagedDirectory(root, paths.locks);
+  const token = uuid();
+
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    try {
+      await mkdir(directory);
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const owner = await readOwner(directory, root);
+      if (!await takeStaleOwnership(directory, root, owner, clock.now(), pidIsAlive)) {
+        await new Promise(resolve => { setTimeout(resolve, waitMs); });
+      }
+      continue;
+    }
+    const owner = { pid: process.pid, token, acquiredAt: clock.now() };
+    await publishAtomic(path.join(directory, OWNER), encode(owner), { root, tmpDir: paths.tmp });
+    try {
+      return await operation();
+    } finally {
+      const current = await readOwner(directory, root);
+      if (current?.token === token) await rm(directory, { recursive: true, force: true });
+    }
+  }
+  throw new AccError(EXIT.CONFLICT, "another writer holds the store lock", { directory });
+}