@volter/supercode-orchestrator 0.4.12 → 0.4.14

package/bin/hermes-worker.mjs

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
-// The command Hermes's board dispatcher runs as its worker when the orchestrator serves the home: the
-// loop sets `HERMES_BIN` to this file (docs/plans/hermes-compat.md row 14). Hermes's own argv and
-// environment; see `kanban-worker.mjs`.
+// The command the board's dispatcher runs as a headless profile's worker (docs/plans/hermes-compat.md row 14):
+// Hermes's own worker argv and environment; see `kanban-worker.mjs`.
 import { runKanbanWorker } from '../kanban-worker.mjs';
 
 // Hermes watches this pid: it exits the moment the turn is over, whatever handle is still open.

package/bin/orchestrator.mjs

@@ -47,6 +47,9 @@
 // jobs create --harness orchestrator` writes the same bytes whether the daemon
 // is up or down. It exits 0 on `ok`, 1 on a refusal.
 //
+// And `workflow <verb>`: supercode's own board, in Hermes Kanban's format, and its dispatcher
+// (`supercode workflow <verb>` hands every verb but `load` here; board/cli.mjs).
+//
 // Everything it prints is one JSON object per line on stdout.
 
 import { existsSync, mkdirSync, rmdirSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
@@ -559,6 +562,19 @@ async function main() {
       process.exit(1);
     }
   }
+  if (argv[0] === 'workflow') {
+    // supercode's own board and its dispatcher (`supercode workflow <verb>`, board/cli.mjs)
+    const { runWorkflow } = await import('../board/cli.mjs');
+    try {
+      const code = await runWorkflow(argv.slice(1));
+      await closeWorld();
+      process.exit(code);
+    } catch (error) {
+      process.stderr.write(`supercode workflow: ${error.message ?? error}\n`);
+      await closeWorld();
+      process.exit(1);
+    }
+  }
   if (argv[0] === 'access') {
     await accessMain(argv.slice(1));
     return;

package/board.mjs

@@ -1,71 +1,62 @@
-// The board's dispatcher (docs/plans/hermes-compat.md row 14). A home's board is Hermes's: `kanban.db` at
-// the root, above the profiles, in Hermes's schema, written by Hermes's code. Where a Hermes gateway
-// would host the dispatcher, the orchestrator hosts it the same way: gated by `kanban.dispatch_in_gateway`
-// (and `HERMES_KANBAN_DISPATCH_IN_GATEWAY`), holding Hermes's one-dispatcher lock, one tick every
-// `kanban.dispatch_interval_seconds` (60, at least 1), the first after five seconds; each tick is Hermes's
-// own (`kanbanTick`). What differs is the worker: Hermes's spawn runs `HERMES_BIN`, here a wrapper that
-// starts `bin/hermes-worker.mjs` on this daemon's own runtime, so each task runs on its assignee
-// profile's worker harness. `hermes kanban` reads and writes the same file.
-import { createHash } from 'node:crypto';
-import { chmodSync, mkdirSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+// The home's board, dispatched while the orchestrator serves the home (docs/architecture/orchestrator.md §2.9,
+// 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: gated by `kanban.dispatch_in_gateway` (and
+// `HERMES_KANBAN_DISPATCH_IN_GATEWAY`), holding the board's one-dispatcher lock (`kanban/.dispatcher.lock`, the
+// lock Hermes's gateways take, so the two never dispatch one board together), one tick every
+// `kanban.dispatch_interval_seconds` (60, at least 1), the first after five seconds. 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 { hermesInstall, kanbanTick } from './hermes-cli.mjs';
 import { holdDispatcherLock } from './hermes-locks.mjs';
+import { summary } from './board/cli.mjs';
 
-const WORKER = fileURLToPath(new URL('./bin/hermes-worker.mjs', import.meta.url));
+const ENTRY = fileURLToPath(new URL('./bin/orchestrator.mjs', import.meta.url));
 
-/** The `HERMES_BIN` for a root: a script that runs the worker command on this very runtime. */
-function workerCommand(root) {
-  const dir = join(process.env.XDG_STATE_HOME || join(homedir(), '.local', 'state'), 'supercode', 'hermes-home', createHash('sha256').update(resolve(root)).digest('hex').slice(0, 16));
-  mkdirSync(dir, { recursive: true });
-  const file = join(dir, 'hermes-worker');
-  writeFileSync(file, `#!/bin/sh\nexec ${JSON.stringify(process.execPath)} ${JSON.stringify(WORKER)} "$@"\n`);
-  chmodSync(file, 0o755);
-  return file;
+function dispatchOnce(root) {
+  return new Promise((done) => {
+    const child = spawn(process.execPath, [ENTRY, 'workflow', 'dispatch', '--root', root, '--json'], { stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
+    let out = '';
+    let err = '';
+    child.stdout.setEncoding('utf8').on('data', (c) => { out += c; });
+    child.stderr.setEncoding('utf8').on('data', (c) => { err = (err + c).slice(-2000); });
+    child.on('error', (error) => done({ error: error.message }));
+    child.on('close', () => {
+      const line = out.trim().split('\n').pop();
+      try { done({ reports: JSON.parse(line) }); } catch { done({ error: (err || out).trim().slice(-500) || 'no answer' }); }
+    });
+  });
 }
 
-/** Start the board's dispatcher for the home at `root`; answers `{ stop }`, or null when it does not dispatch. */
+/** Start the board's dispatcher for the home at `root`; answers `{ tick, stop }`, or null when it does not dispatch. */
 export async function startBoard({ root, config = {}, log = () => {} }) {
   const kanban = config.kanban ?? {};
   const off = String(process.env.HERMES_KANBAN_DISPATCH_IN_GATEWAY ?? '').trim().toLowerCase();
   if (['0', 'false', 'no', 'off'].includes(off)) { log('info', 'board: not dispatched (HERMES_KANBAN_DISPATCH_IN_GATEWAY)'); return null; }
   if (kanban.dispatch_in_gateway === false) { log('info', 'board: not dispatched (kanban.dispatch_in_gateway: false)'); return null; }
-  const install = hermesInstall();
-  if (!install?.python) { log('warn', 'board: not dispatched; the board is Hermes\'s and no Hermes is installed on PATH'); return null; }
   let lock;
-  try { lock = await holdDispatcherLock(root, { python: install.python }); }
+  try { lock = await holdDispatcherLock(root); }
   catch (error) { log('info', `board: not dispatched: ${error.message}`); return null; }
-  const env = {
-    HERMES_BIN: workerCommand(root),
-    PATH: `${dirname(process.execPath)}:${process.env.PATH ?? ''}`,
-    ...(process.env.SUPERCODE_BIN ? { SUPERCODE_BIN: process.env.SUPERCODE_BIN } : {}),
-    ...(process.env.XDG_STATE_HOME ? { XDG_STATE_HOME: process.env.XDG_STATE_HOME } : {}),
-  };
   const seconds = Math.max(Number(kanban.dispatch_interval_seconds) || 60, 1);
   let running = false;
   let stopped = false;
   const said = new Set();
-  // what a Hermes gateway does around the dispatcher and this one does not, said once per board
-  const unserved = (board) => {
-    if (board.subscriptions && !said.has(`subs:${board.board}`)) { said.add(`subs:${board.board}`); log('warn', `board ${board.board}: ${board.subscriptions} chat subscription(s) are delivered by Hermes's gateway notifier, which this orchestrator does not run`); }
-    if (board.triage && !said.has(`triage:${board.board}`)) { said.add(`triage:${board.board}`); log('warn', `board ${board.board}: ${board.triage} triage task(s) wait for decomposition, which Hermes's gateway runs on its auxiliary model and this orchestrator does not`); }
-  };
   const tick = async () => {
     if (running || stopped) return;
     running = true;
     try {
-      for (const board of await kanbanTick(root, env)) {
-        if (board.error) log('warn', `board ${board.board}: ${board.error}`);
-        unserved(board);
-        for (const [task, assignee] of board.spawned ?? []) log('info', `board ${board.board}: ${task} spawned for ${assignee}`);
-        for (const [what, ids] of [['reclaimed', board.reclaimed], ['crashed', board.crashed], ['timed out', board.timed_out]]) {
-          if (Array.isArray(ids) && ids.length) log('info', `board ${board.board}: ${what} ${ids.join(', ')}`);
-        }
+      const { reports, error } = await dispatchOnce(root);
+      if (error) { log('warn', `board: tick failed: ${error}`); return; }
+      for (const r of reports) {
+        const line = summary(r);
+        if (!line.endsWith('nothing to do')) log(r.error ? 'warn' : 'info', line);
+        for (const [task, why] of r.failed ?? []) log('warn', `board ${r.board}: ${task} did not start: ${why}`);
+        for (const [task, to, why] of r.undelivered ?? []) log('warn', `board ${r.board}: a notice for ${task} to ${to} was not delivered: ${why}`);
+        if (r.chat_subscriptions && !said.has(`subs:${r.board}`)) { said.add(`subs:${r.board}`); log('warn', `board ${r.board}: ${r.chat_subscriptions} subscription(s) name a chat platform, which Hermes's gateway notifier serves and this dispatcher does not (it tells supercode sessions)`); }
+        if (r.triage && !said.has(`triage:${r.board}`)) { said.add(`triage:${r.board}`); log('warn', `board ${r.board}: ${r.triage} triage card(s) wait for decomposition, which Hermes's gateway runs on its auxiliary model and this dispatcher does not`); }
+        if (r.nonspawnable?.length && !said.has(`lane:${r.board}`)) { said.add(`lane:${r.board}`); log('warn', `board ${r.board}: ${r.nonspawnable.length} card(s) name an assignee that is no profile of this home, and wait`); }
       }
-    } catch (error) {
-      log('warn', `board: tick failed: ${error.message}`);
     } finally {
       running = false;
     }
@@ -73,7 +64,7 @@ export async function startBoard({ root, config = {}, log = () => {} }) {
   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 task on its assignee's worker`);
+  log('info', `board: dispatching every ${seconds}s, each card as its profile's worker says`);
   return {
     tick,
     stop() { stopped = true; clearTimeout(first); clearInterval(timer); lock.release(); },

package/hermes-cli.mjs

@@ -367,57 +367,6 @@ export function hermesSchedule(profileDir, text) {
   return out;
 }
 
-// One tick of Hermes's board dispatcher, as a Hermes gateway runs it (gateway/kanban_watchers.py
-// `_kanban_dispatcher_watcher`): the home's `kanban:` settings read as the gateway reads them, then
-// `kanban_db.dispatch_once` on every board. Hermes claims, reclaims, promotes and spawns; its spawn runs
-// `HERMES_BIN`, which the caller sets to the orchestrator's worker command.
-const KANBAN_TICK = `
-import json, sys
-a = json.loads(sys.stdin.read())
-from hermes_cli.config import load_config
-from hermes_cli import kanban_db as kb
-cfg = ((load_config() or {}).get("kanban") or {})
-def pos_int(v):
-    try: v = int(v)
-    except (TypeError, ValueError): return None
-    return v if v >= 1 else None
-max_in_progress = kb.resolve_max_in_progress(pos_int(cfg.get("max_in_progress")))
-try: failure_limit = int(cfg.get("failure_limit", kb.DEFAULT_FAILURE_LIMIT))
-except (TypeError, ValueError): failure_limit = kb.DEFAULT_FAILURE_LIMIT
-if failure_limit < 1: failure_limit = kb.DEFAULT_FAILURE_LIMIT
-try: stale = int(cfg.get("dispatch_stale_timeout_seconds", 0) or 0)
-except (TypeError, ValueError): stale = 0
-default_assignee = (cfg.get("default_assignee") or "").strip() or None
-try: boards = kb.list_boards(include_archived=False)
-except Exception: boards = [kb.read_board_metadata(kb.DEFAULT_BOARD)]
-out = []
-for b in boards:
-    slug = b.get("slug") or kb.DEFAULT_BOARD
-    conn = None
-    try:
-        conn = kb.connect(board=slug)
-        r = kb.dispatch_once(conn, board=slug, max_spawn=cfg.get("max_spawn"), max_in_progress=max_in_progress,
-            failure_limit=failure_limit, stale_timeout_seconds=stale, default_assignee=default_assignee,
-            max_in_progress_per_profile=pos_int(cfg.get("max_in_progress_per_profile")),
-            reconcile_orphans=bool(cfg.get("reconcile_orphans", True)))
-        count = lambda sql: conn.execute(sql).fetchone()[0]
-        out.append({"board": slug, "spawned": [list(x) for x in r.spawned], "reclaimed": r.reclaimed, "crashed": r.crashed,
-            "timed_out": r.timed_out, "skipped_locked": bool(getattr(r, "skipped_locked", False)),
-            "subscriptions": count("SELECT COUNT(*) FROM kanban_notify_subs"), "triage": count("SELECT COUNT(*) FROM tasks WHERE status = 'triage'")})
-    except Exception as error:
-        out.append({"board": slug, "error": str(error)})
-    finally:
-        if conn is not None: conn.close()
-print("@@hermes@@" + json.dumps(out, default=str))
-`;
-
-/** One dispatcher tick over the board at `root` (Hermes's `kanban_home`), `env` adding `HERMES_BIN` and the like. */
-export async function kanbanTick(root, env = {}) {
-  const install = hermesInstall();
-  if (!install?.python) throw new Error('the board is Hermes\'s, and no Hermes is installed on PATH');
-  return hermesAnswer('kanban dispatch', await python(install, KANBAN_TICK, {}, { ...hermesEnv(install, root), ...env }, 120_000));
-}
-
 /**
  * Hermes's MCP trust gate for a relayed tool call (tools/mcp_tool.py `_trust_gate_check`): a tool of one of the
  * profile's servers configured anything but `trust: full` (unset is full) is asked in a conversation and denied

package/kanban-worker.mjs

@@ -1,12 +1,10 @@
-// A worker for one board task (docs/plans/hermes-compat.md row 14). Hermes's dispatcher spawns its worker
-// as `hermes -p <assignee> --cli --accept-hooks [--skills <s>]… [-m <model> [--provider <p>]]
-// [--reasoning <e>] [--toolsets <t>] chat -q "work kanban task <id>" [-Q]`, detached, in the task's
-// workspace, its output to the task's log, the task in its environment (`KANBAN_ENV`), and watches the
-// pid. The orchestrator's loop runs that dispatcher with `HERMES_BIN` naming `bin/hermes-worker.mjs`, so
-// this is the process Hermes spawned and watches: it runs the assignee profile's own worker for the one
-// query, with Hermes's task protocol, the task's skills and the home's memory in its system prompt and the
-// board's tools on its door, prints the answer to the log and exits, as `hermes chat -q` does. A profile
-// whose worker is Hermes runs Hermes itself.
+// A worker for one board task (docs/plans/hermes-compat.md row 14). The board's dispatcher (`board/dispatch.mjs`)
+// starts a headless profile's worker as Hermes's dispatcher starts its own: `-p <assignee> --cli --accept-hooks
+// [--skills <s>]… [-m <model> [--provider <p>]] [--reasoning <e>] chat -q "work kanban task <id>"`, detached, in the
+// task's workspace, its output to the task's log, the task in its environment (`KANBAN_ENV`), and watches the pid.
+// This is that process: it runs the assignee profile's own worker for the one query, with Hermes's task protocol,
+// the task's skills and the home's memory in its system prompt and the board's tools on its door, prints the answer
+// to the log and exits, as `hermes chat -q` does. A profile whose worker is Hermes runs Hermes itself.
 import { spawn } from 'node:child_process';
 import { existsSync, statSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';

package/ontology.d.ts

@@ -208,7 +208,10 @@ export interface Job {
   failure_deliver?: Target | null;
   /** The creating conversation. */
   origin?: JobOrigin | null;
-  /** Hermes: mirror the fire's output into the target conversation's transcript. */
+  /**
+   * The fire is a turn in the live session of the conversation it delivers to (steering a running turn where
+   * the worker allows), instead of a session of its own; Hermes mirrors it into that transcript.
+   */
   attach_to_session?: boolean | null;
   /** Remaining-runs counter for `once` jobs. */
   repeat?: Repeat | null;
@@ -540,6 +543,16 @@ export interface Worker {
   locator?: string | null;
 }
 
+/** Whose Claude home (or harness home) a worker runs in. */
+export type WorkerHome =
+  /** The profile folder is the harness's whole config home (its persona, skills and MCP servers only). */
+  | 'profile'
+  /**
+   * The user's own harness home (their instructions, skills, hooks, plugins, MCP servers and login), with the
+   * profile's persona and skills brought in beside it for the session.
+   */
+  | 'user';
+
 /** The worker specification (O-record; Hermes has no worker choice). */
 export interface WorkerSpec {
   /** Any registry id whose runtime can start a session. */
@@ -554,4 +567,21 @@ export interface WorkerSpec {
   env?: Record<string, EnvValue>;
   /** Permission prompt policy. */
   permission?: PermissionPolicy;
+  /** Whose harness home the worker runs in. */
+  home?: WorkerHome;
+  /** How the board runs this profile's tasks. */
+  surface?: WorkerSurface;
+  /** At most this many of the profile's board tasks run at once; the rest wait in `ready`. */
+  capacity?: number | null;
 }
+
+/** How a board task's session runs when the board dispatches it to this profile. */
+export type WorkerSurface =
+  /** Hermes's worker: one query, headless, closed when it answers. */
+  | 'headless'
+  /**
+   * An interactive session in a terminal pane on the machine the card names, started with a
+   * session id the dispatcher chose, kept open, resumed when lost and replaced from the card only
+   * when it cannot be resumed.
+   */
+  | 'pane';

package/orchestration.mjs

@@ -155,6 +155,11 @@ export async function load(root) {
   return { state: stateOf(orchestration), vault };
 }
 
+/** The home at `root` as the IR reads it, and nothing written: a reader's view (the board's lanes and settings). */
+export async function read(root) {
+  return (await through((d) => d.orchestrationLoad({ root }))).orchestration;
+}
+
 /** `save(state, root)` — our folder, canonical and byte-stable: an artifact whose record has not changed keeps its bytes. */
 export async function save(state, root = state.root) {
   await through((d) => d.orchestrationSave({ root, orchestration: persistedView(state) }));

package/package.json

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

package/reducer.mjs

@@ -549,8 +549,8 @@ function handleTick(state, ev, effects) {
 // ---------------------------------------------------------------- restart / adapter / operator
 
 // §4.7 on a clean stop: the daemon closes every runtime, so each binding that held one keeps it as the runtime to
-// resume, as a crash's pass marks it, and the next line reopens the same session. A turn cut off mid-way is told so
-// on its surface; an idle binding is not.
+// resume, as a crash's pass marks it, and the restart reopens the same session (a clean stop is a restart's). A turn
+// cut off mid-way is told so on its surface; an idle binding is not.
 function handleStopping(state, ev, effects) {
   const rt = ensureRuntime(state);
   for (const profile of Object.values(state.profiles)) {
@@ -558,6 +558,8 @@ function handleStopping(state, ev, effects) {
       if (b.ended_at || ks.includes('#') || !b.residue?.runtime_id) continue;
       b.residue.resume_runtime_id = b.residue.runtime_id;
       delete b.residue.runtime_id;
+      // a stop for a restart: what was live now is live again once the daemon is back (handleRestart)
+      if (b.key.platform !== 'webhook' && b.key.platform !== 'cron') b.residue.reopen_at_start = true;
       if (rt.turns[leaseId(profile.name, ks)] && !b.recurrence && b.key.platform !== 'webhook' && b.key.platform !== 'cron') {
         b.residue.interrupted_at = ev.at;
         reply(state, profile, b.key, REPLY.interrupted, ev.at, effects);
@@ -579,7 +581,16 @@ function handleRestart(state, ev, effects) {
     // attaches where the worker's door allows it and marks the rest
     // interrupted (`binding_interrupted` below).
     for (const [ks, b] of Object.entries(profile.bindings)) {
-      if (b.ended_at || ks.includes('#') || !b.residue?.runtime_id) continue;
+      if (b.ended_at || ks.includes('#')) continue;
+      // one the clean stop closed reopens its own session now, so its conversation stays reachable (a message, a
+      // voice line) rather than waiting for its next inbound
+      if (!b.residue?.runtime_id) {
+        if (!b.residue?.reopen_at_start) continue;
+        delete b.residue.reopen_at_start;
+        live += 1;
+        startWorker(state, profile, ks, effects);
+        continue;
+      }
       live += 1;
       // a message arriving while the attach is in flight queues behind it,
       // rather than starting a fresh runtime that would replace the session