@volter/supercode-orchestrator 0.5.84 → 0.5.86

package/board/git-document.mjs

@@ -7,55 +7,250 @@
 // either side wrote is dropped; a merge that cannot be made stops the push and says why, leaving both texts in the
 // checkout's history.
 //
-// The remote is never waited on (D192): a fetch runs beside the process, and what it brings is merged in one local step
-// on this process's loop, serialized with its writes, as a write's own commit is; a push runs beside the process too.
-// What is owed is git's own state, never a queue in memory: board documents that differ from HEAD are a commit owed,
-// and a HEAD ahead of its upstream is a push owed. A process that ends with either owed leaves it in the checkout, and
-// the next one to open each board derives it again and does it (`derive`): after that board's own recovery has written
-// what its store accepted, over every document the board has (the open one, its archive and each rotated archive).
+// Git is publication, not durability: the board's store and its documents are the record, and a write answers once they
+// are written. Nothing here runs on the caller's loop or waits on it (t_00f071f4: a busy index once held the board
+// owner's loop 5 s). Every git step of a checkout runs beside the process, one at a time on that checkout's chain
+// (`git` through execFile): a write's commit, a fetch's merge, a push check. Those are still git processes, one set per
+// write, off the loop (gap A41). What is owed survives in git's own state: board documents that differ from HEAD are a
+// commit owed, and a HEAD ahead of its upstream is a push owed. In memory is only each owed write's own text, in order,
+// so that each commit holds its write and no other. A commit needs no lock but HEAD's: HEAD moves by compare-and-swap,
+// and the checkout's index follows it after (never ahead), a busy index tried again on a timer and said once it has
+// held the entries a minute. A process that ends with anything owed leaves it in the checkout, and the next one to open
+// each board derives it again and does it (`derive`: documents that differ from HEAD committed, the board documents'
+// index entries moved to HEAD, an unpushed HEAD pushed).
+//
+// Only the board writes its documents. A write's commit is made from that write's own text, through an index of its
+// own (never the checkout's staged files, never a later write's text). What a fetch brings is merged without touching
+// the working tree (`git merge-tree`), a board document both sides changed merged by the board's own document merge;
+// the merged documents are handed to their boards (every board this process holds in the checkout), each of which
+// writes its own as an edit in its next transaction only if each is still what HEAD holds (a write owed goes first,
+// and the next fetch takes what was pushed again); then git's HEAD and index move to the merge. A write that lands
+// between stays a commit owed, never lost.
+// Where the checkout is, its branch and its per-worktree git paths (what `git rev-parse --git-path` names: FETCH_HEAD
+// and the push error live in a linked worktree's own git dir) are read from `.git` itself, so a board open starts no
+// process. A write does start its commit's git processes, beside the loop (A41).
 import { current } from './call.mjs';
 import { execFile, execFileSync, spawn } from 'node:child_process';
-import { readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { basename, dirname, relative } from 'node:path';
-
-const git = (cwd, args, input, timeout = 120_000) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'], ...(input === undefined ? {} : { input }), timeout });
-const quiet = (cwd, args, timeout) => { try { return git(cwd, args, undefined, timeout); } catch { return null; } };
-// Another board process (or the manager's own git) may hold git's index for a moment: its index.lock is waited out, not
-// raced. The board keeps no lock of its own (ADR 0003).
-const indexed = (cwd, args) => {
-  for (let attempt = 0; ; attempt++) {
-    try { return git(cwd, args); } catch (error) {
-      if (attempt >= 20 || !/index\.lock/.test(String(error.stderr ?? error.message))) throw error;
-      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 250);
+import { readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+
+/** git beside the process: its stdout, or a rejection carrying git's stdout and stderr. `input` is written to its stdin;
+ *  `env` is added to this process's. */
+const git = (cwd, args, timeout = 120_000, { input = null, env = null } = {}) => new Promise((done, fail) => {
+  const child = execFile('git', args, { cwd, encoding: 'utf8', timeout, maxBuffer: 64 * 1024 * 1024, windowsHide: true, ...(env ? { env: { ...process.env, ...env } } : {}) }, (error, stdout, stderr) => {
+    if (error) fail(Object.assign(error, { stdout: String(stdout ?? ''), stderr: String(stderr ?? '') })); else done(String(stdout));
+  });
+  if (input !== null) child.stdin.end(input); else child.stdin.end();
+});
+const quiet = (cwd, args, timeout) => git(cwd, args, timeout).catch(() => null);
+const busyIndex = (error) => /index\.lock/.test(String(error?.stderr ?? error?.message ?? ''));
+// a ref git would not move: its lock held by another git step, or HEAD moving under the commit on every try
+const refHeld = (error) => Boolean(error?.refHeld) || /\.lock\b|cannot lock ref|unable to lock/i.test(`${error?.stderr ?? ''} ${error?.message ?? ''}`);
+
+/** The checkout `dir` is in, read from its `.git` (a folder, or a linked worktree's `gitdir:` file): its work tree root,
+ *  its git dir and its common dir. Null outside a checkout. */
+function checkoutOf(dir) {
+  let at; try { at = realpathSync(dir); } catch { return null; }
+  for (;;) {
+    const dotgit = join(at, '.git');
+    let stat = null; try { stat = statSync(dotgit); } catch { /* not here */ }
+    if (stat) {
+      let gitDir = dotgit;
+      if (stat.isFile()) { const named = /^gitdir:\s*(.+)$/m.exec(readFileSync(dotgit, 'utf8')); if (!named) return null; gitDir = resolve(at, named[1].trim()); }
+      let common = gitDir; try { common = resolve(gitDir, readFileSync(join(gitDir, 'commondir'), 'utf8').trim()); } catch { /* its own */ }
+      return { root: at, gitDir, common };
     }
+    const up = dirname(at); if (up === at) return null; at = up;
   }
-};
+}
 
 const FETCH_EVERY_MS = 15_000;
-// A fetch beside the process, the network's part: its result is merged (locally, in one step) when it lands.
-const fetchAside = (cwd, branch, timeout = 120_000) => new Promise((resolve) => execFile('git', ['fetch', '--quiet', 'origin', branch], { cwd, timeout }, (error) => resolve(!error)));
+// A fetch beside the process, the network's part: its result is merged (on the checkout's chain) when it lands.
+const fetchAside = (cwd, branch, timeout = 120_000) => new Promise((done) => execFile('git', ['fetch', '--quiet', 'origin', branch], { cwd, timeout }, (error) => done(!error)));
 const fetching = new Map(); // checkout root → the fetch in flight (one at a time per checkout, in this process)
+const chains = new Map(); // checkout root → its git steps, one at a time
 const derived = new Set(); // boards (by their open document) whose owed commit this process has derived from git's state
 const pushDerived = new Set(); // checkouts whose owed push this process has derived
+const boardsAt = new Map(); // checkout root → the boards (GitDocument) this process holds in it
+const takings = new Map(); // checkout root → what a fetch brought, with its boards until each has written its part
 
-/** The fetches in flight, landed and merged, until none is left: a process that exits after a write awaits this first. */
-export async function settleDocuments() {
-  // until none is left: a verb answered while one landed may have started another
-  while (fetching.size) await Promise.all([...fetching.values()]);
+/** One git step of a checkout, after the ones before it; its failure is said, never thrown into the caller. */
+function onChain(root, step) {
+  const previous = chains.get(root) ?? Promise.resolve();
+  const next = previous.then(step).catch((error) => { current().err(`board: ${error.message}\n`); });
+  chains.set(root, next);
+  next.finally(() => { if (chains.get(root) === next) chains.delete(root); });
+  return next;
 }
+
+/** How long a process that is ending waits for its git steps to land. What is still owed then stays in git's state (a
+ *  document that differs from HEAD, a HEAD ahead of its upstream) for the next process to derive. */
+const SETTLE_MS = 10_000;
+
+/** Every fetch and git step in flight, landed, until none is left or SETTLE_MS has passed: a process that exits after a
+ *  write awaits this first. A commit waiting out a busy index is not waited for: it stays owed, said. */
+export async function settleDocuments(within = SETTLE_MS) {
+  const deadline = Date.now() + within;
+  // until none is left: a step that ran may have queued another (a commit its push follows); a retry whose timer fires
+  // meanwhile joins the chain and is waited for too
+  while (fetching.size || chains.size) {
+    const left = deadline - Date.now();
+    if (left <= 0) { current().err(`board: ${chains.size + fetching.size} git step(s) of the board documents were still running as this process ended; what they owed stays in the checkout for the next process\n`); break; }
+    await Promise.race([Promise.all([...fetching.values(), ...chains.values()]), new Promise((done) => setTimeout(done, left).unref?.())]);
+  }
+  // then what still waits on a timer, said: after the chains, so a retry a step set while settling is said too
+  for (const boards of boardsAt.values()) for (const board of boards) if (board.retryTimer) {
+    clearTimeout(board.retryTimer); board.retryTimer = null;
+    current().err(`board: ${board.owed.length} write${board.owed.length === 1 ? '' : 's'} of the board documents not committed as this process ends (git would not move HEAD); ${board.owed.length === 1 ? 'it stays' : 'they stay'} owed in the checkout (documents that differ from HEAD) for the next process\n`);
+  }
+  for (const [root, moves] of filesOwed) if (moves.timer) { clearTimeout(moves.timer); moves.timer = null; current().err(`board: ${moves.files.size} file(s) in ${root} still differ from HEAD as this process ends (what was pushed, not yet written there); the next process to open a board there writes them\n`); }
+  for (const [root, sync] of indexOwed) if (sync.timer) {
+    clearTimeout(sync.timer); sync.timer = null;
+    current().err(`board: git's index in ${root} is still locked as this process ends; its board documents' index entries stay behind HEAD until the next process opens the board\n`);
+  }
+}
+/** How long a busy index may hold an index sync before it is said (with its age), once per stretch. */
+const BUSY_SAID_MS = 60_000;
+// checkout root → { paths, since, said, delay, timer }: board documents whose entries in the checkout's index are to be
+// moved to HEAD (after a commit or a take moved HEAD), waiting out a busy index.
+const indexOwed = new Map();
+
+/** The checkout's index told these paths are as HEAD has them (a path HEAD lacks leaves the index), on the chain. HEAD
+ *  moves first, by compare-and-swap; the index follows, so it is never ahead of HEAD. A busy index is tried again on a
+ *  timer, from 250 ms doubling to 30 s, and said with its age once it has held the sync a minute. */
+function syncIndex(root, paths) {
+  const sync = indexOwed.get(root) ?? { paths: new Set(), since: null, said: false, delay: 0, timer: null };
+  indexOwed.set(root, sync);
+  for (const path of paths) sync.paths.add(path);
+  if (!sync.timer) onChain(root, () => syncNow(root));
+}
+async function syncNow(root) {
+  const sync = indexOwed.get(root);
+  if (!sync || !sync.paths.size) return;
+  const paths = [...sync.paths];
+  try { await git(root, ['reset', '-q', 'HEAD', '--', ...paths]); }
+  catch (error) {
+    if (!busyIndex(error)) { indexOwed.delete(root); throw new Error(`the index entries of ${paths.slice(0, 3).join(', ')} could not be moved to HEAD: ${error.message.split('\n')[0]}`); }
+    sync.since ??= Date.now();
+    if (!sync.said && Date.now() - sync.since >= BUSY_SAID_MS) {
+      sync.said = true;
+      current().err(`board: git's index in ${root} has been locked for ${Math.round((Date.now() - sync.since) / 1000)} s (its index.lock: another git process, or one that ended holding it); ${paths.length} board document index entr${paths.length === 1 ? 'y stays' : 'ies stay'} behind HEAD until it frees\n`);
+    }
+    sync.delay = Math.min(30_000, Math.max(250, (sync.delay || 125) * 2));
+    sync.timer = setTimeout(() => { sync.timer = null; onChain(root, () => syncNow(root)); }, sync.delay);
+    sync.timer.unref?.();
+    return;
+  }
+  for (const path of paths) sync.paths.delete(path);
+  if (!sync.paths.size) indexOwed.delete(root);
+}
+
+// checkout root → { files: Map(path → { from, to }), since, said, delay, timer }: working files a take moved HEAD past,
+// to be written from `to` (or removed, when `to` lacks them), each only while it is still `from`'s text.
+const filesOwed = new Map();
+
+/** The working files a take changed, brought to what HEAD now holds, on the chain: each only while the file is still
+ *  what the commit before the take held (a file changed here since is left, said). One that fails is tried again on a
+ *  timer, said with its age after a minute. */
+function moveFiles(root, files, from, to) {
+  const moves = filesOwed.get(root) ?? { files: new Map(), since: null, said: false, delay: 0, timer: null };
+  filesOwed.set(root, moves);
+  // a file a second take moves again keeps the base of the first: its working text is still that one's until written
+  for (const file of files) moves.files.set(file, { from: moves.files.get(file)?.from ?? from, to });
+  keepMoves(root);
+  if (!moves.timer) onChain(root, () => moveNow(root));
+}
+/** The moves still owed, kept in the checkout's git dir until each is written: a process that ends first leaves them for
+ *  the next one to open a board there (`derive`). */
+const movesPath = (root) => { const checkout = checkoutOf(root); return checkout ? join(checkout.gitDir, 'supercode-board-moves.json') : null; };
+function keepMoves(root) {
+  const path = movesPath(root); if (!path) return;
+  const moves = filesOwed.get(root);
+  try {
+    if (!moves?.files.size) rmSync(path, { force: true });
+    else writeAtomically(path, JSON.stringify(Object.fromEntries(moves.files)));
+  } catch (error) { current().err(`board: the moves owed in ${root} could not be kept (${error.message}); a process that ends before they are written leaves those files differing from HEAD\n`); }
+}
+/** Moves an earlier process left owed, queued again (once per checkout per process). */
+function deriveMoves(root) {
+  const path = movesPath(root); if (!path) return;
+  let kept = null; try { kept = JSON.parse(readFileSync(path, 'utf8')); } catch { return; }
+  for (const [file, { from, to }] of Object.entries(kept ?? {})) if (from && to) moveFiles(root, [file], from, to);
+}
+async function moveNow(root) {
+  const moves = filesOwed.get(root);
+  if (!moves) return;
+  let failed = null;
+  for (const [file, { from, to }] of [...moves.files]) {
+    try {
+      const was = (await quiet(root, ['rev-parse', '-q', '--verify', `${from}:${file}`]))?.trim() || null;
+      let exists = true; try { statSync(join(root, file)); } catch { exists = false; }
+      const now = exists ? (await git(root, ['hash-object', '--', file])).trim() : null;
+      if (now !== was) {
+        // already what the take brought (written before a process ended): done; else changed here since, left and said
+        const brought = (await quiet(root, ['rev-parse', '-q', '--verify', `${to}:${file}`]))?.trim() || null;
+        if (now !== brought) current().err(`board: ${file} in ${root} changed here since what was pushed was merged; it is left as it is (HEAD has the pushed text)\n`);
+        // written before a process ended whose index sync was still owed: the index entry follows HEAD now (a file HEAD
+        // lacks leaves the index, so it is not left staged against HEAD)
+        else await git(root, ['reset', '-q', 'HEAD', '--', file]);
+        moves.files.delete(file); continue;
+      }
+      const kept = Boolean((await quiet(root, ['rev-parse', '-q', '--verify', `${to}:${file}`]))?.trim());
+      if (kept) await git(root, ['checkout', to, '--', file]);
+      else {
+        // the index entry first (a busy index retries with the file still in place), then the file
+        await git(root, ['rm', '--cached', '-q', '--ignore-unmatch', '--', file]);
+        rmSync(join(root, file), { force: true });
+      }
+      moves.files.delete(file);
+    } catch (error) { failed ??= error; }
+  }
+  keepMoves(root);
+  if (!moves.files.size) { filesOwed.delete(root); return; }
+  moves.since ??= Date.now();
+  if (!moves.said && Date.now() - moves.since >= BUSY_SAID_MS) {
+    moves.said = true;
+    current().err(`board: ${moves.files.size} file(s) in ${root} have differed from HEAD for ${Math.round((Date.now() - moves.since) / 1000)} s since what was pushed was taken (${failed?.message.split('\n')[0]}); tried again until written\n`);
+  }
+  moves.delay = Math.min(30_000, Math.max(250, (moves.delay || 125) * 2));
+  moves.timer = setTimeout(() => { moves.timer = null; onChain(root, () => moveNow(root)); }, moves.delay);
+  moves.timer.unref?.();
+}
+
+/** Whether this git can merge without a working tree (`merge-tree --write-tree`, git 2.38): asked once per process,
+ *  beside the loop, on the first take; an older git is said once and nothing pushed is taken. */
+let mergeTreeAble = null;
+async function canMergeTree(root) {
+  if (mergeTreeAble === null) {
+    const version = /(\d+)\.(\d+)/.exec((await quiet(root, ['version'])) ?? '');
+    mergeTreeAble = Boolean(version) && (Number(version[1]) > 2 || (Number(version[1]) === 2 && Number(version[2]) >= 38));
+    if (!mergeTreeAble) current().err(`board: this git (${version ? version[0] : 'its version unread'}) is older than 2.38 and cannot merge without a working tree; what others pushed to the board documents is not taken until git is updated\n`);
+  }
+  return mergeTreeAble;
+}
+
 /** The background push: `git push`, then its error kept for `behind()` (or the last one cleared when it landed). */
 const PUSH = `const {spawnSync}=require('node:child_process'),fs=require('node:fs');const [branch,failure,temporary]=process.argv.slice(1);
 const r=spawnSync('git',['push','--quiet','origin','HEAD:'+branch],{encoding:'utf8',windowsHide:true});
 try{if(r.status===0)fs.rmSync(failure,{force:true});else{fs.writeFileSync(temporary,String(r.stderr||r.error||'push failed'));fs.renameSync(temporary,failure);}}catch{}`;
-/** When this checkout last asked its remote (git writes FETCH_HEAD on every fetch, whichever process ran it). */
-const fetchedAt = (root) => { try { return statSync(git(root, ['rev-parse', '--git-path', 'FETCH_HEAD']).trim().replace(/^(?!\/)/, `${root}/`)).mtimeMs; } catch { return 0; } };
 
 export class GitDocument {
   constructor(paths, merge) {
     this.paths = paths;
     this.cwd = dirname(paths[0]);
-    this.root = quiet(this.cwd, ['rev-parse', '--show-toplevel'])?.trim() ?? null;
+    this.checkout = checkoutOf(this.cwd);
+    this.root = this.checkout?.root ?? null;
     this.merge = merge; // (base, theirs, ours, path) => text | null, ztrack's mergeBoardDocument
+    this.owed = []; // the writes whose commit is owed: { doer, message, files }
+    if (this.root !== null) { if (!boardsAt.has(this.root)) boardsAt.set(this.root, new Set()); boardsAt.get(this.root).add(this); }
+  }
+
+  /** The board closed: it is no longer one of its checkout's boards, and a take still waiting on it is given up. */
+  release() {
+    this.onTaken = null;
+    boardsAt.get(this.root)?.delete(this);
+    const taking = takings.get(this.root);
+    if (taking?.handed.has(this) && !taking.applied.has(this)) abandon(taking);
   }
 
   /** Whether this board's owed commit is still to be derived in this process (its board calls `derive` after its first
@@ -69,25 +264,36 @@ export class GitDocument {
     if (!this.usable) return;
     derived.add(this.paths[0]);
     this.commitDirty('board: documents written before this process started');
+    // an earlier process that moved HEAD and ended before the index followed: the entries are moved now
+    syncIndex(this.root, this.paths.map((path) => this.rel(path)));
     if (pushDerived.has(this.root)) return;
     pushDerived.add(this.root);
+    deriveMoves(this.root);
     const branch = this.branch();
-    if (branch && this.unpushed(branch) && !this.pushing) this.pushInBackground(branch);
+    if (branch) onChain(this.root, async () => { if (await this.unpushed(branch) && !this.pushing) this.pushInBackground(branch); });
   }
 
-  /** This board's documents that differ from HEAD, committed as the board (a recovery's writes are no doer's). */
+  /** This board's documents that differ from HEAD, committed as the board (a recovery's writes are no doer's), with
+   *  their text as it is now: a later write's text is that write's own commit, never this one's. */
   commitDirty(message) {
     if (!this.usable) return;
-    if (quiet(this.root, ['status', '--porcelain', '--', ...this.paths.map((path) => this.rel(path))])?.trim()) this.commit(null, message);
+    this.commit(null, message, this.paths.map((path) => ({ path, text: readText(path) })));
   }
 
   get usable() { return this.root !== null; }
-  rel(path) { return relative(this.root, path); }
-  /** The checkout's branch, or null on no branch (a detached HEAD has nowhere to push and nothing to pull). */
+  rel(path) {
+    let real = path; try { real = join(realpathSync(dirname(path)), basename(path)); } catch { /* not written yet */ }
+    return relative(this.root, real);
+  }
+  /** The checkout's branch, or null on no branch (a detached HEAD has nowhere to push and nothing to pull): its HEAD file. */
   branch() {
-    const name = git(this.root, ['rev-parse', '--abbrev-ref', 'HEAD']).trim();
-    return name && name !== 'HEAD' ? name : null;
+    try { const head = readFileSync(join(this.checkout.gitDir, 'HEAD'), 'utf8').trim(); return /^ref: refs\/heads\/(.+)$/.exec(head)?.[1] ?? null; } catch { return null; }
   }
+  /** When this checkout last asked its remote (git writes FETCH_HEAD on every fetch, whichever process ran it). */
+  // FETCH_HEAD is the checkout's own (a linked worktree's in its git dir, as `git rev-parse --git-path` says), and so is
+  // the push error this keeps beside it.
+  fetchedAt() { try { return statSync(join(this.checkout.gitDir, 'FETCH_HEAD')).mtimeMs; } catch { return 0; } }
+  failurePath() { return join(this.checkout.gitDir, 'supercode-board-push.err'); }
 
   /** Said once per process: a checkout on no branch keeps its commits here (every write tried to push `HEAD:HEAD`
    *  three times, with a fetch and a merge between, and failed: seconds of network on each write, t_23e47b73). */
@@ -96,67 +302,127 @@ export class GitDocument {
     this.warnedDetached = true;
   }
 
-  // Before a write: take what was pushed, so a merged pull request's edit is the document the write starts from. The
-  // remote is asked at most every FETCH_EVERY_MS (git's own FETCH_HEAD is the stamp, so every board process shares it):
-  // a fetch on every write put a network round trip on each one. A checkout holding commits its background push did
-  // not land (refused: something was pushed meanwhile) takes what was pushed now and pushes before writing again.
+  // Before a write: take what was pushed, so a merged pull request's edit reaches the document. The remote is asked at
+  // most every FETCH_EVERY_MS (git's own FETCH_HEAD is the stamp, so every board process shares it), beside the write:
+  // what it brings is merged on the checkout's chain when it lands, and the board's next read takes the document.
   pull() {
     if (!this.usable) return;
-    // Every board transaction pulls (about a hundred a dispatcher round): inside the fetch interval nothing is read,
-    // not even the branch, so a round no longer spends seconds on git subprocesses that decide nothing.
-    if (Date.now() - fetchedAt(this.root) < FETCH_EVERY_MS) return;
+    if (Date.now() - this.fetchedAt() < FETCH_EVERY_MS) return;
     const branch = this.branch();
     if (!branch) return this.detached();
     this.fetchThenTake(branch);
   }
 
-  /** The fetch beside the process; when it lands, what was pushed is taken (take) in one local step. One at a time. */
+  /** The fetch beside the process; when it lands, what was pushed is taken (take) on the chain. One at a time. */
   fetchThenTake(branch, timeout) {
     if (fetching.has(this.root)) return fetching.get(this.root);
     const root = this.root;
     const landing = fetchAside(root, branch, timeout).then((fetched) => {
       if (!fetched) return; // offline: a later write asks again
-      try { this.take(branch); } catch (error) { current().err(`board: ${error.message}\n`); }
+      return onChain(root, () => this.take(branch));
     }).finally(() => fetching.delete(root));
     fetching.set(root, landing);
     return landing;
   }
 
-  /** After a fetch: what was pushed merged into this checkout (local, serialized with this process's writes), then a
-   *  push of what this checkout holds that the remote lacks, beside the process. */
-  take(branch) {
-    const behind = Number(git(this.root, ['rev-list', '--count', `HEAD..origin/${branch}`]).trim());
-    if (behind > 0) {
-      const dirty = git(this.root, ['status', '--porcelain', '--', ...this.paths.map((path) => this.rel(path))]).trim();
-      if (dirty) return; // a write's documents are not committed yet: its commit is owed, and the next fetch takes this
-      this.integrate(branch, 'board');
-    }
-    if (this.unpushed(branch) && !this.pushing) this.pushInBackground(branch);
+  /** After a fetch: what was pushed taken (integrate), then a push of what this checkout holds that the remote lacks,
+   *  beside the process. */
+  async take(branch) {
+    const head = (await git(this.root, ['rev-parse', 'HEAD'])).trim();
+    const theirs = (await git(this.root, ['rev-parse', `origin/${branch}`])).trim();
+    const behind = Number((await git(this.root, ['rev-list', '--count', `${head}..${theirs}`])).trim());
+    if (behind > 0) await this.integrate(branch, head, theirs);
+    if (await this.unpushed(branch) && !this.pushing) this.pushInBackground(branch);
     this.refreshLateness();
   }
 
-  // After a write: commit the board documents as their doer, then push, taking anything pushed meanwhile.
-  commit(doer, message) {
+  // After a write: its commit is owed, made from the write's own text (`files`, its rendered documents; a recovery's or
+  // an earlier process's has none, and commits the documents as they are), as its doer, then pushed, beside the process.
+  commit(doer, message, files = null) {
     if (!this.usable) return;
-    // Only documents that exist or are tracked: the archive is written when a card first ends, and a pathspec naming a
-    // file git does not know fails the whole commit.
-    const files = this.paths.map((path) => this.rel(path)).filter((file) => quiet(this.root, ['ls-files', '--error-unmatch', file]) !== null || readable(`${this.root}/${file}`));
-    if (!files.length) return;
-    indexed(this.root, ['add', '--', ...files]);
-    if (!git(this.root, ['diff', '--cached', '--name-only', '--', ...files]).trim()) return;
-    const who = doer || 'board';
-    indexed(this.root, ['-c', `user.name=${who}`, '-c', 'user.email=board@supercode.invalid', 'commit', '--quiet', '--author', `${who} <board@supercode.invalid>`, '-m', message, '--', ...files]);
+    this.owed.push({ doer: doer || null, message, files: files ? files.map((file) => ({ path: file.path, text: file.text })) : null });
+    if (this.owed.length === 1) this.owedSince = Date.now();
+    if (this.owed.length === 1 && !this.retryTimer) onChain(this.root, () => this.commitOwed());
+  }
+
+  /** Each owed write committed in order, each as its own commit (none needs the checkout's index: a busy one holds
+   *  only the index's following, syncIndex). */
+  async commitOwed() {
+    let made = 0, held = null;
+    while (this.owed.length) {
+      try { if (await this.commitOne(this.owed[0])) made += 1; }
+      catch (error) {
+        // a ref git holds locked (HEAD.lock, a branch's lock), or a HEAD that kept moving: the write stays owed, in order
+        if (refHeld(error)) { held = error; break; }
+        // said, and the writes after it still committed: its documents stay owed in git's state (they differ from HEAD)
+        current().err(`board: a write of the board documents could not be committed (${error.message.split('\n')[0]}); its documents stay owed in the checkout\n`);
+      }
+      this.owed.shift();
+    }
+    if (held) this.waitOutRef(held);
+    else { this.owedSince = null; this.refSince = null; this.refSaid = false; this.refDelay = 0; }
     this.refreshLateness();
+    if (!made) return;
     const branch = this.branch();
     if (!branch) return this.detached();
-    // The push leaves the write's path: the commit is the write, and a push the remote refuses is taken up by the next
-    // write's pull (unpushed commits), which merges what was pushed and pushes before it writes.
-    // While it runs, this process's next write does not push the same commits beside it.
-    // Writes that land while it runs are one more push after it (a burst publishes in two pushes, not one per write).
+    // The push leaves the write's path: the commit is the write's publication, and a push the remote refuses is taken
+    // up by the next fetch (unpushed commits), which merges what was pushed and pushes. While a push runs, the next
+    // commit does not push the same commits beside it: one more push after it (a burst publishes in two pushes).
     if (this.pushing) { this.again = true; return; }
     this.pushInBackground(branch);
   }
 
+  /** git would not move HEAD (its ref locked, or moving under the commit): the owed writes are tried again on a timer,
+   *  from 250 ms doubling to 30 s, and said with how long once they have waited a minute. */
+  waitOutRef(error) {
+    this.refSince ??= Date.now();
+    if (!this.refSaid && Date.now() - this.refSince >= BUSY_SAID_MS) {
+      this.refSaid = true;
+      current().err(`board: ${this.owed.length} write${this.owed.length === 1 ? '' : 's'} of the board documents not committed for ${Math.round((Date.now() - this.refSince) / 1000)} s: git would not move HEAD in ${this.root} (${error.message.split('\n')[0]}); ${this.owed.length === 1 ? 'it stays' : 'they stay'} owed, tried again until it does\n`);
+    }
+    this.refDelay = Math.min(30_000, Math.max(250, (this.refDelay || 125) * 2));
+    this.retryTimer = setTimeout(() => { this.retryTimer = null; onChain(this.root, () => this.commitOwed()); }, this.refDelay);
+    this.retryTimer.unref?.();
+  }
+
+  /** One write's commit: its documents' text written as blobs, through an index of this process's own read from HEAD
+   *  (the checkout's staged files never join it), committed as its doer; HEAD moved only if it is where the commit was
+   *  made (another commit came first: made again on the new HEAD), and then the checkout's index told these documents
+   *  are as committed. Answers whether a commit was made. */
+  async commitOne(write, tries = 3) {
+    const { doer, message, files } = write;
+    const who = doer || 'board';
+    const texts = (files ?? this.paths.map((path) => ({ path, text: readText(path) }))).filter((file) => file.text !== null);
+    if (!texts.length) return false;
+    const head = (await quiet(this.root, ['rev-parse', '--verify', '-q', 'HEAD']))?.trim() || null;
+    const index = join(this.checkout.gitDir, `supercode-board-index.${process.pid}`);
+    let moved = false;
+    try {
+      const own = { GIT_INDEX_FILE: index };
+      await git(this.root, head ? ['read-tree', head] : ['read-tree', '--empty'], 120_000, { env: own });
+      const entries = [];
+      for (const { path, text } of texts) {
+        const rel = this.rel(path);
+        const blob = (await git(this.root, ['hash-object', '-w', '--stdin'], 120_000, { input: text })).trim();
+        entries.push({ rel, blob });
+        await git(this.root, ['update-index', '--add', '--cacheinfo', `100644,${blob},${rel}`], 120_000, { env: own });
+      }
+      const tree = (await git(this.root, ['write-tree'], 120_000, { env: own })).trim();
+      if (head && tree === (await git(this.root, ['rev-parse', `${head}^{tree}`])).trim()) return false;
+      const commit = (await git(this.root, ['commit-tree', tree, ...(head ? ['-p', head] : []), '-m', message], 120_000, { env: author(who) })).trim();
+      try { await git(this.root, ['update-ref', '-m', `board: ${message.split('\n')[0]}`, 'HEAD', commit, head ?? '0'.repeat(40)]); }
+      catch (error) {
+        const now = (await quiet(this.root, ['rev-parse', '--verify', '-q', 'HEAD']))?.trim() || null;
+        if (now === head) throw error; // HEAD where it was: its ref was refused (a lock), said by the caller
+        if (tries <= 1) throw Object.assign(new Error('HEAD moved under the commit on every try'), { refHeld: true });
+        moved = true;
+      }
+      if (!moved) syncIndex(this.root, entries.map(({ rel }) => rel));
+    } finally { rmSync(index, { force: true }); }
+    // HEAD moved under it (another commit, or a take): the same write made again on the new HEAD
+    return moved ? this.commitOne(write, tries - 1) : true;
+  }
+
   /** `git push` beside the process, outliving it. Its refusal is kept where `behind()` reads it, and cleared by a push
    *  that lands. */
   pushInBackground(branch) {
@@ -175,86 +441,181 @@ export class GitDocument {
     pushing.unref();
   }
 
-  failurePath() {
-    return git(this.root, ['rev-parse', '--git-path', 'supercode-board-push.err']).trim().replace(/^(?!\/)/, `${this.root}/`);
-  }
-
-  /** The board documents' publish when it is behind: commits the remote lacks, the oldest one's time and the last push's
-   *  error; null when the remote has everything (or this checkout pushes nowhere). Local reads only, no network. */
   /** A held board's lateness: read once beside the owner's loop, then again after each of its own commits, pushes and
    *  takes (refreshLateness), never by spawning git on an open. `lateness` is that reading (null while none is owed). */
   holdLateness() { this.heldLate = true; this.lateness = null; this.refreshLateness(); }
   refreshLateness() {
     if (!this.heldLate || !this.usable) return;
     if (this.lateReading) { this.lateAgain = true; return; }
-    const root = this.root;
-    const run = (args) => new Promise((resolve) => execFile('git', args, { cwd: root, timeout: 30_000 }, (error, out) => resolve(error ? null : String(out))));
     this.lateReading = (async () => {
-      const name = (await run(['rev-parse', '--abbrev-ref', 'HEAD']))?.trim();
-      if (!name || name === 'HEAD') return null;
-      const times = ((await run(['log', '--format=%ct', `origin/${name}..HEAD`])) ?? '').trim().split('\n').filter(Boolean).map(Number);
-      if (!times.length) return null;
-      const failure = (await run(['rev-parse', '--git-path', 'supercode-board-push.err']))?.trim().replace(/^(?!\/)/, `${root}/`);
+      const name = this.branch();
+      if (!name) return null;
+      const times = ((await quiet(this.root, ['log', '--format=%ct', `origin/${name}..HEAD`], 30_000)) ?? '').trim().split('\n').filter(Boolean).map(Number);
+      // writes not committed yet (a busy index holding them), as well as commits not pushed
+      const uncommitted = this.owed.length ? { writes: this.owed.length, since: this.owedSince ?? Date.now() } : null;
+      if (!times.length && !uncommitted) return null;
       let error = null;
-      try { error = failure ? readFileSync(failure, 'utf8').split('\n').map((line) => line.replace(/\s+/g, ' ').trim()).find(Boolean) ?? null : null; } catch { /* none recorded */ }
-      return { commits: times.length, since: Math.min(...times) * 1000, error };
+      try { error = readFileSync(this.failurePath(), 'utf8').split('\n').map((line) => line.replace(/\s+/g, ' ').trim()).find(Boolean) ?? null; } catch { /* none recorded */ }
+      return { commits: times.length, since: times.length ? Math.min(...times) * 1000 : null, error, uncommitted };
     })().then((late) => { this.lateness = late; }, () => {}).finally(() => {
       this.lateReading = null;
       if (this.lateAgain) { this.lateAgain = false; this.refreshLateness(); }
     });
   }
 
+  /** The board documents' publish when it is behind, for a one-off board open (a CLI process, never the owner, whose
+   *  boards are held and read `lateness`): commits the remote lacks, the oldest one's time and the last push's error, and
+   *  documents that differ from HEAD (a commit owed: an earlier process ended, or a busy index held it, before it was
+   *  made); null when nothing is owed (or this checkout pushes nowhere). Local reads only, no network. */
   behind() {
     if (!this.usable) return null;
     const branch = this.branch();
     if (!branch) return null;
-    const times = (quiet(this.root, ['log', '--format=%ct', `origin/${branch}..HEAD`]) ?? '').trim().split('\n').filter(Boolean).map(Number);
-    if (!times.length) return null;
+    const run = (args) => { try { return execFileSync('git', args, { cwd: this.root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 30_000 }); } catch { return ''; } };
+    const times = run(['log', '--format=%ct', `origin/${branch}..HEAD`]).trim().split('\n').filter(Boolean).map(Number);
+    const owed = run(['status', '--porcelain', '--', ...this.paths.map((path) => this.rel(path))]).trim().split('\n').filter(Boolean).length;
+    if (!times.length && !owed) return null;
     let error = null;
     try { error = readFileSync(this.failurePath(), 'utf8').split('\n').map((line) => line.replace(/\s+/g, ' ').trim()).find(Boolean) ?? null; } catch { /* none recorded */ }
-    return { commits: times.length, since: Math.min(...times) * 1000, error };
+    return { commits: times.length, since: times.length ? Math.min(...times) * 1000 : null, error, uncommitted: owed ? { documents: owed, since: null } : null };
   }
 
   /** The board's round: publish what an earlier write committed and the remote has not taken (a refused or failed
-   *  background push), with the same merge and three attempts a write's pull uses. */
+   *  background push), with the same merge a write's pull uses; beside the round. */
   publishPending() {
     if (!this.usable || this.pushing) return;
     const branch = this.branch();
-    if (!branch || !this.unpushed(branch)) return;
-    // A remote that hangs costs this fetch 15 s, beside the round, never the round.
-    this.fetchThenTake(branch, 15_000);
+    if (!branch) return;
+    onChain(this.root, async () => {
+      // A remote that hangs costs this fetch 15 s, beside the round, never the round.
+      if (await this.unpushed(branch)) this.fetchThenTake(branch, 15_000);
+    });
   }
 
   /** Whether this checkout holds board commits the remote does not have. */
-  unpushed(branch) {
-    return Number(quiet(this.root, ['rev-list', '--count', `origin/${branch}..HEAD`])?.trim() || 0) > 0;
+  async unpushed(branch) {
+    return Number((await quiet(this.root, ['rev-list', '--count', `origin/${branch}..HEAD`]))?.trim() || 0) > 0;
   }
 
-  // Take what was pushed with a merge: it works beside the other edits in this checkout (the manager's own files), which
-  // a rebase refuses. A board document both sides changed is merged by the board's own document merge; any other
-  // conflict leaves the checkout as it was and says so.
-  integrate(branch, who) {
-    const merged = (() => { try { git(this.root, ['-c', `user.name=${who}`, '-c', 'user.email=board@supercode.invalid', 'merge', '--no-edit', '--quiet', `origin/${branch}`]); return true; } catch (error) { return String(error.stderr ?? error.message); } })();
-    if (merged === true) return;
-    const conflicted = git(this.root, ['diff', '--name-only', '--diff-filter=U']).trim().split('\n').filter(Boolean);
-    if (!conflicted.length) {
-      quiet(this.root, ['merge', '--abort']);
-      throw new Error(`what was pushed could not be taken: ${merged.trim().split('\n')[0]}`);
+  // Take what was pushed: merged without touching the working tree (`git merge-tree`), so a board write never meets a
+  // half-merged document; a board document both sides changed is merged by the board's own document merge, and any other
+  // conflict leaves the checkout as it was and says so. What changes a board document is handed to the board
+  // (applyTaken, in its next transaction); what changes only other files moves git at once (finishTake).
+  async integrate(branch, head, theirs) {
+    if (takings.has(this.root)) return; // one is with the boards already
+    if (!(await canMergeTree(this.root))) return;
+    // every board document this process holds in this checkout, by its path in the checkout, with its board
+    const own = new Map();
+    for (const board of boardsAt.get(this.root) ?? []) for (const path of board.paths) own.set(board.rel(path), { path, board });
+    const merged = await git(this.root, ['merge-tree', '--write-tree', '-z', head, theirs]).then(
+      (out) => ({ out, clean: true }),
+      (error) => (error.code === 1 && error.stdout ? { out: error.stdout, clean: false } : Promise.reject(error)));
+    const fields = merged.out.split('\0');
+    let tree = fields[0].trim();
+    const stages = new Map();
+    for (let i = 1; i < fields.length && fields[i] !== ''; i++) {
+      const entry = /^(\d+) ([0-9a-f]+) (\d)\t(.*)$/s.exec(fields[i]);
+      if (!entry) continue;
+      if (!stages.has(entry[4])) stages.set(entry[4], {});
+      stages.get(entry[4])[entry[3]] = entry[2];
     }
-    for (const file of conflicted) {
-      const path = `${this.root}/${file}`;
-      // In a merge, stage 2 is this checkout's text and stage 3 the pushed one.
-      const stage = (n) => quiet(this.root, ['show', `:${n}:${file}`]) ?? '';
-      const text = this.paths.some((own) => this.rel(own) === file) ? this.merge(stage(1), stage(3), stage(2), path) : null;
-      if (text === null) {
-        quiet(this.root, ['merge', '--abort']);
-        throw new Error(`${basename(file)} could not be merged with what was pushed; nothing was pushed, and this checkout is as it was`);
-      }
-      writeFileSync(path, text);
-      indexed(this.root, ['add', '--', file]);
+    if (!merged.clean) {
+      if (!stages.size) throw new Error(`what was pushed to ${branch} could not be taken: a conflict git names by no file; nothing was taken, and this checkout is as it was`);
+      const blob = async (oid) => (oid ? git(this.root, ['cat-file', 'blob', oid]) : '');
+      const index = join(this.checkout.gitDir, `supercode-board-index.${process.pid}`);
+      try {
+        const env = { GIT_INDEX_FILE: index };
+        await git(this.root, ['read-tree', tree], 120_000, { env });
+        for (const [file, stage] of stages) {
+          // stage 2 is this checkout's text and stage 3 the pushed one
+          const text = own.has(file) ? own.get(file).board.merge(await blob(stage[1]), await blob(stage[3]), await blob(stage[2]), own.get(file).path) : null;
+          if (text === null) throw new Error(`${basename(file)} could not be merged with what was pushed to ${branch}; nothing was taken, and this checkout is as it was`);
+          const oid = (await git(this.root, ['hash-object', '-w', '--stdin'], 120_000, { input: text })).trim();
+          await git(this.root, ['update-index', '--add', '--cacheinfo', `100644,${oid},${file}`], 120_000, { env });
+        }
+        tree = (await git(this.root, ['write-tree'], 120_000, { env })).trim();
+      } finally { rmSync(index, { force: true }); }
+    }
+    const commit = (await git(this.root, ['commit-tree', tree, '-p', head, '-p', theirs, '-m', `board: took what was pushed to ${branch}`], 120_000, { env: author('board') })).trim();
+    // without rename detection: a renamed file is its old path deleted and its new one added, both moved
+    const changed = (await git(this.root, ['diff', '--no-renames', '--name-only', '-z', head, commit])).split('\0').filter(Boolean);
+    const docs = changed.filter((file) => own.has(file));
+    const others = changed.filter((file) => !own.has(file));
+    if (others.length && (await git(this.root, ['status', '--porcelain', '--', ...others])).trim()) {
+      throw new Error(`what was pushed to ${branch} changes files this checkout has changed too (${others.slice(0, 3).join(', ')}); nothing was taken`);
+    }
+    const taking = { root: this.root, head, commit, others, docs, handed: new Map(), applied: new Set() };
+    if (!docs.length) return finishTake(taking);
+    for (const file of docs) {
+      const { path, board } = own.get(file);
+      if (!taking.handed.has(board)) taking.handed.set(board, []);
+      taking.handed.get(board).push({ path, base: (await quiet(this.root, ['show', `${head}:${file}`])) ?? '', text: (await quiet(this.root, ['show', `${commit}:${file}`])) ?? '' });
     }
-    indexed(this.root, ['-c', `user.name=${who}`, '-c', 'user.email=board@supercode.invalid', 'commit', '--quiet', '--no-edit']);
+    takings.set(this.root, taking);
+    for (const board of taking.handed.keys()) board.onTaken?.();
   }
+
+  /**
+   * In the board's transaction, on its loop: what a fetch brought, written as the board's own edit (its stale read then
+   * takes it into the store), each document only if it is still what HEAD held when the merge was made. A write owed
+   * first drops it: that commit goes first, and the next fetch takes what was pushed again. Then git moves (finishTake).
+   */
+  applyTaken() {
+    const taking = takings.get(this.root);
+    const mine = taking?.handed.get(this);
+    if (!mine || taking.applied.has(this)) return false;
+    // compared without line endings: a checkout with core.autocrlf holds CRLF where git's blob holds LF
+    if (mine.some(({ path, base }) => lf(readText(path) ?? '') !== lf(base))) { abandon(taking); return false; }
+    for (const { path, text } of mine) writeAtomically(path, text);
+    taking.applied.add(this);
+    // git moves once every board the merge changes has written its part
+    if (taking.applied.size === taking.handed.size) onChain(this.root, () => finishTake(taking));
+    return true;
+  }
+}
+
+/** A take given up (a board's document is no longer what HEAD held, or the board closed): what the boards already
+ *  wrote of it is their edit, committed as owed; the next fetch merges what was pushed again, cleanly. */
+function abandon(taking) {
+  if (takings.get(taking.root) === taking) takings.delete(taking.root);
+  for (const board of taking.applied) board.commitDirty('board: documents taken in part from what was pushed');
 }
 
-function readable(path) { try { readFileSync(path); return true; } catch { return false; } }
+/** git moved to the merge. HEAD first, by compare-and-swap from where the merge was made; then the checkout's index
+ *  follows for every path the merge changed (syncIndex), and the other files the merge changed are written (a file it
+ *  deleted removed), only while unchanged here. Whatever fails before HEAD moves gives the take up (abandon: what the
+ *  boards wrote is committed as owed); after, what is left is said and its index entries stay owed. */
+async function finishTake(taking) {
+  const { root, head, commit, others, docs } = taking;
+  let moved = false;
+  try {
+    if ((await git(root, ['rev-parse', 'HEAD'])).trim() !== head) return abandon(taking); // a commit came first
+    if (others.length && (await git(root, ['status', '--porcelain', '--', ...others])).trim()) {
+      throw new Error(`what was pushed changes files this checkout has changed too (${others.slice(0, 3).join(', ')}); it is taken by a later fetch`);
+    }
+    await git(root, ['update-ref', '-m', 'board: took what was pushed', 'HEAD', commit, head]);
+    moved = true;
+    syncIndex(root, [...docs, ...others]);
+    if (others.length) moveFiles(root, others, head, commit);
+  } catch (error) {
+    if (!moved) abandon(taking);
+    throw error;
+  } finally { if (takings.get(root) === taking) takings.delete(root); }
+}
+
+/** Text without CR before LF. */
+const lf = (text) => text.replace(/\r\n/g, '\n');
+
+/** A document's text, or null when it does not exist. */
+function readText(path) { try { return readFileSync(path, 'utf8'); } catch { return null; } }
+
+/** A document written whole, never half: beside it, then renamed over it. */
+function writeAtomically(path, text) {
+  const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temporary, text);
+  renameSync(temporary, path);
+}
+
+/** The board's commits are made as `who`. */
+const author = (who) => ({ GIT_AUTHOR_NAME: who, GIT_AUTHOR_EMAIL: 'board@supercode.invalid', GIT_COMMITTER_NAME: who, GIT_COMMITTER_EMAIL: 'board@supercode.invalid' });
+

package/board/ztrack.mjs

@@ -101,6 +101,8 @@ class ZtrackBoard {
     // own work; the backing commits only the writes the manager does not make.
     this.manager = manager;
     this.git = commit ? new GitDocument(this.baseDocs.map((doc) => doc.path), (base, theirs, ours, path) => { try { return this.codec.mergeBoardDocument(base, theirs, ours, path)?.text ?? null; } catch { return null; } }) : null;
+    // what a fetch brought is written in the board's next transaction: one soon, on this loop, if none comes
+    if (this.git) this.git.onTaken = () => setImmediate(() => { try { if (!this.closed) this.tx(() => {}); } catch (error) { current().err(`board: ${error.message}\n`); } });
     // A publish that is behind is said once per call, on whichever workflow verb opened the board: a refused push
     // surfaces on the next call instead of only in the dispatcher's report, and stops being said once the push lands.
     // A held board reads git's state once, beside the owner's loop, and again after its own commits and pushes; an
@@ -145,7 +147,11 @@ class ZtrackBoard {
     if (!this.git || said.has(`behind:${this.path}`)) return;
     said.add(`behind:${this.path}`);
     // A push younger than a minute is still on its way.
-    if (late && Date.now() - late.since > 60_000) current().err(`board: warning: ${late.commits} board document commit${late.commits === 1 ? '' : 's'} not published since ${new Date(late.since).toISOString().slice(0, 16)}Z${late.error ? ` (last push: ${late.error})` : ''}; the dispatcher's next round retries\n`);
+    if (late?.commits && Date.now() - late.since > 60_000) current().err(`board: warning: ${late.commits} board document commit${late.commits === 1 ? '' : 's'} not published since ${new Date(late.since).toISOString().slice(0, 16)}Z${late.error ? ` (last push: ${late.error})` : ''}; the dispatcher's next round retries\n`);
+    // A commit not made: writes still waiting on the checkout's git steps past a minute, or documents an earlier process
+    // left owed.
+    const owed = late?.uncommitted;
+    if (owed && (owed.since === null || Date.now() - owed.since > 60_000)) current().err(`board: warning: ${owed.writes ? `${owed.writes} board document write${owed.writes === 1 ? '' : 's'}` : `${owed.documents} board document${owed.documents === 1 ? '' : 's'}`} not committed${owed.since ? ` since ${new Date(owed.since).toISOString().slice(0, 16)}Z (waiting on the checkout's git steps)` : ''}; ${owed.writes ? 'committed when they land' : 'committed by the board owner when it next opens the board'}\n`);
   }
   /** The owner's watch saw this board's documents change: their stamps are read on the next read, and only then. */
   documentsChanged() { this.docsChanged = true; this.importDue = true; }
@@ -160,7 +166,7 @@ class ZtrackBoard {
   get codec() { return this._codec ??= require('@volter/ztrack/board-document'); }
   get preset() { return this._preset ??= require('@volter/ztrack/kanban-preset'); }
   board() { return { root: this.root, slug: this.slug, label: this.slug, db: this.db }; }
-  close() { this.dropOverlay(); this.conn.close(); }
+  close() { this.closed = true; this.git?.release(); this.dropOverlay(); this.conn.close(); }
 
   statement(sql) {
     let statement = this.statements.get(sql);
@@ -424,6 +430,8 @@ class ZtrackBoard {
         this.refused = new Set();
         timedStep('board tx errors', () => this.loadErrors());
         const recovered = timedStep('board tx recover', () => this.recover());
+        // what a fetch brought, merged beside the loop: written here as the board's own edit, read by the stale check
+        if (this.git && !this.seed) timedStep('board tx take what was pushed', () => this.git.applyTaken());
         if (this.seed) this.indexForSeed();
         else {
           const stale = timedStep('board tx stale check', () => this.staleDocuments({ pending: false }));
@@ -468,7 +476,7 @@ class ZtrackBoard {
         // Committed as the session (or person) whose act this write was, and pushed.
         const byManager = this.manager !== null && (actorOf() === this.manager || principalOf() === this.manager);
         if (this.git) this.git.paths = this.docs.map((doc) => doc.path);
-        if (!byManager) try { timedStep('board git commit and push', () => this.git?.commit(actorOf(), `board: ${outcome.files.map((file) => basename(file.path)).join(', ')} written for ${actorOf() ?? 'the board'}`)); }
+        if (!byManager) try { timedStep('board git commit and push', () => this.git?.commit(actorOf(), `board: ${outcome.files.map((file) => basename(file.path)).join(', ')} written for ${actorOf() ?? 'the board'}`, outcome.files)); }
         catch (error) { current().err(`board: ${error.message}\n`); }
       }
       return outcome.result;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.84",
+  "version": "0.5.86",
   "type": "module",
   "description": "The orchestrator runtime over the Volter Harness ontology: one typed operational model whose folder is its serialization, read and written through the harness orchestration doors (docs/ORCHESTRATOR-IR.md)",
   "exports": {