gcf-aif-ext 0.4.1 → 0.5.1

package/lib/integrate.js

@@ -0,0 +1,322 @@
+// The integrator (Methodology §7): an item runs in its worktree on branch `work/<id>`, and the
+// branch is ready once its tip carries the trailer `GCF-Verified: <id>` — readiness lives in git,
+// not in memory. `integrate` merges such a branch into main and records the item's move there,
+// under the main lock; without an id it picks up every verified branch a dead run left behind.
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { buildLedger } from './ledger.js';
+import { parse } from './frontmatter.js';
+import { withMainLock } from './main-lock.js';
+import { verifyItem, deltaProblems } from './verify.js';
+import { submitItem, closeItem, blockItem } from './work-ops.js';
+import { isValidId } from './id.js';
+
+const TRAILER = 'GCF-Verified';
+export const branchOf = (id) => `work/${id}`;
+export const worktreeOf = (projectDir, id) =>
+  path.join(path.resolve(projectDir), '.gcf-session', 'worktrees', id);
+
+function git(cwd, args, { check = true } = {}) {
+  const res = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  const err = (res.stderr || res.stdout || '').trim();
+  if (check && res.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${err}`);
+
+  return { ok: res.status === 0, out: (res.stdout ?? '').trim(), err };
+}
+
+/** `.gcf-session/` stays out of `git status` without a tracked .gitignore change. */
+async function excludeSession(projectDir) {
+  const common = path.resolve(projectDir, git(projectDir, ['rev-parse', '--git-common-dir']).out);
+  const file = path.join(common, 'info', 'exclude');
+  const text = existsSync(file) ? await readFile(file, 'utf8') : '';
+  if (text.split(/\r?\n/).includes('/.gcf-session/')) return;
+  await mkdir(path.dirname(file), { recursive: true });
+  await appendFile(file, `${text && !text.endsWith('\n') ? '\n' : ''}/.gcf-session/\n`);
+}
+
+const METRICS = ':(exclude)gcf/.metrics';
+
+/**
+ * Bring the main checkout's branch into a resumed worktree: the operator's answer from
+ * `unblock`, a newer LIVE.md and the other items' states live on main only.
+ */
+function syncWithMain(projectDir, dir) {
+  const main = git(projectDir, ['rev-parse', '--abbrev-ref', 'HEAD']).out;
+  if (main === 'HEAD' || main.startsWith('work/')) return {};
+  const res = git(dir, ['merge', '--no-edit', '-m', `gcf(sync): ${main}`, main], { check: false });
+  if (res.ok) return {};
+  if (git(dir, ['rev-parse', '-q', '--verify', 'MERGE_HEAD'], { check: false }).ok)
+    git(dir, ['merge', '--abort'], { check: false });
+
+  return { sync: `${main} does not merge into the worktree: ${res.err}` };
+}
+
+/**
+ * A worktree for a ready item: `.gcf-session/worktrees/<id>` on branch `work/<id>` from HEAD.
+ * An existing one is resumed with main merged in; `sync` names a merge that did not go.
+ */
+export async function addWorktree(projectDir, id) {
+  if (!isValidId(id)) throw new Error(`${id} is not an item id`);
+  const item = (await buildLedger(projectDir)).item(id);
+  if (!item) throw new Error(`${id} is not a work item of gcf/work/`);
+  const dir = worktreeOf(projectDir, id);
+  if (existsSync(dir))
+    return {
+      id,
+      path: dir,
+      branch: branchOf(id),
+      created: false,
+      ...syncWithMain(projectDir, dir),
+    };
+  if (item.data.status !== 'ready')
+    throw new Error(`${id} is ${item.data.status}: a run starts on a ready item`);
+  await excludeSession(projectDir);
+  // A worktree folder deleted by hand leaves its registration behind: add would refuse.
+  git(projectDir, ['worktree', 'prune']);
+  const ref = `refs/heads/${branchOf(id)}`;
+  const exists = git(projectDir, ['rev-parse', '--verify', '--quiet', ref], { check: false }).ok;
+  const from = exists ? [dir, branchOf(id)] : ['-b', branchOf(id), dir, 'HEAD'];
+  git(projectDir, ['worktree', 'add', ...from]);
+
+  return { id, path: dir, branch: branchOf(id), created: true };
+}
+
+/**
+ * `verify --mark`: the DoD is green on branch `work/<id>` with everything committed — an empty
+ * commit carrying the trailer says so in git. Refuses on red checks or uncommitted work.
+ */
+export async function markVerified(worktreeDir, id, opts = {}) {
+  const branch = git(worktreeDir, ['rev-parse', '--abbrev-ref', 'HEAD']).out;
+  if (branch !== branchOf(id))
+    throw new Error(`${id} is verified on its branch ${branchOf(id)}, this is ${branch}`);
+  if (git(worktreeDir, ['status', '--porcelain', '--', '.', METRICS]).out)
+    throw new Error('commit the work first: the trailer marks a commit, not a working tree');
+  const r = await verifyItem(worktreeDir, id, opts);
+  if (!r.ok) return { ...r, marked: false };
+  const msg = ['-m', `gcf(verified): ${id}`, '-m', `${TRAILER}: ${id}`];
+  git(worktreeDir, ['commit', '--allow-empty', ...msg]);
+
+  return { ...r, marked: true };
+}
+
+function isVerified(projectDir, id) {
+  const format = `--format=%(trailers:key=${TRAILER},valueonly)`;
+  const trailers = git(projectDir, ['log', '-1', format, branchOf(id)], { check: false }).out;
+
+  return trailers.split('\n').some((v) => v.trim() === id);
+}
+
+/** The ids of branches `work/<id>` whose tip carries `GCF-Verified: <id>`. */
+export function verifiedBranches(projectDir) {
+  const refs = git(projectDir, ['for-each-ref', '--format=%(refname:short)', 'refs/heads/work/']);
+
+  return refs.out
+    .split('\n')
+    .filter(Boolean)
+    .map((b) => b.slice('work/'.length))
+    .filter((id) => isVerified(projectDir, id));
+}
+
+/**
+ * Take the worktree and the branch away once the branch is in main (or tagged, for a spike).
+ * Without --force: work left uncommitted in the worktree stops the removal and is named.
+ */
+function cleanUp(projectDir, id, { force = false } = {}) {
+  const notes = [];
+  const dir = worktreeOf(projectDir, id);
+  if (existsSync(dir)) {
+    // The run's own audit and context lines are no work to keep.
+    git(dir, ['checkout', '--', 'gcf/.metrics'], { check: false });
+    git(dir, ['clean', '-fdq', '--', 'gcf/.metrics'], { check: false });
+    const res = git(projectDir, ['worktree', 'remove', dir], { check: false });
+    if (!res.ok) notes.push(`worktree kept: ${res.err}`);
+  }
+
+  git(projectDir, ['worktree', 'prune'], { check: false });
+  const res = git(projectDir, ['branch', force ? '-D' : '-d', branchOf(id)], { check: false });
+  if (!res.ok) notes.push(`branch kept: ${res.err}`);
+
+  return notes.length ? { cleanup: notes } : {};
+}
+
+/** The item file at `rev` without its `live:`: what a branch must leave as main has it. */
+function itemBeyondLive(projectDir, rev, id) {
+  const res = git(projectDir, ['show', `${rev}:./gcf/work/${id}.md`], { check: false });
+  if (!res.ok) return null;
+  const { data, body } = parse(res.out);
+  const { live, ...rest } = data;
+
+  return JSON.stringify([rest, String(body).trim()]);
+}
+
+/**
+ * The branch may change in gcf/ only its own item's `live:` (Methodology §5.2): status, other
+ * items and the config move on main through their commands.
+ */
+function foreignGcfEdits(projectDir, id) {
+  const own = `gcf/work/${id}.md`;
+  const range = `HEAD...${branchOf(id)}`;
+  const changed = git(projectDir, ['diff', '--name-only', range, '--', 'gcf/'])
+    .out.split('\n')
+    .filter((f) => f && f !== own && f !== 'gcf/INDEX.md' && !f.startsWith('gcf/.metrics/'));
+  const base = git(projectDir, ['merge-base', 'HEAD', branchOf(id)]).out;
+  if (itemBeyondLive(projectDir, base, id) !== itemBeyondLive(projectDir, branchOf(id), id))
+    changed.push(`${own} beyond its live:`);
+
+  return changed;
+}
+
+/** Whether the item's move was recorded after its branch merged: a crash may fall in between. */
+function movedSinceMerge(projectDir, id) {
+  const grep = ['--fixed-strings', `--grep=gcf(integrate): ${id}`];
+  const merge = git(projectDir, ['log', '-1', '--format=%H', ...grep]).out;
+  if (!merge) return false;
+  const after = git(projectDir, ['log', '--format=%s', `${merge}..HEAD`]).out.split('\n');
+  const move = new RegExp(`^gcf\\((submit|close|block)\\): ${id}( |$)`);
+
+  return after.some((s) => move.test(s));
+}
+
+/**
+ * The move a merged item ends its run with. Its delta is checked against main first — the
+ * worktree's LIVE.md may be behind. A move the item refuses blocks it with the reason; when even
+ * the block fails, the error goes up and the next integrate records the move again.
+ */
+async function recordMove(projectDir, item) {
+  const { id, gate } = item.data;
+  const stale = await deltaProblems(projectDir, item);
+  try {
+    if (stale.length) throw new Error(stale.join('; '));
+    if (gate === 'auto') return { move: 'close', ...(await closeItem(projectDir, id)) };
+
+    return { move: 'submit', ...(await submitItem(projectDir, id)) };
+  } catch (e) {
+    const reason = `integrate: ${e.message}`;
+
+    return { move: 'block', reason, ...(await blockItem(projectDir, id, { reason })) };
+  }
+}
+
+/** A spike's code never reaches main (§5.5): only its plan does, and a tag keeps the branch. */
+async function integrateSpike(projectDir, item) {
+  const id = String(item.data.id);
+  const plan = item.data.plan ?? `.ai-factory/plans/${id}.md`;
+  if (git(projectDir, ['cat-file', '-e', `${branchOf(id)}:./${plan}`], { check: false }).ok) {
+    git(projectDir, ['checkout', branchOf(id), '--', plan]);
+    // A plan main already holds as it is (a rerun after a crash) has nothing to commit.
+    if (!git(projectDir, ['diff', '--cached', '--quiet', '--', plan], { check: false }).ok)
+      git(projectDir, ['commit', '-m', `gcf(integrate): ${id} plan`, '--only', '--', plan]);
+  }
+
+  git(projectDir, ['tag', '-f', `spike/${id}`, branchOf(id)]);
+  const moved = await recordMove(projectDir, item);
+
+  return { ...moved, ...cleanUp(projectDir, id, { force: true }) };
+}
+
+/** Merge the branch; null when it went in, else the conflict or the refusal. */
+function mergeBranch(projectDir, id) {
+  const args = ['merge', '--no-ff', '--no-edit', '-m', `gcf(integrate): ${id}`, branchOf(id)];
+  const merge = git(projectDir, args, { check: false });
+  if (merge.ok) return null;
+  const head = ['rev-parse', '-q', '--verify', 'MERGE_HEAD'];
+  if (!git(projectDir, head, { check: false }).ok)
+    return { error: `merge of ${branchOf(id)} refused: ${merge.err}` };
+  git(projectDir, ['merge', '--abort'], { check: false });
+
+  return {
+    conflict:
+      `${branchOf(id)} conflicts with main: in its worktree merge main, resolve, run ` +
+      `gcf verify ${id} --mark again, then gcf integrate ${id}`,
+  };
+}
+
+/** A branch main already holds: its move may still be owed, after a crash in between. */
+async function integrateMerged(projectDir, id, item) {
+  if (!item || item.data.status !== 'ready' || movedSinceMerge(projectDir, id))
+    return { id, skipped: `${branchOf(id)} is in main already`, ...cleanUp(projectDir, id) };
+
+  return { id, ...(await recordMove(projectDir, item)), ...cleanUp(projectDir, id) };
+}
+
+async function integrateOne(projectDir, id) {
+  const item = (await buildLedger(projectDir)).item(id);
+  const ancestor = ['merge-base', '--is-ancestor', branchOf(id), 'HEAD'];
+  if (git(projectDir, ancestor, { check: false }).ok) return integrateMerged(projectDir, id, item);
+  if (!item || item.data.status !== 'ready')
+    return { id, skipped: `${id} is ${item ? item.data.status : 'not a work item'} on main` };
+  if (item.data.type === 'spike') return { id, ...(await integrateSpike(projectDir, item)) };
+  const foreign = foreignGcfEdits(projectDir, id);
+  if (foreign.length)
+    return {
+      id,
+      error:
+        `${branchOf(id)} changes gcf/ beyond the item's live: (${foreign.join(', ')}) — take ` +
+        'those edits out of the branch: they reach main through their commands',
+    };
+  const failed = mergeBranch(projectDir, id);
+  if (failed) return { id, ...failed };
+  const moved = await recordMove(projectDir, (await buildLedger(projectDir)).item(id));
+
+  return { id, ...moved, ...cleanUp(projectDir, id) };
+}
+
+/**
+ * Audit and context append to tracked logs in gcf/.metrics on every call: commit them, or a
+ * branch bringing its own lines could not merge over them. Union merge joins the lines.
+ */
+function commitMetrics(projectDir) {
+  const dirty = git(projectDir, [
+    'status',
+    '--porcelain',
+    '--untracked-files=no',
+    '--',
+    'gcf/.metrics',
+  ]);
+  if (dirty.out)
+    git(projectDir, [
+      'commit',
+      '-q',
+      '--no-verify',
+      '-m',
+      'gcf(metrics): run logs',
+      '--only',
+      '--',
+      'gcf/.metrics',
+    ]);
+}
+
+/**
+ * Merge verified branches into main and record each item's move: gate auto closes, the others
+ * submit; a move the item refuses blocks it with the reason. `ids` empty: every verified branch.
+ * One item's failure is reported and the others still go.
+ */
+export async function integrate(projectDir, ids = []) {
+  const branch = git(projectDir, ['rev-parse', '--abbrev-ref', 'HEAD']).out;
+  if (branch === 'HEAD' || branch.startsWith('work/'))
+    throw new Error(`integrate runs in the main checkout on its branch, not on ${branch}`);
+
+  return withMainLock(projectDir, async () => {
+    if (git(projectDir, ['status', '--porcelain', '--untracked-files=no', '--', '.', METRICS]).out)
+      throw new Error('main has uncommitted changes: commit or stash them before integrating');
+    commitMetrics(projectDir);
+    for (const id of ids)
+      if (!isVerified(projectDir, id))
+        throw new Error(
+          `${branchOf(id)} carries no ${TRAILER}: ${id} trailer — run gcf verify ${id} --mark ` +
+            'in its worktree once the DoD is green',
+        );
+    const results = [];
+    for (const id of ids.length ? ids : verifiedBranches(projectDir)) {
+      try {
+        results.push(await integrateOne(projectDir, id));
+      } catch (e) {
+        results.push({ id, error: e.message });
+      }
+    }
+
+    return results;
+  });
+}

package/lib/live.js

@@ -9,53 +9,94 @@ import { atomicWrite } from './safe-path.js';
 import { listItems } from './gcf-paths.js';
 import { summaryProblem } from './validate-item.js';
 
-const SECTIONS = { capabilities: 'capabilities', 'known-issues': 'knownIssues' };
+const SECTIONS = {
+  release: 'release',
+  capabilities: 'capabilities',
+  'known-issues': 'knownIssues',
+};
+const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 const NONE = {
   capabilities: '- none: no capability recorded yet',
   'known-issues': '- none: no known issue',
 };
 
 /** @typedef {{id: string, summary: string, refs?: string}} LiveRecord */
+/** @typedef {{version: string, channel?: string, date?: string, phase?: string}} LiveRelease */
+
+/**
+ * A line of the one-record `release:` block (Methodology §13): the last release, which the end
+ * of the next release item replaces. False when the line is none of the block's lines.
+ */
+function releaseLine(out, line) {
+  const start = line.match(/^- version:\s*(\S+)\s*$/);
+  if (start) {
+    if (out.release) out.problems.push('release: holds one record, the last release');
+    out.release = { version: start[1] };
+
+    return true;
+  }
+
+  const field = line.match(/^ {2}(channel|date|phase):\s*(\S+)\s*$/);
+  if (!field || !out.release) return false;
+  out.release[field[1]] = field[2];
+
+  return true;
+}
 
-/** Parse LIVE.md text: `{capabilities, knownIssues, problems}`. */
+/**
+ * Parse LIVE.md text: `{phase, release, capabilities, knownIssues, problems}`. `phase`
+ * (Methodology §10) sits in the frontmatter, null until the first `gcf phase next`; `release`
+ * is null until a release item ends.
+ */
 export function parseLive(text) {
-  /** @type {{capabilities: LiveRecord[], knownIssues: LiveRecord[], problems: string[]}} */
-  const out = { capabilities: [], knownIssues: [], problems: [] };
-  const body = String(text)
-    .replace(/\r\n/g, '\n')
-    .replace(/^---\n[\s\S]*?\n---\n?/, '');
-  /** @type {'capabilities' | 'knownIssues' | null} */
+  /** @type {{phase: string | null, release: LiveRelease | null, capabilities: LiveRecord[],
+   *   knownIssues: LiveRecord[], problems: string[]}} */
+  const out = { phase: null, release: null, capabilities: [], knownIssues: [], problems: [] };
+  const norm = String(text).replace(/\r\n/g, '\n');
+  const front = norm.match(/^---\n([\s\S]*?)\n---\n?/);
+  const phase = front?.[1].match(/^phase:(.*)$/m)?.[1].trim();
+  if (phase !== undefined && !SLUG.test(phase))
+    out.problems.push(`phase: ${phase} is not a phase name`);
+  else out.phase = phase ?? null;
+  const body = front ? norm.slice(front[0].length) : norm;
+  /** @type {'release' | 'capabilities' | 'knownIssues' | null} */
   let section = null;
   /** @type {LiveRecord | null} */
   let rec = null;
-  body.split('\n').forEach((line, i) => {
-    const head = line.match(/^([a-z-]+):\s*$/);
-    if (head) {
-      section = SECTIONS[head[1]] ?? null;
-      if (!section) out.problems.push(`line ${i + 1}: unknown section ${head[1]}:`);
-      rec = null;
-
-      return;
-    }
-
+  /** A record line of capabilities or known-issues; false when the line is not one. */
+  const recordLine = (line) => {
     const start = line.match(/^- id:\s*(\S+)\s*$/);
     if (start && section) {
       rec = { id: start[1], summary: '' };
       out[section].push(rec);
 
-      return;
+      return true;
     }
 
     const field = line.match(/^ {2}(summary|refs):\s*(.+?)\s*$/);
-    if (field && rec) {
-      rec[field[1]] = field[2];
+    if (!field || !rec) return false;
+    rec[field[1]] = field[2];
+
+    return true;
+  };
+
+  body.split('\n').forEach((line, i) => {
+    const head = line.match(/^([a-z-]+):\s*$/);
+    if (head) {
+      section = SECTIONS[head[1]] ?? null;
+      if (!section) out.problems.push(`line ${i + 1}: unknown section ${head[1]}:`);
+      rec = null;
 
       return;
     }
 
+    if (section === 'release' ? releaseLine(out, line) : recordLine(line)) return;
     if (line.trim() && !/^- none\b/.test(line) && !line.startsWith('#'))
       out.problems.push(`line ${i + 1}: not a record line: ${line.trim()}`);
   });
+  const r = out.release;
+  if (r && !(SLUG.test(r.channel ?? '') && /^\d{4}-\d{2}-\d{2}$/.test(r.date ?? '')))
+    out.problems.push('release: needs version, a slug channel and a YYYY-MM-DD date');
 
   return out;
 }
@@ -66,12 +107,18 @@ const recordText = (r) =>
 const byId = (a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
 
 /** LIVE.md text: records sorted by id, so two branches touching different ids merge cleanly. */
-export function serializeLive({ capabilities, knownIssues }) {
+export function serializeLive({ phase = null, release = null, capabilities, knownIssues }) {
   const block = (key, list) =>
     `${key}:\n${list.length ? [...list].sort(byId).map(recordText).join('\n') : NONE[key]}\n`;
 
   return [
-    '---\ntype: live\n---\n',
+    `---\ntype: live\n${phase ? `phase: ${phase}\n` : ''}---\n`,
+    ...(release
+      ? [
+          `release:\n- version: ${release.version}\n  channel: ${release.channel}\n` +
+            `  date: ${release.date}\n${release.phase ? `  phase: ${release.phase}\n` : ''}`,
+        ]
+      : []),
     block('capabilities', capabilities),
     block('known-issues', knownIssues),
   ].join('\n');
@@ -85,6 +132,18 @@ export async function readLive(root) {
   return parseLive(existsSync(file) ? await readFile(file, 'utf8') : '');
 }
 
+/**
+ * LIVE.md for a command that writes it or acts on its phase: a malformed file refuses, since
+ * rewriting it would drop what the parser could not read.
+ */
+export async function readLiveStrict(root) {
+  const live = await readLive(root);
+  if (live.problems.length)
+    throw new Error(`gcf/LIVE.md: ${live.problems[0]} — fix it by hand in its own commit first`);
+
+  return live;
+}
+
 export async function writeLive(root, live) {
   await atomicWrite(liveFile(root), serializeLive(live));
 }

package/lib/main-lock.js

@@ -0,0 +1,112 @@
+// Writes to main serialize through `.gcf-session/main.lock` (Methodology §7): every committed gcf
+// move and the integrator hold it while they write and commit, so a run and the operator wait for
+// each other instead of committing over each other. Re-entrant along one call chain: `integrate`
+// holds it across the merge and the move it records.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { link, mkdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+
+const chain = new AsyncLocalStorage();
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export const lockFile = (projectDir) =>
+  path.join(path.resolve(projectDir), '.gcf-session', 'main.lock');
+
+const alive = (pid) => {
+  try {
+    process.kill(pid, 0);
+
+    return true;
+  } catch (e) {
+    // EPERM: alive under another user. ESRCH: gone.
+    return e.code === 'EPERM';
+  }
+};
+
+/** The lock's text when its holder is gone, else null. The file appears whole: see `take`. */
+async function staleText(file) {
+  try {
+    const text = await readFile(file, 'utf8');
+    const pid = Number(text.split('\n')[0]);
+    if (Number.isInteger(pid) && pid > 0) return alive(pid) ? null : text;
+
+    // Not ours to read: a lock in some other shape counts as dead only once it is old.
+    return Date.now() - (await stat(file)).mtimeMs > 10000 ? text : null;
+  } catch {
+    return null; // released meanwhile
+  }
+}
+
+/**
+ * Take the lock atomically: the pid goes into a file of its own first, and a hard link puts it
+ * in place whole or fails with EEXIST — no reader ever sees a lock without its pid.
+ */
+async function take(file, token) {
+  const tmp = `${file}.${token}`;
+  await writeFile(tmp, `${process.pid}\n${token}\n`);
+  try {
+    await link(tmp, file);
+
+    return true;
+  } catch (e) {
+    if (e.code !== 'EEXIST') throw e;
+
+    return false;
+  } finally {
+    await unlink(tmp).catch(() => {});
+  }
+}
+
+/**
+ * Move a dead holder's lock aside. shortcut: two takers that judged the same dead lock may race
+ * here — the rename lets one of them win, a fresh lock renamed by the loser is put back.
+ */
+async function clearStale(file, text) {
+  const aside = `${file}.stale-${randomUUID()}`;
+  try {
+    await rename(file, aside);
+  } catch {
+    return;
+  }
+
+  if ((await readFile(aside, 'utf8').catch(() => text)) !== text)
+    await link(aside, file).catch(() => {});
+  await unlink(aside).catch(() => {});
+}
+
+/**
+ * Run `fn` holding the main lock. Waits up to `waitMs` for another holder; a lock whose process
+ * died is taken over.
+ * @template T
+ * @param {string} projectDir
+ * @param {() => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+export async function withMainLock(projectDir, fn, { waitMs = 60000 } = {}) {
+  const file = lockFile(projectDir);
+  const held = chain.getStore() ?? new Set();
+  if (held.has(file)) return fn();
+
+  await mkdir(path.dirname(file), { recursive: true });
+  const token = randomUUID();
+  const until = Date.now() + waitMs;
+  while (!(await take(file, token))) {
+    const dead = await staleText(file);
+    if (dead !== null) await clearStale(file, dead);
+    else if (Date.now() > until)
+      throw new Error(
+        `gcf/ is busy: another gcf move holds ${path.relative(projectDir, file)} — retry when ` +
+          'it ends, or delete the file if no gcf command is running',
+      );
+    else await sleep(100);
+  }
+
+  try {
+    return await chain.run(new Set([...held, file]), fn);
+  } finally {
+    // Only our own lock leaves: one taken over as dead meanwhile belongs to its new holder.
+    const text = await readFile(file, 'utf8').catch(() => '');
+    if (text.includes(token)) await unlink(file).catch(() => {});
+  }
+}