quiver-cli 1.3.0 → 2.0.0

package/template/.agents/skills/design/impeccable/scripts/live/session-store.mjs

@@ -1,563 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { getLegacyLiveSessionsDir, getLiveSessionsDir, safeSessionId } from '../lib/impeccable-paths.mjs';
-import { COMPLETED_SESSION_PHASES, GENERATION_FENCED_SESSION_PHASES } from './vocabulary.mjs';
-
-const COMPLETED_PHASES = new Set(COMPLETED_SESSION_PHASES);
-export const GENERATION_FENCED_PHASES = new Set(GENERATION_FENCED_SESSION_PHASES);
-
-// The snapshot file carries two bookkeeping fields the snapshot itself does not
-// own: how large the journal was when the snapshot was written, and the next
-// sequence number. Both are stripped before a snapshot is handed to a caller.
-// The byte count is what makes a cached snapshot verifiable — the journal is
-// append-only, so a matching size means no event has landed since.
-const META_JOURNAL_BYTES = '__journalBytes';
-const META_NEXT_SEQ = '__nextSeq';
-
-// TODO(revision-unification): `checkpointRevision`, `browserCheckpointRevision`,
-// and `publicationCheckpointRevision` are three counters for two domains.
-// `checkpointRevision` is a compatibility mirror of the browser counter kept for
-// older readers. Collapsing them means changing what a resumed browser compares
-// its local revision against, so it belongs in a pass that owns resume ordering,
-// not in a caching change.
-
-export function createLiveSessionStore({ cwd = process.cwd(), sessionId } = {}) {
-  const rootDir = getLiveSessionsDir(cwd);
-  const legacyRootDir = getLegacyLiveSessionsDir(cwd);
-  fs.mkdirSync(rootDir, { recursive: true });
-
-  // Derived state per session, keyed by what the journal looked like when it was
-  // derived. Publisher/complete helpers append from other processes, so the key
-  // is the journal's own (path, size, mtime) rather than a trusted local write
-  // count: an append this process did not make invalidates the entry and the
-  // next read replays. Without the cache every append and every read replayed
-  // the whole journal, which made a long session quadratic in its own length.
-  /** @type {Map<string, { snapshot: object, nextSeq: number, journalPath: string, size: number, mtimeMs: number }>} */
-  const derived = new Map();
-
-  function getReadableJournalPath(id) {
-    const primary = getJournalPath(rootDir, id);
-    if (fs.existsSync(primary)) return primary;
-    const legacy = getJournalPath(legacyRootDir, id);
-    if (fs.existsSync(legacy)) return legacy;
-    return primary;
-  }
-
-  /**
-   * The current derived state for a session, from the in-memory cache when the
-   * journal has not moved, from the snapshot file when that file is provably
-   * current, and from a full replay otherwise.
-   */
-  function readState(id, { allowSnapshotFile = true } = {}) {
-    const journalPath = getReadableJournalPath(id);
-    const stat = statOrNull(journalPath);
-    const size = stat ? stat.size : -1;
-    const mtimeMs = stat ? stat.mtimeMs : -1;
-
-    const cached = derived.get(id);
-    if (cached && cached.journalPath === journalPath && cached.size === size && cached.mtimeMs === mtimeMs) {
-      return cached;
-    }
-
-    if (allowSnapshotFile && stat) {
-      const hydrated = readSnapshotFile(getSnapshotPath(rootDir, id), id, size);
-      if (hydrated) {
-        const entry = { ...hydrated, journalPath, size, mtimeMs };
-        derived.set(id, entry);
-        return entry;
-      }
-    }
-
-    const rebuilt = rebuildSnapshotFromJournal(journalPath, id);
-    const entry = { snapshot: rebuilt.snapshot, nextSeq: rebuilt.nextSeq, journalPath, size, mtimeMs };
-    derived.set(id, entry);
-    return entry;
-  }
-
-  function persist(id, snapshot, nextSeq) {
-    const snapshotPath = getSnapshotPath(rootDir, id);
-    const journalPath = getReadableJournalPath(id);
-    const stat = statOrNull(journalPath);
-    writeSnapshot(snapshotPath, snapshot, { journalBytes: stat ? stat.size : -1, nextSeq });
-    derived.set(id, {
-      snapshot,
-      nextSeq,
-      journalPath,
-      size: stat ? stat.size : -1,
-      mtimeMs: stat ? stat.mtimeMs : -1,
-    });
-  }
-
-  return {
-    rootDir,
-    legacyRootDir,
-    appendEvent(event) {
-      const normalized = normalizeEvent(event, sessionId);
-      const journalPath = getJournalPath(rootDir, normalized.id);
-      const legacyJournalPath = getJournalPath(legacyRootDir, normalized.id);
-      if (!fs.existsSync(journalPath) && fs.existsSync(legacyJournalPath)) {
-        fs.copyFileSync(legacyJournalPath, journalPath);
-        // The readable path just moved from legacy to primary; anything derived
-        // against the old path describes a file this session no longer reads.
-        derived.delete(normalized.id);
-      }
-      // Reuse the derived state when the journal has not changed under us, and
-      // apply the new event on top of it. Correctness still comes from the
-      // journal: any append from another process invalidates the entry above
-      // and this replays before writing, so sequence numbers and phase fences
-      // are never taken from a stale copy.
-      const prior = readState(normalized.id);
-      const entry = {
-        seq: prior.nextSeq,
-        id: normalized.id,
-        type: normalized.type,
-        ts: new Date().toISOString(),
-        event: normalized,
-      };
-      fs.appendFileSync(journalPath, JSON.stringify(entry) + '\n');
-      const next = applyEvent(prior.snapshot, entry);
-      persist(normalized.id, next, prior.nextSeq + 1);
-      return next;
-    },
-    /**
-     * True when a journal exists for the id in either root. appendEvent
-     * CREATES a journal for any id it is handed, so callers that should only
-     * ever touch existing sessions (browser checkpoints, mount acks) check
-     * here first — otherwise a stale id from another project's browser
-     * storage materializes a ghost session in this store.
-     */
-    has(id) {
-      if (!id || typeof id !== 'string') return false;
-      return fs.existsSync(getJournalPath(rootDir, id))
-        || fs.existsSync(getJournalPath(legacyRootDir, id));
-    },
-    /**
-     * Read-only. `live-status` and `live-resume` call this against a session a
-     * running server owns; writing the snapshot file here made every read a
-     * write and let a reader's replay of a half-written journal land on disk.
-     * Snapshot files are written by appendEvent and by flush().
-     */
-    getSnapshot(id = sessionId, opts = {}) {
-      if (!id) throw new Error('session id required');
-      const { snapshot } = readState(id);
-      if (!opts.includeCompleted && COMPLETED_PHASES.has(snapshot.phase)) return null;
-      return snapshot;
-    },
-    /**
-     * Write the snapshot file for a session without appending an event. The
-     * durable truth is the journal, so this only refreshes the read cache other
-     * processes use; callers that need the state itself should use getSnapshot.
-     */
-    flush(id = sessionId) {
-      if (!id) throw new Error('session id required');
-      const state = readState(id, { allowSnapshotFile: false });
-      persist(id, state.snapshot, state.nextSeq);
-      return state.snapshot;
-    },
-    listActiveSessions() {
-      const ids = new Set();
-      for (const dir of [legacyRootDir, rootDir]) {
-        if (!fs.existsSync(dir)) continue;
-        for (const name of fs.readdirSync(dir)) {
-          if (name.endsWith('.jsonl')) ids.add(name.slice(0, -'.jsonl'.length));
-        }
-      }
-      // Each id goes through readState, so a session whose journal has not moved
-      // since it was last derived costs a stat and nothing more. The server calls
-      // this on every /status and on every SSE connect.
-      return [...ids]
-        .sort()
-        .map((id) => this.getSnapshot(id))
-        .filter(Boolean);
-    },
-  };
-}
-
-function statOrNull(filePath) {
-  try {
-    return fs.statSync(filePath);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Hydrate derived state from a snapshot file, but only when it provably
- * describes the journal as it stands right now. Anything short of an exact byte
- * match on an append-only file means events landed after the snapshot was
- * written, and the caller replays instead.
- */
-function readSnapshotFile(snapshotPath, id, journalBytes) {
-  let parsed;
-  try {
-    parsed = JSON.parse(fs.readFileSync(snapshotPath, 'utf-8'));
-  } catch {
-    return null;
-  }
-  if (!parsed || typeof parsed !== 'object') return null;
-  if (parsed[META_JOURNAL_BYTES] !== journalBytes) return null;
-  if (!Number.isInteger(parsed[META_NEXT_SEQ])) return null;
-  const nextSeq = parsed[META_NEXT_SEQ];
-  delete parsed[META_JOURNAL_BYTES];
-  delete parsed[META_NEXT_SEQ];
-  // The journal owns identity; a snapshot file copied between session ids is
-  // not a reason to answer with the wrong id.
-  if (parsed.id !== id) return null;
-  return { snapshot: { ...baseSnapshot(id), ...parsed }, nextSeq };
-}
-
-function normalizeEvent(event, fallbackId) {
-  if (!event || typeof event !== 'object') throw new Error('event object required');
-  const id = event.id || fallbackId;
-  if (!id || typeof id !== 'string') throw new Error('event id required');
-  if (!event.type || typeof event.type !== 'string') throw new Error('event type required');
-  return { ...event, id };
-}
-
-function getJournalPath(rootDir, id) {
-  return path.join(rootDir, safeSessionId(id) + '.jsonl');
-}
-
-function getSnapshotPath(rootDir, id) {
-  return path.join(rootDir, safeSessionId(id) + '.snapshot.json');
-}
-
-function baseSnapshot(id) {
-  return {
-    id,
-    phase: 'new',
-    pageUrl: null,
-    sourceFile: null,
-    previewFile: null,
-    previewMode: null,
-    expectedVariants: 0,
-    arrivedVariants: 0,
-    visibleVariant: null,
-    paramValues: {},
-    pendingEventSeq: null,
-    pendingEvent: null,
-    deliveryLease: null,
-    checkpointRevision: 0,
-    browserCheckpointRevision: 0,
-    publicationCheckpointRevision: 0,
-    activeOwner: null,
-    sourceMarkers: {},
-    fallbackMode: null,
-    generationPhase: null,
-    generationCompletedAt: null,
-    generationTimings: {},
-    variantPlan: null,
-    generationCanceled: false,
-    generationCanceledAt: null,
-    cancelReason: null,
-    annotationArtifacts: [],
-    // Render truth. `arrivedVariants` says what the agent published; these say
-    // what the browser actually got on screen. They are kept alongside the
-    // published counters rather than replacing them so older readers keep
-    // working, but they are the only fields that answer "did the user ever see
-    // a variant".
-    mountedVariants: [],
-    mountFailures: [],
-    renderState: null,
-    diagnostics: [],
-    updatedAt: null,
-  };
-}
-
-// How many mount failures a session keeps. The card in the browser shows the
-// newest one; the agent needs enough history to spot a variant that fails
-// every republish, not the whole retry storm.
-const MOUNT_FAILURE_HISTORY = 5;
-
-/**
- * `pending` = the agent published and nothing has acked yet, `mounted` = at
- * least one variant reached the DOM, `failed` = the browser reported failures
- * and nothing ever mounted. A single success outranks any number of failures:
- * the user is looking at something.
- */
-function deriveRenderState(snapshot) {
-  if (snapshot.mountedVariants.length > 0) return 'mounted';
-  if (snapshot.mountFailures.length > 0) return 'failed';
-  if (snapshot.generationCompletedAt) return 'pending';
-  return null;
-}
-
-function rebuildSnapshotFromJournal(journalPath, id) {
-  let snapshot = baseSnapshot(id);
-  const diagnostics = [];
-  let nextSeq = 1;
-  if (!fs.existsSync(journalPath)) return { snapshot, diagnostics, nextSeq };
-
-  const lines = fs.readFileSync(journalPath, 'utf-8').split('\n');
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    if (!line.trim()) continue;
-    try {
-      const entry = JSON.parse(line);
-      if (!entry || typeof entry !== 'object') throw new Error('entry is not object');
-      if (Number.isInteger(entry.seq)) nextSeq = Math.max(nextSeq, entry.seq + 1);
-      snapshot = applyEvent(snapshot, entry);
-    } catch (err) {
-      diagnostics.push({
-        error: 'journal_parse_failed',
-        line: i + 1,
-        message: err.message,
-      });
-    }
-  }
-  snapshot.diagnostics = [...snapshot.diagnostics, ...diagnostics];
-  return { snapshot, diagnostics, nextSeq };
-}
-
-function applyEvent(snapshot, entry) {
-  const event = entry.event || entry;
-  const next = {
-    ...snapshot,
-    paramValues: { ...(snapshot.paramValues || {}) },
-    sourceMarkers: { ...(snapshot.sourceMarkers || {}) },
-    generationTimings: { ...(snapshot.generationTimings || {}) },
-    variantPlan: snapshot.variantPlan || null,
-    annotationArtifacts: [...(snapshot.annotationArtifacts || [])],
-    mountedVariants: [...(snapshot.mountedVariants || [])],
-    mountFailures: [...(snapshot.mountFailures || [])],
-    renderState: snapshot.renderState ?? null,
-    diagnostics: [...(snapshot.diagnostics || [])],
-    updatedAt: entry.ts || new Date().toISOString(),
-  };
-
-  switch (event.type) {
-    case 'generate':
-      next.phase = 'generate_requested';
-      next.pageUrl = event.pageUrl ?? next.pageUrl;
-      next.expectedVariants = event.count ?? next.expectedVariants;
-      next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
-      next.pendingEvent = toPendingEvent(event);
-      next.variantPlan = null;
-      // A new cycle publishes new files: everything the browser told us about
-      // the previous batch is now about modules that no longer exist.
-      next.mountedVariants = [];
-      next.mountFailures = [];
-      next.renderState = null;
-      if (event.screenshotPath) upsertArtifact(next.annotationArtifacts, { type: 'screenshot', path: event.screenshotPath });
-      break;
-    case 'variant_plan':
-      if (!next.generationCanceled && !GENERATION_FENCED_PHASES.has(next.phase)) {
-        next.variantPlan = event.plan ?? next.variantPlan;
-      }
-      break;
-    case 'detector_waivers':
-      if (!next.generationCanceled && !GENERATION_FENCED_PHASES.has(next.phase)) {
-        next.detectorWaivers = [
-          ...(next.detectorWaivers || []),
-          ...(Array.isArray(event.waivers) ? event.waivers : []),
-        ];
-      }
-      break;
-    case 'agent_phase':
-      next.generationPhase = event.phase ?? next.generationPhase;
-      if (event.phase) {
-        next.generationTimings[event.phase] = {
-          at: event.at ?? (Date.parse(entry.ts || '') || null),
-          durationMs: event.durationMs ?? null,
-        };
-      }
-      break;
-    case 'variants_ready':
-    case 'agent_done':
-      if ((next.generationCanceled || GENERATION_FENCED_PHASES.has(next.phase))
-          && !(event.type === 'agent_done' && event.carbonize === true && next.phase === 'accept_requested')) {
-        next.diagnostics.push({
-          error: 'late_generation_event_ignored',
-          type: event.type,
-          phase: next.phase,
-        });
-        break;
-      }
-      next.phase = event.carbonize === true ? 'carbonize_required' : 'variants_ready';
-      // Durable completion marker: later browser checkpoints (a resumed page
-      // reporting phase "generating") regress `phase`, but generation staying
-      // finished is monotone — the live server keys missed-`done` redelivery
-      // on this field.
-      next.generationCompletedAt = event.at ?? (Date.parse(entry.ts || '') || Date.now());
-      next.sourceFile = event.sourceFile ?? event.file ?? next.sourceFile;
-      next.previewFile = event.previewFile ?? next.previewFile;
-      next.previewMode = event.previewMode ?? next.previewMode;
-      next.arrivedVariants = event.arrivedVariants ?? (next.expectedVariants || next.arrivedVariants || 0);
-      next.pendingEventSeq = null;
-      next.pendingEvent = null;
-      if (event.carbonize === true) {
-        next.diagnostics.push({
-          error: 'carbonize_cleanup_required',
-          file: event.file || null,
-          message: 'Accepted variant still has carbonize markers that must be folded into source CSS.',
-        });
-      }
-      next.renderState = deriveRenderState(next);
-      break;
-    case 'variant_mounted': {
-      const variant = Number(event.variant);
-      if (!Number.isInteger(variant) || variant < 1) {
-        next.diagnostics.push({ error: 'malformed_mount_ack', type: event.type, variant: event.variant ?? null });
-        break;
-      }
-      if (!next.mountedVariants.includes(variant)) {
-        next.mountedVariants = [...next.mountedVariants, variant].sort((a, b) => a - b);
-      }
-      next.renderState = deriveRenderState(next);
-      break;
-    }
-    case 'variant_mount_failed': {
-      const variant = Number(event.variant);
-      if (!Number.isInteger(variant) || variant < 1) {
-        next.diagnostics.push({ error: 'malformed_mount_ack', type: event.type, variant: event.variant ?? null });
-        break;
-      }
-      next.mountFailures = [
-        ...next.mountFailures,
-        {
-          variant,
-          url: typeof event.url === 'string' ? event.url : null,
-          error: typeof event.error === 'string' ? event.error : null,
-          at: event.at ?? (Date.parse(entry.ts || '') || Date.now()),
-        },
-      ].slice(-MOUNT_FAILURE_HISTORY);
-      next.renderState = deriveRenderState(next);
-      // The failure needs an agent reply, so it must survive a helper
-      // restart the same way a generate does. Never clobber a still-pending
-      // generate: a progressive publish can fail an early mount while the
-      // generate event itself is still leased.
-      if (!next.pendingEvent) {
-        next.pendingEvent = toPendingEvent(event);
-      }
-      break;
-    }
-    case 'checkpoint':
-      if (next.generationCanceled || GENERATION_FENCED_PHASES.has(next.phase)) {
-        next.diagnostics.push({ error: 'checkpoint_after_terminal_ignored', phase: event.phase ?? null, revision: event.revision ?? null });
-        break;
-      }
-      {
-        const revisionDomain = event.revisionDomain === 'publication'
-          || (event.reason === 'variants_progress' && !event.owner)
-          ? 'publication'
-          : 'browser';
-        const revisionField = revisionDomain === 'publication'
-          ? 'publicationCheckpointRevision'
-          : 'browserCheckpointRevision';
-        const currentRevision = next[revisionField]
-          ?? (revisionDomain === 'browser' ? next.checkpointRevision : 0)
-          ?? 0;
-        if ((event.revision ?? 0) >= currentRevision) {
-          next.phase = event.phase ?? next.phase;
-          next[revisionField] = event.revision ?? currentRevision;
-          if (revisionDomain === 'browser') {
-            next.checkpointRevision = event.revision ?? next.checkpointRevision;
-            next.activeOwner = event.owner ?? next.activeOwner;
-          }
-          next.arrivedVariants = event.arrivedVariants ?? next.arrivedVariants;
-          if (revisionDomain === 'browser') next.visibleVariant = event.visibleVariant ?? next.visibleVariant;
-          next.sourceFile = event.sourceFile ?? next.sourceFile;
-          next.previewFile = event.previewFile ?? next.previewFile;
-          next.previewMode = event.previewMode ?? next.previewMode;
-          if (revisionDomain === 'browser' && event.paramValues) next.paramValues = { ...event.paramValues };
-        } else {
-          next.diagnostics.push({ error: 'stale_checkpoint_ignored', revision: event.revision, revisionDomain });
-        }
-      }
-      break;
-    case 'accept':
-    case 'accept_intent':
-      next.phase = 'accept_requested';
-      next.generationCanceled = true;
-      next.generationCanceledAt = event.at ?? (Date.parse(entry.ts || '') || Date.now());
-      next.cancelReason = 'accept';
-      next.visibleVariant = Number(event.variantId ?? next.visibleVariant);
-      if (event.paramValues) next.paramValues = { ...event.paramValues };
-      next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
-      next.pendingEvent = toPendingEvent(event);
-      break;
-    case 'manual_edit_apply':
-      next.phase = 'manual_edit_apply_requested';
-      next.pageUrl = event.pageUrl ?? next.pageUrl;
-      next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
-      next.pendingEvent = toPendingEvent(event);
-      break;
-    case 'steer':
-      next.phase = 'steer_requested';
-      next.pageUrl = event.pageUrl ?? next.pageUrl;
-      next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
-      next.pendingEvent = toPendingEvent(event);
-      break;
-    case 'carbonize_cleanup':
-      next.phase = 'carbonize_cleanup_requested';
-      next.sourceFile = event.file ?? next.sourceFile;
-      next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
-      next.pendingEvent = toPendingEvent(event);
-      break;
-    case 'steer_done':
-      next.phase = 'steer_done';
-      next.sourceFile = event.sourceFile ?? event.file ?? next.sourceFile;
-      next.previewFile = event.previewFile ?? next.previewFile;
-      next.previewMode = event.previewMode ?? next.previewMode;
-      next.message = event.message ?? next.message;
-      next.pendingEventSeq = null;
-      next.pendingEvent = null;
-      break;
-    case 'discard':
-      next.phase = 'discard_requested';
-      next.generationCanceled = true;
-      next.generationCanceledAt = event.at ?? (Date.parse(entry.ts || '') || Date.now());
-      next.cancelReason = 'discard';
-      next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
-      next.pendingEvent = toPendingEvent(event);
-      break;
-    case 'discarded':
-      next.phase = 'discarded';
-      next.pendingEventSeq = null;
-      next.pendingEvent = null;
-      break;
-    case 'complete':
-      next.phase = 'completed';
-      next.sourceFile = event.sourceFile ?? event.file ?? next.sourceFile;
-      next.previewFile = event.previewFile ?? next.previewFile;
-      next.previewMode = event.previewMode ?? next.previewMode;
-      next.pendingEventSeq = null;
-      next.pendingEvent = null;
-      break;
-    case 'agent_error':
-      if (next.generationCanceled && event.sourceEventType === 'generate') {
-        next.diagnostics.push({ error: 'late_generation_event_ignored', type: event.type, phase: next.phase });
-        break;
-      }
-      next.phase = 'agent_error';
-      next.pendingEventSeq = null;
-      next.pendingEvent = null;
-      next.diagnostics.push({ error: 'agent_error', message: event.message || 'unknown agent error' });
-      break;
-    default:
-      next.diagnostics.push({ error: 'unknown_event_type', type: event.type });
-      break;
-  }
-  return next;
-}
-
-function toPendingEvent(event) {
-  const pending = { ...event };
-  delete pending.token;
-  return pending;
-}
-
-function upsertArtifact(artifacts, artifact) {
-  if (!artifacts.some((existing) => existing.path === artifact.path && existing.type === artifact.type)) {
-    artifacts.push(artifact);
-  }
-}
-
-function writeSnapshot(snapshotPath, snapshot, meta) {
-  const payload = {
-    ...snapshot,
-    [META_JOURNAL_BYTES]: meta?.journalBytes ?? -1,
-    [META_NEXT_SEQ]: meta?.nextSeq ?? 1,
-  };
-  fs.writeFileSync(snapshotPath, JSON.stringify(payload, null, 2) + '\n');
-}

package/template/.agents/skills/design/impeccable/scripts/live/source-lock.mjs

@@ -1,105 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { createHash, randomUUID } from 'node:crypto';
-import { getLiveDir, isLiveServerPidReachable } from '../lib/impeccable-paths.mjs';
-
-// Only used to retire a lock whose contents we cannot read (empty or truncated
-// by a crash mid-write). A readable lock's fate is decided by its owner's
-// liveness instead, so a slow critical section is never swept.
-const UNREADABLE_LOCK_STALE_MS = 60_000;
-
-export function sourceLockPath(file, cwd = process.cwd()) {
-  const digest = createHash('sha256').update(path.resolve(cwd, file)).digest('hex').slice(0, 24);
-  return path.join(getLiveDir(cwd), 'locks', digest + '.lock');
-}
-
-export function withSourceLockSync(file, owner, fn, {
-  cwd = process.cwd(),
-  waitMs = 0,
-  retryMs = 5,
-} = {}) {
-  const lockPath = sourceLockPath(file, cwd);
-  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-  const deadline = Date.now() + Math.max(0, Number(waitMs) || 0);
-  // Identifies this acquisition specifically, so release can tell our own lock
-  // from a replacement that some other writer created.
-  const token = randomUUID();
-  let acquired = false;
-
-  while (!acquired) {
-    clearStaleLock(lockPath);
-    let fd;
-    try {
-      fd = fs.openSync(lockPath, 'wx');
-      fs.writeFileSync(fd, JSON.stringify({
-        owner,
-        token,
-        pid: process.pid,
-        at: Date.now(),
-        file: path.resolve(cwd, file),
-      }) + '\n');
-      acquired = true;
-    } catch (error) {
-      if (error?.code !== 'EEXIST') throw error;
-      if (Date.now() >= deadline) {
-        const locked = new Error('source_locked');
-        locked.code = 'SOURCE_LOCKED';
-        locked.lockPath = lockPath;
-        throw locked;
-      }
-      sleepSync(Math.max(1, Math.min(Number(retryMs) || 5, deadline - Date.now())));
-    } finally {
-      try { if (fd !== undefined) fs.closeSync(fd); } catch {}
-    }
-  }
-
-  try {
-    return fn();
-  } finally {
-    releaseOwnLock(lockPath, token);
-  }
-}
-
-function sleepSync(ms) {
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-
-function readLock(lockPath) {
-  try { return JSON.parse(fs.readFileSync(lockPath, 'utf-8')); } catch { return null; }
-}
-
-/**
- * Remove the lock only if it is still the one this call created. If a sweeper
- * judged our lock stale and another writer replaced it, unlinking here would
- * end *their* critical section and admit a third writer to the same file.
- */
-function releaseOwnLock(lockPath, token) {
-  const held = readLock(lockPath);
-  if (held && held.token !== token) return;
-  try { fs.unlinkSync(lockPath); } catch {}
-}
-
-/**
- * A lock is stale when its owner is gone, not when it is old.
- *
- * Age alone cuts both ways: it sweeps a live holder whose critical section
- * outran the timeout (a suspended laptop, a stopped process), letting two
- * writers into the same source file, while still making every accept on a
- * crashed holder's file wait out the full timeout. Asking the OS whether the
- * recorded pid is alive answers both correctly: a dead owner releases at once,
- * and a live owner keeps its lock however long it needs.
- */
-function clearStaleLock(lockPath) {
-  const held = readLock(lockPath);
-  if (!held) {
-    // Unreadable: either a crash truncated it, or we caught the brief window
-    // between create and write in a live acquisition. mtime distinguishes them.
-    try {
-      const stat = fs.statSync(lockPath);
-      if (Date.now() - stat.mtimeMs > UNREADABLE_LOCK_STALE_MS) fs.unlinkSync(lockPath);
-    } catch { /* gone already */ }
-    return;
-  }
-  if (typeof held.pid === 'number' && isLiveServerPidReachable(held.pid)) return;
-  try { fs.unlinkSync(lockPath); } catch {}
-}