@volter/supercode-orchestrator 0.4.124 → 0.4.125

package/board/cli.mjs

@@ -13,7 +13,8 @@ import { view, backingPaths, layOut, backingOf, boardExists, boardPath, DEFAULT_
 import { isLocalWorkspace } from './workspace.mjs';
 import { openZtrackBoard } from './ztrack.mjs';
 import * as engine from './engine.mjs';
-import { adoptSession, boardAddress, boardLabel, boardSettings, callerSession, reconcileCallerLaunch, closeRequested, lanesOf, localMachine, observeFleet, paused, plan, startCard, tick } from './dispatch.mjs';
+import { adoptSession, boardAddress, boardLabel, boardSettings, callerSession, commandEnv, reconcileCallerLaunch, closeRequested, lanesOf, localMachine, observeFleet, paused, plan, startCard, supercodeBin, tick } from './dispatch.mjs';
+import { watchBoard } from './wake.mjs';
 import { loadWorkflow, requestSessionClose, scopeOf, statusOf, useWorkflow, workflowEntry, workflowFor } from './workflow.mjs';
 import { evaluate } from './expr.mjs';
 
@@ -1139,7 +1140,8 @@ async function serve(root, args = {}) {
   const params = { ...(Number(args.max) > 0 ? { max_spawn: Number(args.max) } : {}), ...(Number(args['failure-limit']) > 0 ? { failure_limit: Number(args['failure-limit']) } : {}) };
   if (args.pidfile) writeFileSync(args.pidfile, `${process.pid}\n`);
   let stopped = false;
-  const stop = () => { stopped = true; };
+  let events;
+  const stop = () => { stopped = true; events?.close(); };
   process.on('SIGTERM', stop);
   process.on('SIGINT', stop);
   // what the serve says is kept in the home too (logs/workflow-serve.log), so why it stopped outlives its pane
@@ -1154,9 +1156,12 @@ async function serve(root, args = {}) {
   const installed = () => { try { return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version ?? null; } catch { return null; } };
   const running = installed();
   log(`dispatching the boards of ${root} from ${localMachine()} (orchestrator ${running ?? 'unknown'})`);
+  events = watchBoard({ root, binary: supercodeBin(), env: commandEnv(), log });
+  log('dispatch wakes on board writes, document edits, board mail and session catalogue events; interval is a safety sweep');
   const stuck = {};
   const warned = {};
   let pausedSaid = false;
+  let wakeReason = null;
   try {
     while (!stopped) {
       // An installer owns this operational window, not a card pause. Finish the
@@ -1177,6 +1182,8 @@ async function serve(root, args = {}) {
       pausedSaid = Boolean(paused(root)) && pausedSaid;
       let interval = 60;
       const began = Date.now();
+      if (wakeReason) log(`dispatch wake ${wakeReason.sources.join(', ')}; event age ${began - wakeReason.at}ms`);
+      wakeReason = null;
       try {
         const state = await laneState(root);
         const settings = { ...state.settings, ...override };
@@ -1186,9 +1193,9 @@ async function serve(root, args = {}) {
           if (!said.endsWith('nothing to do') || args.verbose) log(said);
           if (args.verbose && r.ms) log(`  took ${Object.entries(r.ms).map(([k, v]) => `${k} ${(v / 1000).toFixed(1)}s`).join(', ')}`);
           if (r.paused && !pausedSaid) { log(`new starts paused by ${r.paused} (\`supercode workflow resume\` lifts it)`); pausedSaid = true; }
-          // Hermes's stuck warning: ready work for six ticks running and nothing started
-          stuck[r.board] = r.ready_waiting && !r.started.length && !r.paused ? (stuck[r.board] ?? 0) + 1 : 0;
-          if (stuck[r.board] >= 6 && Date.now() - (warned[r.board] ?? 0) >= 300_000) { log(`board ${r.board} stuck: ${r.ready_waiting} ready card(s) and nothing started for ${stuck[r.board]} ticks; \`supercode workflow diagnostics\``); warned[r.board] = Date.now(); }
+          // Event bursts do not shorten the six-sweep stuck warning.
+          stuck[r.board] = r.ready_waiting && !r.started.length && !r.paused ? (stuck[r.board] || Date.now()) : 0;
+          if (stuck[r.board] && Date.now() - stuck[r.board] >= interval * 6000 && Date.now() - (warned[r.board] ?? 0) >= 300_000) { log(`board ${r.board} stuck: ${r.ready_waiting} ready card(s) and nothing started for ${Math.floor((Date.now() - stuck[r.board]) / 1000)}s; \`supercode workflow diagnostics\``); warned[r.board] = Date.now(); }
           for (const [t, why] of r.failed) log(`  ${t} did not start: ${why}`);
           for (const [t, why] of r.unsettled ?? []) log(`  ${t} could not be read: ${why}`);
           for (const [t, s, m] of r.started) log(`  ${t} started ${s} (${m})`);
@@ -1201,14 +1208,19 @@ 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)
-      const rest = Math.max(1, interval - Math.floor((Date.now() - began) / 1000));
-      for (let waited = 0; waited < rest && !stopped && !moved; waited += 1) {
-        await new Promise((done) => setTimeout(done, 1000));
-        if (waited % 5 === 4) moved = newer();
+      events.refresh();
+      if (!stopped && !moved) {
+        wakeReason = await events.wait(Math.max(0, interval * 1000 - (Date.now() - began)));
+        // A busy event stream is coalesced to at most one tick per second.
+        const remaining = 1000 - (Date.now() - began);
+        if (remaining > 0 && !stopped) await new Promise(done => setTimeout(done, remaining));
+        moved = newer();
       }
       if (moved) { log(`orchestrator ${moved} is installed (this serve runs ${running}); stopping, for its keeper to start the new one`); break; }
     }
   } finally {
+    events?.close();
+    process.off('SIGTERM', stop); process.off('SIGINT', stop);
     if (args.pidfile) { try { unlinkSync(args.pidfile); } catch { /* gone */ } }
   }
   log(stopped ? 'stopped (a signal)' : 'stopped');

package/board/store.mjs

@@ -16,6 +16,7 @@ import { dirname, join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { openZtrackBoard } from './ztrack.mjs';
 import { isFilesBoard, openFilesBoard } from './files.mjs';
+import { signalBoardWrite } from './wake.mjs';
 
 export const DEFAULT_BOARD = 'default';
 
@@ -163,7 +164,11 @@ export function openBoard(root, slug = DEFAULT_BOARD, { create = false, backing
  * Run `fn(db)` in one write transaction of the board's backing: answers what `fn` answers; rolls back on a throw.
  * A read inside the transaction is the state it writes over.
  */
-export const tx = (board, fn) => board.tx(fn);
+export const tx = (board, fn) => {
+  const result = board.tx(fn);
+  signalBoardWrite(board.root, actor);
+  return result;
+};
 export const view = (board, fn) => fn(board.db);
 
 // A deferred native transaction, with the whole operation retried on an optimistic conflict.

package/board/wake.mjs

@@ -0,0 +1,134 @@
+// Wake hints never own board state. A missed hint is repaired by the safety
+// sweep; a writer never waits for a dispatcher or for another writer.
+import { watch, existsSync, readFileSync, readdirSync, writeFileSync, renameSync, unlinkSync, realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+export function signalBoardWrite(root, actor) {
+  if (!root || actor?.includes(':board:')) return;
+  const path = join(root, '.dispatch-wake.json');
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, JSON.stringify({ at: Date.now(), actor }) + '\n', { mode: 0o600 });
+    renameSync(temporary, path);
+  } catch { try { unlinkSync(temporary); } catch { /* hints cannot fail a committed verb */ } }
+}
+
+/** One coalescing queue shared by standalone serve and the hosted dispatcher. */
+export function watchBoard({ root, binary, env, log = () => {} }) {
+  const watchers = new Map();
+  let pending = null, waiter = null, closed = false, child = null, retry = null, lastError = null;
+  const wake = (source, at = Date.now()) => {
+    if (closed) return;
+    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;
+    try {
+      const handle = watch(path, (_event, filename) => {
+        if (filename == null || accept(String(filename))) wake(key);
+      });
+      handle.on('error', error => {
+        handle.close(); watchers.delete(id);
+        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`); }
+  };
+  const file = (path, key) => {
+    directory(dirname(path), key, name => name === basename(path));
+    try {
+      const target = realpathSync(path);
+      if (target !== path) directory(dirname(target), key, name => name === basename(target));
+    } catch { /* the parent watcher sees a newly created file */ }
+  };
+  const refresh = () => {
+    directory(root, 'board-write', name => {
+      if (name !== '.dispatch-wake.json') return false;
+      try { const receipt = JSON.parse(readFileSync(join(root, name), 'utf8')); wake('board-write', receipt.at); } catch { wake('board-write'); }
+      return false;
+    });
+    for (const name of ['workflow.yaml', 'config.yaml', 'installation-window.json', 'ESTOP']) file(join(root, name), name);
+    file(fileURLToPath(new URL('../package.json', import.meta.url)), 'installation');
+    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)) : [])];
+    for (const dir of dirs) {
+      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}`);
+        file(`${document}.archive.md`, `document:${document}.archive.md`);
+      } catch { /* other backing or not yet created */ }
+    }
+    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');
+    directory(mail, 'mailbox-registry', name => name.startsWith('board-'));
+    if (existsSync(mail)) for (const name of readdirSync(mail)) {
+      if (name.startsWith('board-')) directory(join(mail, name, 'new'), 'board-mail', name => name.endsWith('.json'));
+    }
+  };
+  // The retained Teams catalogue includes local and remote session changes.
+  // This is a read-only stream, with no model or new native harness session.
+  const follow = () => {
+    if (closed) return;
+    let buffer = '', error = '';
+    const command = env.SUPERCODE_TEAMS_ENTRY ? process.execPath : binary;
+    const args = [...(env.SUPERCODE_TEAMS_ENTRY ? [env.SUPERCODE_TEAMS_ENTRY] : []), 'sessions', 'list', '--watch', '--json'];
+    child = spawn(command, args, { cwd: tmpdir(), env, stdio: ['ignore', 'pipe', 'pipe'] });
+    child.stdout.setEncoding('utf8').on('data', chunk => {
+      buffer += chunk;
+      if (buffer.length > 8 * 1024 * 1024) { error = 'catalogue frame exceeds 8 MiB'; child.kill(); return; }
+      let end;
+      while ((end = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, end); buffer = buffer.slice(end + 1);
+        try {
+          const event = JSON.parse(line);
+          lastError = null;
+          if (!['heartbeat', 'ping', 'keepalive'].includes(event.type)) wake('session-catalogue');
+        } catch { /* CLI diagnostics are not events */ }
+      }
+    });
+    child.stderr.setEncoding('utf8').on('data', chunk => { error = (error + chunk).slice(-500); });
+    child.on('error', failure => { error = failure.message; });
+    child.on('close', () => {
+      child = null;
+      if (!closed) {
+        const reason = error.trim() || 'connection closed';
+        if (reason !== lastError) log(`dispatch session stream ended: ${reason}; reconnecting, safety sweep remains active`);
+        lastError = reason;
+        retry = setTimeout(follow, 5000);
+      }
+    });
+  };
+  refresh(); follow();
+  return {
+    refresh,
+    wake,
+    async wait(milliseconds) {
+      if (!pending && !closed) await new Promise(done => {
+        const timer = setTimeout(finish, Math.max(0, milliseconds));
+        function finish() { clearTimeout(timer); waiter = null; done(); }
+        waiter = finish;
+      });
+      // Bound coalescing: a sustained event stream cannot postpone dispatch.
+      if (pending && !closed) await new Promise(done => setTimeout(done, 100));
+      const result = pending; pending = null;
+      return result ? { at: result.at, sources: [...result.sources] } : null;
+    },
+    close() {
+      closed = true; waiter?.(); clearTimeout(retry);
+      for (const handle of watchers.values()) handle.close();
+      watchers.clear(); child?.kill('SIGTERM');
+    },
+  };
+}

package/board.mjs

@@ -2,14 +2,15 @@
 // docs/plans/hermes-compat.md row 14). The board and its dispatcher are supercode's own (`board/`): Hermes Kanban's
 // format and lifecycle, each profile's lane decided by its `worker` in the IR. Where a Hermes gateway would run
 // its dispatcher, the daemon runs this one the same way: when the board's workflow says so (its `dispatch.serve`),
-// taking no file locks, one tick every `dispatch.tick` seconds
-// of the workflow (at least 1), the first after five seconds. Each tick runs as
+// taking no file locks, waking on events with `dispatch.tick` as a safety sweep.
+// Each tick runs as
 // `workflow dispatch` in a child process: a tick waits on supercode (the fleet, launches, mail), and the daemon's
 // own loop never does.
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { summary } from './board/cli.mjs';
-import { notifyChats } from './board/dispatch.mjs';
+import { commandEnv, notifyChats, supercodeBin } from './board/dispatch.mjs';
+import { watchBoard } from './board/wake.mjs';
 import { workflowEntry } from './board/workflow.mjs';
 import { evaluate, holds } from './board/expr.mjs';
 
@@ -52,8 +53,8 @@ export async function startBoard({ root, orchestration = null, log = () => {}, a
       try { await notifyChats(root, adapters, log, wake); } catch (error) { log('warn', `board: chat notices failed: ${error.message}`); }
       for (const r of reports) {
         const line = summary(r);
-        stuck[r.board] = r.ready_waiting && !r.started?.length && !r.paused ? (stuck[r.board] ?? 0) + 1 : 0;
-        if (stuck[r.board] >= 6 && Date.now() - (warned[r.board] ?? 0) >= 300_000) { log('warn', `board ${r.board} stuck: ${r.ready_waiting} ready card(s) and nothing started for ${stuck[r.board]} ticks`); warned[r.board] = Date.now(); }
+        stuck[r.board] = r.ready_waiting && !r.started?.length && !r.paused ? (stuck[r.board] || Date.now()) : 0;
+        if (stuck[r.board] && Date.now() - stuck[r.board] >= seconds * 6000 && Date.now() - (warned[r.board] ?? 0) >= 300_000) { log('warn', `board ${r.board} stuck: ${r.ready_waiting} ready card(s) and nothing started for ${Math.floor((Date.now() - stuck[r.board]) / 1000)}s`); warned[r.board] = Date.now(); }
         if (r.paused && !said.has(`paused:${r.board}`)) { said.add(`paused:${r.board}`); log('info', `board ${r.board}: new starts paused by ${r.paused}`); }
         if (!r.paused) said.delete(`paused:${r.board}`);
         if (!line.endsWith('nothing to do')) log(r.error ? 'warn' : 'info', line);
@@ -67,12 +68,22 @@ export async function startBoard({ root, orchestration = null, log = () => {}, a
       running = false;
     }
   };
-  const first = setTimeout(() => { void tick(); }, 5_000);
-  const timer = setInterval(() => { void tick(); }, seconds * 1000);
-  first.unref?.(); timer.unref?.();
-  log('info', `board: dispatching every ${seconds}s, each card as its profile's worker says`);
+  const events = watchBoard({ root, binary: supercodeBin(), env: commandEnv(), log: message => log('warn', message) });
+  void (async () => {
+    let wakeReason = null;
+    while (!stopped) {
+      const began = Date.now();
+      if (wakeReason) log('info', `board: dispatch wake ${wakeReason.sources.join(', ')}; event age ${began - wakeReason.at}ms`);
+      await tick();
+      events.refresh();
+      wakeReason = await events.wait(Math.max(0, seconds * 1000 - (Date.now() - began)));
+      const remaining = 1000 - (Date.now() - began);
+      if (remaining > 0 && !stopped) await new Promise(done => setTimeout(done, remaining));
+    }
+  })().catch(error => log('warn', `board: dispatch loop failed: ${error.message}`));
+  log('info', `board: dispatching on events, safety sweep every ${seconds}s, each card as its profile's worker says`);
   return {
-    tick,
-    stop() { stopped = true; clearTimeout(first); clearInterval(timer); },
+    tick() { events.wake('requested'); },
+    stop() { stopped = true; events.close(); },
   };
 }

package/package.json

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