@volter/supercode-orchestrator 0.5.75 → 0.5.76

package/board/cli.mjs

@@ -19,13 +19,13 @@ import { holdLock } from './lock-holder.mjs';
 import { takeEpoch } from './fence.mjs';
 import { dispatcherNotice, holdOwnerHealth, holdRound, holdSwitch } from './owner-health.mjs';
 import { boardTool } from './tools.mjs';
-import { recordSlow, takeSteps } from '@volter/supercode-harness-sdk/slow-log';
+import { noteStep, recordSlow, takeSteps } from '@volter/supercode-harness-sdk/slow-log';
 // read by name, so an older harness SDK without them still loads: the owner then keeps no per-verb or loop lines
 import * as slowLog from '@volter/supercode-harness-sdk/slow-log';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir, tmpdir, userInfo } from 'node:os';
-import { actorOf, publishMarked, view, backingPaths, layOut, backingOf, boardExists, boardPath, DEFAULT_BOARD, event, json, listBoards, logsDir, now, openBoard, setActor, setPrincipal, principalOf, isCaller, tx } from './store.mjs';
+import { actorOf, heldConfigWatched, heldDocumentsChanged, heldDocumentsWatched, holdBoards, retireHeldBoards, releaseHeldBoards, publishMarked, view, backingPaths, layOut, backingOf, boardExists, boardPath, DEFAULT_BOARD, event, json, listBoards, logsDir, now, openBoard, setActor, setPrincipal, principalOf, isCaller, tx } from './store.mjs';
 import { isLocalWorkspace } from './workspace.mjs';
 import { openZtrackBoard } from './ztrack.mjs';
 import * as engine from './engine.mjs';
@@ -1648,7 +1648,33 @@ async function serve(root, args = {}) {
   // a held event loop is every caller's wait at once: each hold over a second is a slow line naming what held it
   const unwatchLoop = slowLog.watchEventLoop?.({ name: 'board owner event loop blocked' });
   log(`owning the boards of ${root} on ${localMachine()} (orchestrator ${running ?? 'unknown'}); dispatching where a board's dispatching is on (\`supercode workflow dispatching\`)`);
-  events = watchBoard({ root, binary: supercodeBin(), env: commandEnv(), log });
+  // a document event reaches the held boards as it arrives: their next read takes the documents' new stamps
+  // a document event, or the watch saying it may have lost events, reaches the held boards as it arrives: their next
+  // read takes the documents' new stamps; while a document's folder is unwatched they read the stamps on every read
+  // Trust in what the owner holds is per board, per source and per configuration generation. A board's configuration
+  // event (or the home's registry) retires that board's held generation, and the watch set is refreshed at once so a
+  // replacement's documents are watched before they are loaded; a lost configuration watch keeps the board unheld
+  // until it is watched again. A board's own backing source changing, or its watch saying it may have lost events,
+  // makes that board read its files again; while one of its sources is unwatched, it reads them on every use.
+  const sourceOf = (key) => key.startsWith('document:') || key === 'board-storage';
+  // a refresh's own reports (a configuration it could not read) never start another refresh
+  let refreshing = false;
+  const refreshNow = () => { if (refreshing) return; refreshing = true; try { events?.refresh(); } finally { refreshing = false; } };
+  events = watchBoard({ root, binary: supercodeBin(), env: commandEnv(), log, onEvent: (key, { uncertain = false, watched, id, board = null } = {}) => {
+    if (key === 'board-registry') { retireHeldBoards(); refreshNow(); return; }
+    if (key === 'board-config') {
+      if (watched !== undefined && board) heldConfigWatched(board, id ?? key, watched);
+      retireHeldBoards(board); refreshNow(); return;
+    }
+    if (!sourceOf(key)) return;
+    heldDocumentsChanged(board);
+    if (watched !== undefined && board) heldDocumentsWatched(board, id ?? key, watched);
+    else if (uncertain && !board) heldDocumentsChanged();
+  } });
+  // the owner holds its boards only now, its watch installed (watch before load): opened once, changed by events
+  holdBoards(root);
+  // a pause of the collector holds the loop like any synchronous step: each is a step, so a block line names it
+  try { const { PerformanceObserver } = await import('node:perf_hooks'); new PerformanceObserver((list) => { for (const entry of list.getEntries()) noteStep('gc', entry.duration); }).observe({ entryTypes: ['gc'] }); } catch { /* no gc entries here */ }
   // The board's events are published by this machine's connector, not by the dispatcher (D137, D138 step 4): the home is
   // named to the daemon once, and the connector follows its `workflow events` from then on, with or without this serve.
   { let named = null, refusal = null;
@@ -1676,13 +1702,14 @@ async function serve(root, args = {}) {
       const began = Date.now();
       if (wakeReason) log(`dispatch wake ${wakeReason.sources.join(', ')}; event age ${began - wakeReason.at}ms`);
       wakeReason = null;
+      const loopStep = async (name, fn) => { const at = performance.now(); try { return await fn(); } finally { noteStep(`owner loop: ${name}`, performance.now() - at); } };
       try {
-        const state = await ownCall(() => laneState(root));
+        const state = await loopStep('lane state', () => ownCall(() => laneState(root)));
         const settings = { ...state.settings, ...override };
         interval = settings.interval;
         // Publishing is the owner's, dispatching or not: what a writer outside this process marked changed is published
         // on the wake its write caused, and the retained history kept bounded (store.mjs publishMarked).
-        const published = await ownCall(async () => publishMarked(root));
+        const published = await loopStep('publish marked', () => ownCall(async () => publishMarked(root)));
         if (published && args.verbose) log(`published ${published} card(s) a writer outside the owner changed`);
         // Dispatching is a controller over the boards whose own state says it is on; the owner answers verbs either way.
         const dispatching = listBoards(root).filter((slug) => dispatchingOf(root, slug).on);
@@ -1722,7 +1749,7 @@ async function serve(root, args = {}) {
       const newer = () => { const now = installed(); return running && now && now !== running ? now : null; };
       let moved = newer();
       // the next tick is due an interval after this one began (a long tick is not followed by a full interval's wait)
-      events.refresh();
+      await loopStep('wake refresh', () => refreshNow());
       if (!stopped && !moved) {
         wakeReason = await events.wait(Math.max(0, Math.min(interval * 1000 - (Date.now() - began), nextMailAt - Date.now())));
         // A busy event stream is coalesced to at most one tick per second.
@@ -1735,7 +1762,7 @@ async function serve(root, args = {}) {
   } finally {
     // a fetch in flight lands, and what it brought is merged, while this owner still holds the home's lock
     try { const { settleDocuments } = await import('./git-document.mjs'); await settleDocuments(); } catch { /* nothing in flight */ }
-    unwatchLoop?.(); closeVerbs();
+    unwatchLoop?.(); releaseHeldBoards(); closeVerbs();
     unfollowHome();
     await closeDoors();
     events?.close();

package/board/files.mjs

@@ -33,14 +33,18 @@ function writeAtomic(file, text) {
  * Open the files board in `dir`. `init(db, { fresh })` lays the board's schema over a loaded database (the store's:
  * Hermes's tables on a fresh one, supercode's own table and columns on every one). Answers `{ db, tx, close }`.
  */
-export function openFilesBoard(dir, { create = false, init }) {
+export function openFilesBoard(dir, { create = false, init, held = false }) {
   if (!isFilesBoard(dir)) {
     if (!create) throw new Error(`${dir} is not a board`);
     mkdirSync(dir, { recursive: true });
   }
   const board = new FilesBoard(dir, init);
+  // held by the board owner: its files are read again only when the owner's watch says they changed or may have lost
+  // events, and on every read while it keeps no watch on them; a write still compares the files it read (persist)
+  board.held = held;
   if (!isFilesBoard(dir)) board.tx(() => {}, { force: true });
-  return { db: board.db, tx: (fn) => board.tx(fn), close: () => board.close() };
+  return { db: board.db, tx: (fn) => board.tx(fn), close: () => board.close(),
+    documentsChanged: () => { board.changed = true; }, documentsUnwatched: (unwatched) => { board.unwatched = unwatched; } };
 }
 
 class FilesBoard {
@@ -217,7 +221,10 @@ class FilesBoard {
   }
 
   read(fn) {
-    if (!this.inTx && this.stampOf() !== this.stamp) this.load();
+    // a held board knows its files until an event says otherwise; one opened per use reads them on each query
+    const known = this.held && !this.changed && !this.unwatched && this.mem && this.stamp !== null;
+    // the mark clears only once the files were read: a read that fails leaves it, and the next read tries again
+    if (!this.inTx && !known) { if (this.stampOf() !== this.stamp) this.load(); if (this.held) this.changed = false; }
     return fn();
   }
 

package/board/git-document.mjs

@@ -132,6 +132,7 @@ export class GitDocument {
       this.integrate(branch, 'board');
     }
     if (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.
@@ -145,6 +146,7 @@ export class GitDocument {
     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.refreshLateness();
     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
@@ -166,6 +168,7 @@ export class GitDocument {
     const done = () => {
       if (this.pushing !== pushing) return;
       this.pushing = null;
+      this.refreshLateness();
       if (this.again) this.pushInBackground(branch);
     };
     pushing.on('error', done); pushing.on('exit', done);
@@ -178,6 +181,29 @@ export class GitDocument {
 
   /** 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}/`);
+      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 };
+    })().then((late) => { this.lateness = late; }, () => {}).finally(() => {
+      this.lateReading = null;
+      if (this.lateAgain) { this.lateAgain = false; this.refreshLateness(); }
+    });
+  }
+
   behind() {
     if (!this.usable) return null;
     const branch = this.branch();

package/board/store.mjs

@@ -172,7 +172,87 @@ function noteOrigin(root) {
   copies.set(root, origin === here ? null : origin);
 }
 
-export function openBoard(root, slug = DEFAULT_BOARD, { create = false, backing = null, document = null, declared = null } = {}) {
+/**
+ * The boards the owner holds (overview.md, the board owner: a held home view, changed by events). In the process that
+ * owns a home, every board is opened once and held: each verb, wake and round gets a handle of its own over the held
+ * board (its own `label`; its `close` releases nothing), so none re-opens the store, re-reads its schema, re-hashes
+ * its documents or asks git again for what the owner already holds. What changes a held board is an event: its own
+ * writes, and the document changes the owner's watch reports (heldDocumentsChanged). Elsewhere (a CLI process, a
+ * worker) a board is opened per use, as before.
+ */
+let holding = null;
+const heldBoards = new Map(); // slug → { board, uses: handles open on it, retired }: one per configuration generation
+const unwatchedSources = new Map(); // slug → its backing sources (watched folders) the owner's watch does not keep
+const untrustedConfig = new Map(); // slug → its configuration's watches the owner does not keep
+const realRoot = (root) => { try { return realpathSync(root); } catch { return root; } };
+/** The owner holds its boards from here on: called once its watch is installed (watch before load, D187). */
+export function holdBoards(root) { holding = realRoot(root); }
+export function releaseHeldBoards() { retireHeldBoards(); holding = null; }
+/**
+ * A board's configuration changed, or the home's registry did (their own events): the held boards are retired, so the
+ * next use opens what the configuration now says, as a new generation. A retired generation refuses every write (a
+ * call that held it across an await writes nothing under the old configuration) and closes with its last handle.
+ */
+export function retireHeldBoards(slug = null) {
+  for (const [held, entry] of [...heldBoards]) {
+    if (slug !== null && held !== slug) continue;
+    heldBoards.delete(held); entry.retired = true;
+    if (!entry.uses) try { entry.board.close(); } catch { /* closed */ }
+  }
+}
+/** A board's backing source changed, or its watch may have lost events: that board reads its files again on its next
+ *  read, and only then (all boards, with no slug). */
+export function heldDocumentsChanged(slug = null) {
+  for (const [held, { board }] of heldBoards) if (slug === null || held === slug) board.documentsChanged?.();
+}
+/** Whether the owner's watch keeps one of a board's backing sources: while any is unwatched, that board reads its files
+ *  on every use. */
+export function heldDocumentsWatched(slug, source, watched) {
+  const set = unwatchedSources.get(slug) ?? new Set();
+  if (watched) set.delete(source); else set.add(source);
+  unwatchedSources.set(slug, set);
+  heldBoards.get(slug)?.board.documentsUnwatched?.(set.size > 0);
+}
+/** Whether the owner's watch keeps a board's configuration: while it does not, the board is not held (each use reads
+ *  its configuration), and a held generation is retired. */
+export function heldConfigWatched(slug, source, watched) {
+  const set = untrustedConfig.get(slug) ?? new Set();
+  if (watched) set.delete(source); else set.add(source);
+  untrustedConfig.set(slug, set);
+  if (set.size) retireHeldBoards(slug);
+}
+
+export function openBoard(root, slug = DEFAULT_BOARD, options = {}) {
+  if (holding !== null && !options.create && realRoot(root) === holding && !untrustedConfig.get(slug)?.size) {
+    let entry = heldBoards.get(slug);
+    if (!entry) {
+      const began = performance.now();
+      let board;
+      try { board = openBoardNow(root, slug, { ...options, held: true }); } finally { noteStep('board open (held, once)', performance.now() - began); }
+      entry = { board, uses: 0, retired: false };
+      heldBoards.set(slug, entry);
+      board.documentsUnwatched?.((unwatchedSources.get(slug)?.size ?? 0) > 0);
+    }
+    entry.uses += 1;
+    entry.board.saidOnOpen?.();
+    return heldHandle(entry, slug);
+  }
+  return openBoardNow(root, slug, options);
+}
+
+/** A call's handle on a held board: its own label, a close that releases its use, and every write refused once the
+ *  generation it was opened on is retired. */
+function heldHandle(entry, slug) {
+  const guard = () => { if (entry.retired) throw Object.assign(new Error(`board ${slug}'s configuration changed while this call held it; nothing was written (read it again)`), { code: 'board_retired' }); };
+  const bound = (target, key) => { const value = target[key]; return typeof value === 'function' ? value.bind(target) : value; };
+  const statement = (st) => new Proxy(st, { get: (target, key) => key === 'run' ? (...args) => { guard(); return target.run(...args); } : bound(target, key) });
+  const db = new Proxy(entry.board.db, { get: (target, key) => key === 'prepare' ? (sql) => statement(target.prepare(sql)) : key === 'exec' ? (sql) => { guard(); return target.exec(sql); } : bound(target, key) });
+  let closed = false;
+  return { ...entry.board, db, tx: (fn) => { guard(); return entry.board.tx(fn); },
+    close() { if (closed) return; closed = true; entry.uses -= 1; if (entry.retired && !entry.uses) try { entry.board.close(); } catch { /* closed */ } } };
+}
+
+function openBoardNow(root, slug, { create = false, backing = null, document = null, declared = null, held = false } = {}) {
   noteOrigin(root);
   const kept = backingOf(root, slug);
   if (!kept && !create) throw new Error(`no board ${slug} in ${root} (${boardPath(root, slug)})`);
@@ -180,8 +260,8 @@ export function openBoard(root, slug = DEFAULT_BOARD, { create = false, backing
   const use = kept ?? backing ?? 'sqlite';
   if (!BACKINGS.includes(use)) throw new Error(`a board's backing is ${BACKINGS.join(' | ')}, not ${use}`);
   const path = backingPaths(root, slug)[use];
-  if (use === 'ztrack') return { ...openZtrackBoard(path, { create, document, declared, init: layOut, root, slug }), root, slug, path, backing: use };
-  if (use === 'files') return { ...openFilesBoard(path, { create, init: layOut }), root, slug, path, backing: use };
+  if (use === 'ztrack') return { ...openZtrackBoard(path, { create, document, declared, init: layOut, root, slug, held }), root, slug, path, backing: use };
+  if (use === 'files') return { ...openFilesBoard(path, { create, init: layOut, held }), root, slug, path, backing: use };
   if (!kept) mkdirSync(dirname(path), { recursive: true });
   const db = new DatabaseSync(path);
   db.exec('PRAGMA foreign_keys = OFF');
@@ -231,13 +311,14 @@ export function publishMarked(root) {
   let published = 0;
   for (const slug of listBoards(root)) {
     let board;
+    const step = (name, fn) => { const began = performance.now(); try { return fn(); } finally { noteStep(`publish marked: ${name}`, performance.now() - began); } };
     try {
-      board = openBoard(root, slug);
+      board = step('open', () => openBoard(root, slug));
       // a mark in the store, or a backing edit not yet imported into its tables (a ztrack document): the transaction
       // imports the edit, which marks its cards, and publishes them
-      const marked = board.db.prepare('SELECT 1 FROM supercode_publication_dirty LIMIT 1').get() || board.unimported?.();
-      if (marked) published += board.tx((db) => recordCardPublications(db, actorOf()));
-      if (pruneDue(board.db)) board.tx((db) => prunePublications(db));
+      const marked = step('marks', () => board.db.prepare('SELECT 1 FROM supercode_publication_dirty LIMIT 1').get()) || step('unimported', () => board.unimported?.());
+      if (marked) published += step('publish', () => board.tx((db) => recordCardPublications(db, actorOf())));
+      if (step('prune due', () => pruneDue(board.db))) step('prune', () => board.tx((db) => prunePublications(db)));
     } finally { board?.close(); }
   }
   return published;

package/board/wake.mjs

@@ -16,35 +16,55 @@ export function signalBoardWrite(root, actor) {
 }
 
 /** One coalescing queue shared by standalone serve and the hosted dispatcher. */
-export function watchBoard({ root, binary, env, log = () => {} }) {
+export function watchBoard({ root, binary, env, log = () => {}, onEvent = () => {} }) {
   const watchers = new Map();
   let pending = null, waiter = null, closed = false;
-  const wake = (source, at = Date.now()) => {
+  const wake = (source, at = Date.now(), info = {}) => {
     if (closed) return;
+    // each event as it arrives, with the board whose source it is (a held board learns its files changed now)
+    try { onEvent(source, info); } catch { /* an observer cannot stop a wake */ }
     if (!pending) pending = { at, sources: new Set() };
     pending.at = Math.min(pending.at, at);
     pending.sources.add(source);
     waiter?.();
   };
-  const directory = (path, key, accept) => {
-    const id = `${path}\0${key}`;
-    if (watchers.has(id) || !existsSync(path)) return;
+  // The watch says when it may have lost events: a pathless event, a watch that failed, one that could not be made.
+  // An observer is told (uncertain), and told again when the watch is kept once more (watched), so what it holds from
+  // these events is read again only then, never on a timer.
+  const unwatched = new Set();
+  const tell = (key, info) => { try { onEvent(key, info); } catch { /* an observer cannot stop a watch */ } };
+  // `board` names the board whose backing source a watch is (null for the home's own files): its observer keeps trust
+  // per board and per source.
+  // `name` tells apart two watches of one folder under one key (an alias and its target side by side): each keeps its
+  // own filter, so each source's events reach its board
+  const directory = (path, key, accept, board = null, name = '') => {
+    const id = `${path}\0${key}\0${name}`;
+    if (watchers.has(id)) return;
+    // a folder not there yet is unwatched, said (never assumed quiet): the next refresh watches it once it exists
+    if (!existsSync(path)) { if (!unwatched.has(id)) { unwatched.add(id); tell(key, { uncertain: true, watched: false, id, board }); } return; }
     try {
       const handle = watch(path, (_event, filename) => {
-        if (filename == null || accept(String(filename))) wake(key);
+        if (filename == null) { tell(key, { uncertain: true, board }); wake(key, undefined, { board }); return; }
+        if (accept(String(filename))) wake(key, undefined, { board });
       });
       handle.on('error', error => {
-        handle.close(); watchers.delete(id);
+        handle.close(); watchers.delete(id); unwatched.add(id);
+        tell(key, { uncertain: true, watched: false, id, board });
         log(`dispatch watch ${key} failed: ${error.message}; safety sweep remains active`);
       });
       watchers.set(id, handle);
-    } catch (error) { log(`dispatch watch ${key} unavailable: ${error.message}; safety sweep remains active`); }
+      if (unwatched.delete(id)) tell(key, { uncertain: true, watched: true, id, board });
+    } catch (error) {
+      if (!unwatched.has(id)) { unwatched.add(id); tell(key, { uncertain: true, watched: false, id, board }); }
+      log(`dispatch watch ${key} unavailable: ${error.message}; safety sweep remains active`);
+    }
   };
-  const file = (path, key) => {
-    directory(dirname(path), key, name => name === basename(path));
+  const file = (path, key, board = null) => {
+    directory(dirname(path), key, name => name === basename(path), board, basename(path));
     try {
+      // an alias is followed to its target, each filtered by its own name
       const target = realpathSync(path);
-      if (target !== path) directory(dirname(target), key, name => name === basename(target));
+      if (target !== path) directory(dirname(target), key, name => name === basename(target), board, `target:${basename(target)}`);
     } catch { /* the parent watcher sees a newly created file */ }
   };
   const refresh = () => {
@@ -58,22 +78,27 @@ export function watchBoard({ root, binary, env, log = () => {} }) {
     const boards = join(root, 'kanban', 'boards');
     directory(join(root, 'kanban'), 'board-registry', name => ['boards', 'ztrack.json', 'current'].includes(name));
     directory(boards, 'board-registry', () => true);
-    const dirs = [join(root, 'kanban'), ...(existsSync(boards) ? readdirSync(boards).map(name => join(boards, name)) : [])];
-    file(join(root,'kanban.db'),'board-storage');
-    file(join(root,'kanban.db-wal'),'board-storage');
-    for (const dir of dirs) {
-      file(join(dir,'kanban.db'),'board-storage');
-      file(join(dir,'kanban.db-wal'),'board-storage');
-      directory(join(dir,'board'),'board-storage',name=>name.endsWith('.json'));
-      file(join(dir, 'ztrack.json'), 'board-config');
-      try {
-        const config = JSON.parse(readFileSync(join(dir, 'ztrack.json'), 'utf8'));
-        const document = resolve(dir, config.document);
-        file(document, `document:${document}`);
-        // the current archive and each rotated one (`<document>.archive-<date>.md`)
-        const own = basename(document);
-        directory(dirname(document), `document:${document}.archive`, name => name === `${own}.archive.md` || (name.startsWith(`${own}.archive-`) && name.endsWith('.md')));
-      } catch { /* other backing or not yet created */ }
+    // each board's own backing sources, and only those: a ztrack board's configuration and documents, a files board's
+    // folder, a SQLite board's store (a source a board does not have is not watched, so its absence says nothing)
+    const dirs = [[join(root, 'kanban'), 'default'], ...(existsSync(boards) ? readdirSync(boards).map(name => [join(boards, name), name]) : [])];
+    for (const [dir, board] of dirs) {
+      file(join(dir, 'ztrack.json'), 'board-config', board);
+      if (existsSync(join(dir, 'ztrack.json'))) {
+        try {
+          const config = JSON.parse(readFileSync(join(dir, 'ztrack.json'), 'utf8'));
+          const document = resolve(dir, config.document);
+          file(document, `document:${document}`, board);
+          // the current archive and each rotated one (`<document>.archive-<date>.md`)
+          const own = basename(document);
+          directory(dirname(document), `document:${document}.archive`, name => name === `${own}.archive.md` || (name.startsWith(`${own}.archive-`) && name.endsWith('.md')), board);
+        } catch { tell('board-config', { uncertain: true, board }); }
+      } else if (existsSync(join(dir, 'board', '_board.json'))) {
+        directory(join(dir, 'board'), 'board-storage', name => name.endsWith('.json'), board);
+      } else {
+        const store = board === 'default' ? join(root, 'kanban.db') : join(dir, 'kanban.db');
+        file(store, 'board-storage', board);
+        file(`${store}-wal`, 'board-storage', board);
+      }
     }
     const config = env.SUPERCODE_HOME || (env.XDG_CONFIG_HOME ? join(env.XDG_CONFIG_HOME, 'supercode') : join(env.HOME ?? '', '.config', 'supercode'));
     const mail = join(config, 'mail');

package/board/ztrack.mjs

@@ -62,7 +62,7 @@ DROP TABLE IF EXISTS board_export;`;
 // written to the document). board_tasks: a subtask's key on its arc's Tasks list
 // (`<arc>:c3`) and its `source:` lines, which live only in the document.
 
-export function openZtrackBoard(marker, { create = false, document = null, declared = null, seed = null, init, root, slug }) {
+export function openZtrackBoard(marker, { create = false, document = null, declared = null, seed = null, init, root, slug, held = false }) {
   if (!existsSync(marker)) {
     if (!create) throw new Error(`no ztrack board ${marker}`);
     mkdirSync(dirname(marker), { recursive: true });
@@ -76,13 +76,18 @@ export function openZtrackBoard(marker, { create = false, document = null, decla
     atomic(marker, JSON.stringify({ format: 1, document: join(realpathSync(dirname(named)), basename(named)), ...said }) + '\n');
   }
   const config = JSON.parse(read(marker));
-  const backing = new ZtrackBoard({ ...config, seed, marker, init, root, slug });
-  return { db: backing.db, tx: (fn) => backing.tx(fn), publishPending: () => backing.git?.publishPending(), unimported: () => backing.unimported(), close: () => backing.close(), document: backing.path };
+  const backing = new ZtrackBoard({ ...config, seed, marker, init, root, slug, held });
+  return { db: backing.db, tx: (fn) => backing.tx(fn), publishPending: () => backing.git?.publishPending(), unimported: () => backing.unimported(), close: () => backing.close(), document: backing.path,
+    documentsChanged: () => backing.documentsChanged(), documentsUnwatched: (unwatched) => { backing.unwatched = unwatched; }, saidOnOpen: () => backing.sayLate() };
 }
 
 
 class ZtrackBoard {
-  constructor({ document, seed, marker, init, root, slug, commit = false, manager = null, archive = {} }) {
+  constructor({ document, seed, marker, init, root, slug, commit = false, manager = null, archive = {}, held = false }) {
+    // held by the board owner (store.mjs holdBoards): opened once, its documents' stamps read again only when the
+    // owner's watch says they changed or may have lost events (documentsChanged), and on every read while it keeps no
+    // watch on them (unwatched); git's lateness held and refreshed on its own commits
+    this.held = held; this.docsChanged = true; this.importDue = true; this.knownStamps = null;
     this.path = resolve(dirname(marker), document);
     this.archive = `${this.path}.archive.md`;
     this.baseDocs = [{ role: 'open', path: this.path }, { role: 'archived', path: this.archive }];
@@ -98,13 +103,10 @@ class ZtrackBoard {
     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;
     // 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.
-    const said = current().said;
-    if (this.git && !said.has(`behind:${this.path}`)) {
-      said.add(`behind:${this.path}`);
-      const late = timedStep('board open git behind', () => this.git.behind());
-      // 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`);
-    }
+    // A held board reads git's state once, beside the owner's loop, and again after its own commits and pushes; an
+    // open per use reads it now.
+    if (this.git && held) this.git.holdLateness();
+    else if (this.git) this.sayLate(timedStep('board open git behind', () => this.git.behind()));
     this.seed = seed; this.root = root; this.slug = slug; this.init = init;
     this.file = `${marker}.board.db`;
     mkdirSync(dirname(this.path), { recursive: true });
@@ -137,6 +139,16 @@ class ZtrackBoard {
     // a board that is only read, or whose owner runs no round, still finishes an earlier process's commit.
     if (seed || this.git?.underived) this.tx(() => {});
   }
+  /** The publish's lateness, said once per call (a held board's from its held reading, never by asking git). */
+  sayLate(late = this.git?.lateness ?? null) {
+    const said = current().said;
+    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`);
+  }
+  /** 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; }
   // The board's documents: the open one, the current archive, and each rotated archive (recorded in the board's own
   // state, so a rotation committed but not yet written is still a document of the board).
   get docs() {
@@ -360,21 +372,30 @@ class ZtrackBoard {
   // A reader sees a hand edit at once, through connection-local copies of the card tables, and
   // writes nothing: the next write records the edit.
   observeForRead() {
-    const stamp = [...this.docs.map((doc) => this.fileHash(doc.path).stamp), this.stateText('published'), this.stateText('pending_hashes')].join('|');
+    // a held board knows its documents' stamps until the owner's watch says they changed; one opened per use reads them
+    const stamps = this.held && !this.docsChanged && !this.unwatched && this.knownStamps ? this.knownStamps
+      : timedStep('board read: document stamps', () => this.docs.map((doc) => this.fileHash(doc.path).stamp));
+    if (this.held) { this.knownStamps = stamps; this.docsChanged = false; }
+    const stamp = [...stamps, this.stateText('published'), this.stateText('pending_hashes')].join('|');
     if (stamp === this.seen) return;
     this.seen = stamp;
     this.loadErrors();
-    const stale = this.staleDocuments({ pending: true });
+    const stale = timedStep('board read: stale check', () => this.staleDocuments({ pending: true }));
     if (!stale.length) { this.dropOverlay(); return; }
     let plan;
-    try { plan = this.observe(stale); } catch { this.dropOverlay(); return; } // the next write reports it
-    this.applyPlan(plan, { overlay: true });
+    try { plan = timedStep('board read: observe', () => this.observe(stale)); } catch { this.dropOverlay(); return; } // the next write reports it
+    timedStep('board read: overlay', () => this.applyPlan(plan, { overlay: true }));
   }
 
   // Whether a document holds an edit its tables have not imported (a hand edit, a git update): the publication owner
   // enters a transaction for it, which imports it and so marks its cards. Unreadable reads as yes: the write reports it.
   unimported() {
-    try { return this.staleDocuments({ pending: true }).length > 0; } catch { return true; }
+    // a held board looks again only after a document event (or while unwatched): a quiet round hashes nothing
+    if (this.held && !this.importDue && !this.unwatched) return false;
+    let stale;
+    try { stale = timedStep('board unimported check', () => this.staleDocuments({ pending: true }).length > 0); } catch { return true; }
+    if (!stale) this.importDue = false;
+    return stale;
   }
 
   dropOverlay() {
@@ -436,11 +457,14 @@ class ZtrackBoard {
       // accepted, with every document the board has; a recovery in any later write is committed the same way.
       if (this.git && (this.git.underived || outcome.recovered)) {
         this.git.paths = this.docs.map((doc) => doc.path);
+        if (outcome.recovered) this.docsChanged = true;
         try { timedStep('board git derive', () => outcome.recovered && !this.git.underived ? this.git.commitDirty('board: documents another write accepted') : this.git.derive()); }
         catch (error) { current().err(`board: ${error.message}\n`); }
       }
       if (outcome.intent) {
         this.publish(outcome);
+        // its own documents written: an event of its own, read on the next read
+        this.docsChanged = true;
         // 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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.75",
+  "version": "0.5.76",
   "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": {