@volter/supercode-orchestrator 0.4.123 → 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';
 
@@ -48,7 +49,7 @@ supercode's own:
   create … --machine M --subtask-of ARC --notify ADDRESS|--no-notify --no-start
       With a pane lane and room, a card starts at once and answers "started" with its session; else it answers why it
       waits, and its creator is told when it starts. A subtask is worked by its arc's session and never starts alone.
-  move <id> <machine|none>   adopt <id> <session> [--assignee P]   close <id>   serve (= daemon)   list --machine M
+  move <id> <machine|none>   adopt <id> <session> [--assignee P] [--role ROLE]   close <id>   serve (= daemon)   list --machine M
   notify-subscribe <id> --address sc:<machine>:<harness>:<id> [--role creator|worker|dependency]
   Any verb … --at sc:<machine>:board:<home>: sent as mail to a board kept on another machine.
   <event> <id>... [reason] [--<field> value]: any other event the board's workflow declares, its flags the event's fields.
@@ -814,7 +815,7 @@ export async function runWorkflow(argv) {
     case 'adopt': {
       need(2, 'a card id and a session');
       const { settings } = await laneState(root);
-      const got = withBoard((b) => adoptSession(b, id, rest[1], { workspace: args.workspace ?? null, ttl: settings.ttl, assignee: args.assignee ?? null }));
+      const got = withBoard((b) => adoptSession(b, id, rest[1], { workspace: args.workspace ?? null, ttl: settings.ttl, assignee: args.assignee ?? null, role: args.role ?? null }));
       say(args, `${id} is worked by ${got.address} (pane ${got.pane ?? '?'} in ${got.workspace ?? 'its card\'s directory'})`, { ok: true, ...got });
       return 0;
     }
@@ -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/dispatch.mjs

@@ -1158,7 +1158,7 @@ function resolveLocalWorkspace(board, task) {
  * never as the session describes itself. From then on the board watches it, resumes it when lost, and tells it of
  * its card. `who` is an address, a session id, or a `name@machine` the fleet lists.
  */
-export function adoptSession(board, id, who, { workspace = null, ttl, assignee = null } = {}) {
+export function adoptSession(board, id, who, { workspace = null, ttl, assignee = null, role = null } = {}) {
   const fleet = observeFleet();
   if (!fleet.ok) throw new Error(`supercode could not read the fleet: ${fleet.error}`);
   const found = fleet.sessions.find((s) => s.address === who || s.address.endsWith(`:${who}`) || s.name === who);
@@ -1195,14 +1195,20 @@ export function adoptSession(board, id, who, { workspace = null, ttl, assignee =
     if (dir && !task.workspace_anchor && !(task.workspace_kind === 'dir' && task.workspace_path)) {
       db.prepare("UPDATE tasks SET workspace_kind = 'dir', workspace_path = ? WHERE id = ?").run(dir.replace(/^dir:/, ''), id);
     }
-    // the workflow's adopt event: the card is claimed for its implementer, whose session this now is
+    // Adoption takes the role and slot declared for this card's current stage.
     const entry = workflowFor(board.root);
+    const expected = runSpec(entry, statusOf(db, task), task);
+    if (role && role !== expected?.role) throw new Error(`${id} needs its ${expected?.role ?? 'declared'} role, not ${role}`);
+    if (expected?.role === 'reviewer') {
+      const implementer = lastSession(db, id, 'worker');
+      if (implementer?.session_id === sessionId) throw new Error('a reviewer must be independent of the implementer session');
+    }
     if (!beforeRun) fire(db, board, entry, id, entry.workflow.run ? entry.workflow.dispatch.start : 'adopt', { roles: ['manager'], payload: { lock: claimer() } });
     const runId = getTask(db, id).current_run_id;
     if (!runId) throw new Error(`${id} waits on parents that are not done`);
     const session = { surface: 'pane', session_id: sessionId, harness, machine: host, pane: found.pane ?? null, address: found.address, mode: 'adopt', launched_at: now(), seen_at: now() };
-    setRunSession(db, runId, { ...(currentRun(db, id)?.metadata?.supercode ?? {}), ...session, slot: beforeSession?.slot ?? 'worker', close_requested: null, closed_at: null, close_confirmed_at: null, close_error: null, missing_since: null });
-    event(db, id, 'session_adopted', { session_id: sessionId, machine: host, pane: session.pane, address: found.address, mode: 'adopt' }, runId);
+    setRunSession(db, runId, { ...(currentRun(db, id)?.metadata?.supercode ?? {}), ...session, slot: currentRun(db, id)?.metadata?.supercode?.slot ?? beforeSession?.slot ?? expected?.session ?? 'worker', close_requested: null, closed_at: null, close_confirmed_at: null, close_error: null, missing_since: null });
+    event(db, id, 'session_adopted', { session_id: sessionId, machine: host, pane: session.pane, address: found.address, mode: 'adopt', role: currentRun(db, id)?.metadata?.supercode?.role }, runId);
     subscribeIn(db, id, found.address, 'worker');
     for (const p of db.prepare('SELECT parent_id FROM task_links WHERE child_id = ?').all(id)) subscribeIn(db, p.parent_id, found.address, 'dependency');
     return { ...session, workspace: dir };

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.123",
+  "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": {