handmux 0.17.7 → 0.18.0

package/src/workspace/agentRunner.js

@@ -0,0 +1,185 @@
+import { spawn as spawnChild } from 'node:child_process';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ensurePrivateDir, writeJsonAtomic } from './atomicJson.js';
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const PANE_RE = /^%\d+$/;
+const RUNNER_FILE = fileURLToPath(import.meta.url);
+
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function validateAgentRequest(request) {
+  const valid = request?.cmd === 'claude'
+    ? Array.isArray(request.args) && request.args.length === 2 && request.args[0] === '--resume' && UUID_RE.test(request.args[1])
+    : request?.cmd === 'codex'
+      && Array.isArray(request.args) && request.args.length === 2 && request.args[0] === 'resume' && UUID_RE.test(request.args[1]);
+  if (!valid) throw new Error('unsafe agent request');
+  return { cmd: request.cmd, args: [...request.args] };
+}
+
+function earlyFailure(request, error, code) {
+  if (error?.code === 'ENOENT') return `${request.cmd} binary not found`;
+  if (error) return `${request.cmd} failed to start: ${errorText(error)}`;
+  return `${request.cmd} exited ${code ?? 'unknown'} before ready`;
+}
+
+export function launchAgentRequest(requestInput, {
+  spawn = spawnChild,
+  readinessMs = 500,
+  setTimeout = globalThis.setTimeout,
+  clearTimeout = globalThis.clearTimeout,
+} = {}) {
+  const request = validateAgentRequest(requestInput);
+  let child;
+  let readyDone = false;
+  let timer = null;
+  let completionDone = false;
+  let settleReady;
+  let settleCompletion;
+  const ready = new Promise((resolve) => { settleReady = resolve; });
+  const completion = new Promise((resolve) => { settleCompletion = resolve; });
+  const finishCompletion = (value) => {
+    if (completionDone) return;
+    completionDone = true;
+    settleCompletion(value);
+  };
+  const failReady = (error, code) => {
+    if (readyDone) return;
+    readyDone = true;
+    if (timer) clearTimeout(timer);
+    settleReady({ status: 'failed', error: earlyFailure(request, error, code) });
+  };
+  try {
+    child = spawn(request.cmd, request.args, { stdio: 'inherit', shell: false });
+  } catch (error) {
+    failReady(error);
+    finishCompletion({ code: null, signal: null, error: errorText(error) });
+    return { child: null, ready, completion, terminate: async () => completion };
+  }
+  child.once('spawn', () => {
+    timer = setTimeout(() => {
+      if (readyDone) return;
+      readyDone = true;
+      settleReady({ status: 'ready' });
+    }, readinessMs);
+  });
+  child.once('error', (error) => {
+    failReady(error);
+    finishCompletion({ code: null, signal: null, error: errorText(error) });
+  });
+  child.once('exit', (code, signal) => {
+    failReady(null, code);
+    finishCompletion({ code, signal });
+  });
+  return {
+    child,
+    ready,
+    completion,
+    async terminate() {
+      if (!completionDone) child.kill('SIGTERM');
+      return completion;
+    },
+  };
+}
+
+export async function publishAgentReadiness(launched, writeStatus) {
+  const ready = await launched.ready;
+  try {
+    await writeStatus(ready);
+  } catch (error) {
+    let cleanupError;
+    try { await launched.terminate(); } catch (failure) { cleanupError = failure; }
+    if (cleanupError) throw new Error(`${errorText(error)}; cleanup failed: ${errorText(cleanupError)}`);
+    throw error;
+  }
+  return ready;
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}
+
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function unlinkIfPresent(fs, file) {
+  try { await fs.unlink(file); } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+}
+
+export function createAgentRunner({
+  home = os.homedir(),
+  fs = fsp,
+  now = Date.now,
+  wait = delay,
+  timeoutMs = 3_000,
+  pollMs = 25,
+} = {}) {
+  const dir = path.join(home, '.handmux', 'workspaces', 'agent-runs');
+  const command = `${shellQuote(process.execPath)} ${shellQuote(RUNNER_FILE)}`;
+  const files = (paneId) => {
+    if (!PANE_RE.test(paneId)) throw new Error('invalid agent runner pane id');
+    const base = paneId.slice(1);
+    return { request: path.join(dir, `${base}.request.json`), status: path.join(dir, `${base}.status.json`) };
+  };
+  return {
+    command,
+    async prepare({ paneId, cmd, args }) {
+      const request = validateAgentRequest({ cmd, args });
+      const target = files(paneId);
+      await ensurePrivateDir(dir, { fs });
+      await unlinkIfPresent(fs, target.status);
+      await writeJsonAtomic(target.request, { paneId, ...request }, { fs });
+    },
+    async waitReady(paneId) {
+      const target = files(paneId);
+      const started = now();
+      while (now() - started <= timeoutMs) {
+        try {
+          const status = JSON.parse(await fs.readFile(target.status, 'utf8'));
+          if (status?.status === 'ready' || status?.status === 'failed') return status;
+        } catch (error) {
+          if (error?.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error;
+        }
+        await wait(pollMs);
+      }
+      return { status: 'failed', error: 'agent readiness timed out' };
+    },
+    async cancel(paneId) {
+      const target = files(paneId);
+      await Promise.all([target.request, target.status].map((file) => unlinkIfPresent(fs, file)));
+    },
+  };
+}
+
+async function runPreparedAgent() {
+  const paneId = process.env.TMUX_PANE;
+  const target = (() => {
+    if (!PANE_RE.test(paneId || '')) throw new Error('agent runner requires TMUX_PANE');
+    const dir = path.join(os.homedir(), '.handmux', 'workspaces', 'agent-runs');
+    const base = paneId.slice(1);
+    return { request: path.join(dir, `${base}.request.json`), status: path.join(dir, `${base}.status.json`) };
+  })();
+  const input = JSON.parse(await fsp.readFile(target.request, 'utf8'));
+  if (input.paneId !== paneId) throw new Error('agent runner pane mismatch');
+  const launched = launchAgentRequest(input);
+  try {
+    const ready = await publishAgentReadiness(launched, (status) => writeJsonAtomic(target.status, status));
+    if (ready.status === 'ready') await launched.completion;
+    if (ready.status !== 'ready') throw new Error(ready.error);
+  } finally {
+    await unlinkIfPresent(fsp, target.request);
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === RUNNER_FILE) {
+  runPreparedAgent().catch((error) => {
+    process.stderr.write(`handmux agent resume: ${errorText(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/src/workspace/atomicJson.js

@@ -0,0 +1,32 @@
+import crypto from 'node:crypto';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+export async function ensurePrivateDir(dir, { fs = fsp } = {}) {
+  const resolved = path.resolve(dir);
+  const { root } = path.parse(resolved);
+  const parts = resolved.slice(root.length).split(path.sep).filter(Boolean);
+  const privateStart = parts.indexOf('.handmux');
+  const first = privateStart === -1 ? parts.length - 1 : privateStart;
+  for (let index = first; index < parts.length; index += 1) {
+    const current = path.join(root, ...parts.slice(0, index + 1));
+    await fs.mkdir(current, { recursive: true, mode: 0o700 });
+    await fs.chmod(current, 0o700);
+  }
+}
+
+export async function writeJsonAtomic(file, value, { fs = fsp } = {}) {
+  const temp = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  const handle = await fs.open(temp, 'wx', 0o600);
+  try {
+    await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    await handle.sync();
+    await handle.close();
+    await fs.rename(temp, file);
+    await fs.chmod(file, 0o600);
+  } catch (error) {
+    await handle.close().catch(() => {});
+    await fs.unlink(temp).catch(() => {});
+    throw error;
+  }
+}

package/src/workspace/capture.js

@@ -0,0 +1,87 @@
+import fsp from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { AGENTS } from '../agents/index.js';
+import { canonicalizeSnapshot, WORKSPACE_SCHEMA_VERSION } from './schema.js';
+
+function agentMap(agents) {
+  return new Map(agents.map((agent) => [agent.id, agent]));
+}
+
+export async function readAgentBindings(stateFile, agents = AGENTS, readFile = fsp.readFile, access = fsp.access, stat = fsp.stat) {
+  let state;
+  try {
+    state = JSON.parse(await readFile(stateFile, 'utf8'));
+    if (!state || typeof state !== 'object' || Array.isArray(state)) return new Map();
+  } catch {
+    return new Map();
+  }
+
+  const known = agentMap(agents);
+  const bindings = new Map();
+  for (const [paneRuntimeId, record] of Object.entries(state)) {
+    if (!record || typeof record !== 'object' || Array.isArray(record)) continue;
+    const id = record.agent === undefined ? 'claude' : record.agent;
+    if (typeof id !== 'string' || !known.has(id)) continue;
+    const payload = record.payload;
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) continue;
+    const sessionId = payload.session_id;
+    const transcriptPath = payload.transcript_path;
+    const driver = known.get(id);
+    if (!driver.sessions?.isId(sessionId) || typeof transcriptPath !== 'string' || !transcriptPath) continue;
+    try {
+      await access(transcriptPath, constants.R_OK);
+      if (!(await stat(transcriptPath)).isFile()) continue;
+    } catch { continue; }
+    bindings.set(paneRuntimeId, { id, sessionId, transcriptPath });
+  }
+  return bindings;
+}
+
+export function attachBindings(topology, bindings) {
+  return {
+    ...topology,
+    windows: topology.windows.map((window) => ({
+      ...window,
+      panes: window.panes.map((pane) => ({ ...pane, agent: bindings.get(pane.runtimeId) || null })),
+    })),
+  };
+}
+
+function isUnknownFingerprint(value) {
+  return value === null || value === undefined || value?.status === 'unknown';
+}
+
+export async function captureWorkspace({
+  tmux,
+  stateFile,
+  environment,
+  agents = AGENTS,
+  readFile = fsp.readFile,
+  access = fsp.access,
+  stat = fsp.stat,
+  now = Date.now,
+}) {
+  try {
+    const before = await tmux.topologyFingerprint();
+    if (isUnknownFingerprint(before)) return { status: 'unknown' };
+    const topology = await tmux.captureTopology();
+    if (!topology || topology.status === 'unknown') return { status: 'unknown' };
+    const bindings = await readAgentBindings(stateFile, agents, readFile, access, stat);
+    const after = await tmux.topologyFingerprint();
+    if (isUnknownFingerprint(after)) return { status: 'unknown' };
+    if (before !== after) return { status: 'changed-during-capture' };
+
+    const snapshot = canonicalizeSnapshot(attachBindings({
+      schemaVersion: WORKSPACE_SCHEMA_VERSION,
+      capturedAt: new Date(now()).toISOString(),
+      environment: { ...environment },
+      tmuxVersion: topology.tmuxVersion,
+      active: topology.active,
+      sessions: topology.sessions,
+      windows: topology.windows,
+    }, bindings));
+    return { status: topology.status === 'empty' ? 'empty' : 'ok', snapshot };
+  } catch {
+    return { status: 'unknown' };
+  }
+}

package/src/workspace/checkpointer.js

@@ -0,0 +1,179 @@
+import { captureWorkspace } from './capture.js';
+import { detectEnvironmentChange } from './environment.js';
+import { fingerprintSnapshot } from './schema.js';
+
+function sameSnapshot(left, right) {
+  return fingerprintSnapshot(left) === fingerprintSnapshot(right);
+}
+
+function snapshotEnvironment(observed) {
+  return {
+    id: observed.id,
+    bootIdentity: observed.bootIdentity,
+    tmuxServerId: observed.tmuxServerId,
+  };
+}
+
+async function reconcileOnce(deps, cause) {
+  const handle = await deps.lock.tryAcquire({ operationId: `checkpointer:${cause}` });
+  if (!handle) return { status: 'locked' };
+  try {
+    const observed = await deps.observeEnvironment();
+    if (!observed || observed.status === 'unknown') return { status: 'unknown' };
+
+    const live = await deps.store.readLive();
+    if (live.status === 'corrupt') return live;
+    const previous = live.status === 'ok' ? live.value.environment : null;
+    let change = detectEnvironmentChange(previous, observed);
+    if (cause === 'confirmed-empty' && observed.status === 'absent') {
+      change = { status: 'same', reason: 'same', current: observed };
+    }
+    if (change.status === 'unknown') return change;
+
+    // An absent tmux server only ends a known live generation. An already-empty generation remains
+    // unknown unless a Handmux deletion explicitly confirms it.
+    if (observed.status === 'absent' && cause !== 'confirmed-empty' && change.status !== 'changed') {
+      return { status: 'unknown' };
+    }
+
+    const captured = await deps.capture(snapshotEnvironment(change.current ?? observed));
+    if (captured.status === 'changed-during-capture') {
+      deps.scheduleRetry?.();
+      return captured;
+    }
+    if (captured.status !== 'ok' && captured.status !== 'empty') return captured;
+    if (captured.status === 'empty' && cause !== 'confirmed-empty' && observed.status !== 'present' && change.status !== 'changed') {
+      return { status: 'unknown' };
+    }
+    if (change.status === 'changed') {
+      const archived = await deps.store.archiveEnvironment({
+        endedReason: change.reason,
+        detectedAt: new Date(deps.now()).toISOString(),
+      });
+      if (archived.status !== 'ok' && archived.status !== 'empty') return archived;
+    }
+    if (live.status === 'ok' && sameSnapshot(live.value, captured.snapshot)) return { status: 'unchanged' };
+    await deps.store.writeLive(captured.snapshot);
+    return { status: 'written', snapshot: captured.snapshot };
+  } finally {
+    await handle.release();
+  }
+}
+
+export function createCheckpointer({
+  setInterval = globalThis.setInterval,
+  clearInterval = globalThis.clearInterval,
+  setTimeout = globalThis.setTimeout,
+  clearTimeout = globalThis.clearTimeout,
+  now = Date.now,
+  ...rest
+} = {}) {
+  const deps = { ...rest, now, setInterval, clearInterval, setTimeout, clearTimeout };
+  let interval = null;
+  let debounce = null;
+  let running = null;
+  let pendingConfirmation = null;
+  let stopping = false;
+  let stopped = false;
+  let stopPromise = null;
+
+  function launch(cause) {
+    const current = reconcileOnce(deps, cause);
+    running = current;
+    const settled = () => {
+      if (running !== current) return;
+      running = null;
+      if (pendingConfirmation) {
+        const pending = pendingConfirmation;
+        pendingConfirmation = null;
+        launch('confirmed-empty').then(pending.resolve, pending.reject);
+      }
+    };
+    current.then(settled, settled);
+    return current;
+  }
+
+  function confirmEmpty() {
+    if (stopping || stopped) return Promise.resolve({ status: 'stopped' });
+    if (!running) return launch('confirmed-empty');
+    if (!pendingConfirmation) {
+      let resolve;
+      let reject;
+      const promise = new Promise((onResolve, onReject) => { resolve = onResolve; reject = onReject; });
+      pendingConfirmation = { promise, resolve, reject };
+    }
+    return pendingConfirmation.promise;
+  }
+
+  function reconcile(cause = 'timer') {
+    if (cause === 'confirmed-empty') return confirmEmpty();
+    if (stopping || stopped) return Promise.resolve({ status: 'stopped' });
+    return running || launch(cause);
+  }
+
+  function requestReconcile() {
+    if (stopping || stopped) return;
+    clearTimeout(debounce);
+    debounce = setTimeout(() => {
+      debounce = null;
+      reconcile('event').catch(() => {});
+    }, 2_000);
+  }
+  deps.scheduleRetry = requestReconcile;
+
+  return {
+    reconcile,
+    start() {
+      if (stopping || stopped) return Promise.resolve({ status: 'stopped' });
+      if (!interval) interval = setInterval(() => { reconcile('timer').catch(() => {}); }, 60_000);
+      return reconcile('start');
+    },
+    requestReconcile,
+    confirmEmpty,
+    stop() {
+      if (stopPromise) return stopPromise;
+      stopping = true;
+      stopPromise = (async () => {
+        if (interval) clearInterval(interval);
+        if (debounce) clearTimeout(debounce);
+        interval = null;
+        debounce = null;
+        while (running || pendingConfirmation) {
+          await (running || pendingConfirmation.promise).catch(() => {});
+        }
+        await launch('shutdown').catch(() => {});
+        while (running || pendingConfirmation) {
+          await (running || pendingConfirmation.promise).catch(() => {});
+        }
+        stopped = true;
+      })();
+      return stopPromise;
+    },
+  };
+}
+
+export function createWorkspaceBackground({ store, tmux, observeEnvironment, lock, stateFile, now = Date.now } = {}) {
+  return createCheckpointer({
+    store,
+    observeEnvironment,
+    lock,
+    now,
+    capture: (environment) => captureWorkspace({ tmux, stateFile, environment, now }),
+  });
+}
+
+export function createGracefulShutdown({ events, workspace, server }) {
+  let closing = null;
+  return function shutdown() {
+    if (!closing) {
+      closing = (async () => {
+        try {
+          await events.stop();
+        } finally {
+          try { await workspace.stop(); } finally { server.close(); }
+        }
+      })();
+    }
+    return closing;
+  };
+}

package/src/workspace/environment.js

@@ -0,0 +1,75 @@
+import crypto from 'node:crypto';
+import { execFile } from 'node:child_process';
+import fsp from 'node:fs/promises';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+function normalizeMacBootTime(value) {
+  const seconds = String(value).match(/\bsec\s*=\s*(\d+)\b/)?.[1];
+  return seconds && seconds !== '0' ? seconds : null;
+}
+
+function environmentId(bootIdentity, tmuxServerId) {
+  return crypto
+    .createHash('sha256')
+    .update(`${bootIdentity}\0${tmuxServerId || 'no-tmux'}`)
+    .digest('hex');
+}
+
+export function detectEnvironmentChange(previous, observed) {
+  if (!observed || observed.status === 'unknown') return { status: 'unknown' };
+  if (!previous) return { status: 'initial', current: observed };
+  if (previous.bootIdentity !== observed.bootIdentity) return { status: 'changed', reason: 'boot-changed', current: observed };
+  if (observed.status === 'absent') {
+    return previous.tmuxServerId
+      ? { status: 'changed', reason: 'tmux-changed', current: observed }
+      : { status: 'unknown' };
+  }
+  if (!previous.tmuxServerId) return { status: 'attached', reason: 'same', current: observed };
+  if (previous.tmuxServerId !== observed.tmuxServerId) return { status: 'changed', reason: 'tmux-changed', current: observed };
+  return { status: 'same', reason: 'same', current: observed };
+}
+
+export function createBootIdentityProvider({
+  platform = process.platform,
+  readFile = fsp.readFile,
+  exec = execFileAsync,
+} = {}) {
+  return async () => {
+    try {
+      if (platform === 'linux') {
+        const identity = String(await readFile('/proc/sys/kernel/random/boot_id', 'utf8')).trim();
+        return identity || null;
+      }
+      if (platform === 'darwin') {
+        return normalizeMacBootTime((await exec('sysctl', ['-n', 'kern.boottime'])).stdout);
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  };
+}
+
+export function createEnvironmentProvider({
+  bootIdentityProvider = createBootIdentityProvider(),
+  tmuxServerIdProvider,
+} = {}) {
+  return async () => {
+    try {
+      const bootIdentity = await bootIdentityProvider();
+      if (typeof bootIdentity !== 'string' || !bootIdentity) return { status: 'unknown' };
+      const tmuxServerId = await tmuxServerIdProvider();
+      if (tmuxServerId !== null && (typeof tmuxServerId !== 'string' || !tmuxServerId)) return { status: 'unknown' };
+      return {
+        status: tmuxServerId === null ? 'absent' : 'present',
+        id: environmentId(bootIdentity, tmuxServerId),
+        bootIdentity,
+        tmuxServerId,
+      };
+    } catch {
+      return { status: 'unknown' };
+    }
+  };
+}

package/src/workspace/lock.js

@@ -0,0 +1,128 @@
+import crypto from 'node:crypto';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+const OWNER_FILE = 'owner.json';
+const SAFE_TOKEN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function defaultProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function ownerLabel(owner) {
+  if (!owner) return 'unknown owner';
+  const operation = typeof owner.operationId === 'string' && owner.operationId ? owner.operationId : 'unknown operation';
+  const pid = Number.isInteger(owner.pid) ? owner.pid : 'unknown';
+  return `${operation} (pid ${pid})`;
+}
+
+export function createWorkspaceLock({
+  dir,
+  fs = fsp,
+  pid = process.pid,
+  now = Date.now,
+  isProcessAlive = defaultProcessAlive,
+  wait = delay,
+  timeoutMs = 5_000,
+  retryMs = 50,
+  staleGraceMs = 5_000,
+  randomUUID = crypto.randomUUID,
+} = {}) {
+  if (typeof dir !== 'string' || !dir) throw new Error('workspace lock directory is required');
+
+  async function readOwner() {
+    let stat = null;
+    try { stat = await fs.stat(dir); } catch (error) {
+      if (error?.code === 'ENOENT') return null;
+      throw error;
+    }
+    try {
+      const value = JSON.parse(await fs.readFile(path.join(dir, OWNER_FILE), 'utf8'));
+      return { value, mtimeMs: stat.mtimeMs };
+    } catch {
+      return { value: null, mtimeMs: stat.mtimeMs };
+    }
+  }
+
+  async function reclaimIfStale(record) {
+    if (!record) return true;
+    const owner = record.value;
+    if (!SAFE_TOKEN.test(owner?.token)) return false;
+    const startedAt = Date.parse(owner?.startedAt);
+    const age = now() - (Number.isFinite(startedAt) ? startedAt : record.mtimeMs);
+    if (age < staleGraceMs) return false;
+    if (Number.isInteger(owner?.pid) && await isProcessAlive(owner.pid)) return false;
+
+    // Every contender that observed this owner uses the SAME destination. The winner leaves the renamed
+    // directory as a tombstone, so a loser cannot later rename a newly-created lock out of the way.
+    const staleDir = `${dir}.stale.${owner.token}`;
+    try {
+      await fs.rename(dir, staleDir);
+    } catch (error) {
+      if (error?.code === 'ENOENT') return true;
+      return false;
+    }
+    return true;
+  }
+
+  async function tryAcquire({ operationId = 'workspace-writer' } = {}) {
+    await fs.mkdir(path.dirname(dir), { recursive: true, mode: 0o700 });
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      const token = randomUUID();
+      if (!SAFE_TOKEN.test(token)) throw new Error('workspace lock token must be a UUID');
+      const owner = { pid, startedAt: new Date(now()).toISOString(), operationId, token };
+      try {
+        await fs.mkdir(dir, { mode: 0o700 });
+        try {
+          await fs.writeFile(path.join(dir, OWNER_FILE), `${JSON.stringify(owner)}\n`, { mode: 0o600, flag: 'wx' });
+        } catch (error) {
+          await fs.rm(dir, { recursive: true, force: true });
+          throw error;
+        }
+        let released = false;
+        return {
+          owner,
+          async release() {
+            if (released) return;
+            released = true;
+            const current = await readOwner();
+            if (current?.value?.token === token) await fs.rm(dir, { recursive: true, force: true });
+          },
+        };
+      } catch (error) {
+        if (error?.code !== 'EEXIST') throw error;
+        const record = await readOwner();
+        if (!await reclaimIfStale(record)) return null;
+      }
+    }
+    return null;
+  }
+
+  async function acquire(owner = {}, options = {}) {
+    const limit = options.timeoutMs ?? timeoutMs;
+    const started = now();
+    while (true) {
+      const handle = await tryAcquire(owner);
+      if (handle) return handle;
+      const current = await readOwner();
+      if (now() - started >= limit) {
+        throw new Error(`workspace writer lock timed out; held by ${ownerLabel(current?.value)}`);
+      }
+      await wait(options.retryMs ?? retryMs);
+    }
+  }
+
+  async function withLock(owner, fn, options) {
+    const handle = await acquire(owner, options);
+    try { return await fn(handle.owner); } finally { await handle.release(); }
+  }
+
+  return { tryAcquire, acquire, withLock, readOwner: async () => (await readOwner())?.value ?? null };
+}