@volter/supercode-orchestrator 0.4.22 → 0.4.23

package/board/cli.mjs

@@ -28,12 +28,12 @@ Hermes Kanban's verbs, with their flags:
   comment <id> <text> [--author] [--max-len]   attach <id> <path> [--name] [--content-type]   attachments <id>   attach-rm <n>
   complete <id>... [--result] [--summary] [--metadata JSON]   edit <id> --result [--summary] [--metadata]
   block <id> [reason] [--kind dependency|needs_input|capability|transient] [--ids ...]   schedule <id> [reason] [--ids ...]
-  unblock <id>...   request-review <id> [--summary] [--reviewer]   request-changes <id> <reason>   reopen-review <id>...
+  unblock <id>... [--reason]   request-review <id> [--summary] [--reviewer] [--force]   request-changes <id> <reason>   reopen-review <id>...   reopen <id>... [--reason]
   promote <id> [reason] [--ids ...] [--force] [--dry-run]   archive <id>... [--rm <id>...]
   specify <id> [--title --body] [--all]   decompose <id> [--child "<title>[@<profile>]"]... [--all]
   diagnostics [--task] [--severity]   stats   assignees   log <id> [--tail N]   tail <id>   watch [--assignee] [--kinds]
   notify-subscribe <id> --platform P --chat-id C [--thread-id]   notify-list [<id>]   notify-unsubscribe <id> --platform P --chat-id C
-  dispatch [--dry-run] [--max N] [--failure-limit N]   daemon   gc [--event-retention-days] [--log-retention-days]   repair
+  dispatch [--dry-run] [--max N] [--failure-limit N]   daemon [--interval S] [--max N] [--failure-limit N] [--pidfile F] [--verbose]   gc [--event-retention-days] [--log-retention-days]   repair
   pause [reason] · resume   (Hermes's emergency stop, the ESTOP file: new starts stop, running sessions go on)
 
 supercode's own:
@@ -462,10 +462,18 @@ export async function runWorkflow(argv) {
     case 'unblock': {
       need(1, 'a card id');
       const results = ids().map((t) => [t, withBoard((b) => engine.unblock(b, t))]);
+      // Hermes records the reason as a comment on each card it unblocks
+      if (args.reason) for (const [t] of results) withBoard((b) => engine.comment(b, t, callerName(), `UNBLOCK: ${args.reason}`));
       say(args, results.map(([t, s]) => `Unblocked ${t} → ${s}`).join('\n'), { ok: true, results }); return 0;
     }
-    case 'request-review': need(1, 'a card id'); withBoard((b) => engine.requestReview(b, id, { summary: args.summary ?? null, reviewer: args.reviewer ?? null, metadata: metadataOf(args.metadata) ?? null })); say(args, `${id} → review`, { ok: true }); return 0;
+    case 'request-review': need(1, 'a card id'); withBoard((b) => engine.requestReview(b, id, { summary: args.summary ?? null, reviewer: args.reviewer ?? null, metadata: metadataOf(args.metadata) ?? null, force: Boolean(args.force) })); say(args, `${id} → review`, { ok: true }); return 0;
     case 'request-changes': need(2, 'a card id and the reason'); withBoard((b) => engine.requestChanges(b, id, { reason: rest.slice(1).join(' '), reviewer: args.reviewer ?? callerName() })); say(args, `${id} sent back for changes`, { ok: true }); return 0;
+    case 'reopen': {
+      // a done card back to work; the cards that built on it are invalidated with it (Hermes's reopen)
+      need(1, 'a card id');
+      const results = ids().map((t) => [t, withBoard((b) => engine.reopen(b, t, { author: callerName(), reason: args.reason ?? null }))]);
+      say(args, results.map(([t, r]) => `Reopened ${t} → ${r.status}${r.invalidated?.length ? ` (invalidated ${r.invalidated.map((d) => d.id).join(', ')})` : ''}`).join('\n'), { ok: true, results }); return 0;
+    }
     case 'reopen-review': {
       need(1, 'a card id');
       const results = ids().map((t) => [t, withBoard((b) => engine.reopenReview(b, t))]);
@@ -632,7 +640,7 @@ export async function runWorkflow(argv) {
       else for (const r of reports) process.stdout.write(`${summary(r)}\n`);
       return reports.some((r) => r.error) ? 1 : 0;
     }
-    case 'daemon': case 'serve': return serve(root);
+    case 'daemon': case 'serve': return serve(root, args);
 
     case 'gc': {
       const eventDays = Number(args['event-retention-days'] ?? 30);
@@ -923,7 +931,7 @@ function authorize(db, verb, rest, args, own) {
   }
   if (verb === 'boards') { if (!['list', 'ls', 'show', 'current', undefined].includes(rest[0])) refuse('does not change the home\'s boards'); return; }
   // verbs that act on the board rather than on a card are the manager's and the board's, never a card's session's
-  if (['pause', 'resume', 'swarm', 'dispatch', 'daemon', 'serve', 'gc', 'repair', 'adopt', 'close', 'move', 'reassign', 'assign', 'set-model', 'claim', 'reclaim', 'archive', 'promote', 'schedule', 'link', 'unlink', 'edit', 'reopen-review', 'attach-rm'].includes(verb)) refuse(`does not ${verb}; the fleet's manager does`);
+  if (['pause', 'resume', 'swarm', 'dispatch', 'daemon', 'serve', 'gc', 'repair', 'adopt', 'close', 'move', 'reassign', 'assign', 'set-model', 'claim', 'reclaim', 'archive', 'promote', 'schedule', 'link', 'unlink', 'edit', 'reopen-review', 'reopen', 'attach-rm'].includes(verb)) refuse(`does not ${verb}; the fleet's manager does`);
   if (args.all) refuse(`does not ${verb} every card; only its own`);
   const card = engine.getTask(db, rest[0]);
   if (!card) return; // the verb itself answers "no card"
@@ -969,8 +977,15 @@ export function summary(r) {
  * re-read every tick, so a profile's change takes effect without a restart). It holds the board's one-dispatcher
  * lock, as the daemon and Hermes's gateways do, so one dispatcher serves a board.
  */
-async function serve(root) {
+async function serve(root, args = {}) {
   const lock = await holdDispatcherLock(root);
+  // Hermes's daemon flags: --interval seconds, --max starts per tick, --failure-limit, --pidfile, --verbose
+  const override = {
+    ...(Number(args.interval) > 0 ? { interval: Number(args.interval) } : {}),
+    ...(Number(args.max) > 0 ? { maxSpawn: Number(args.max) } : {}),
+    ...(Number(args['failure-limit']) > 0 ? { failureLimit: Number(args['failure-limit']) } : {}),
+  };
+  if (args.pidfile) writeFileSync(args.pidfile, `${process.pid}\n`);
   let stopped = false;
   const stop = () => { stopped = true; };
   process.on('SIGTERM', stop);
@@ -985,11 +1000,12 @@ async function serve(root) {
       pausedSaid = Boolean(paused(root)) && pausedSaid;
       let interval = 60;
       try {
-        const { lanes, settings } = await laneState(root);
+        const state = await laneState(root);
+        const settings = { ...state.settings, ...override };
         interval = settings.interval;
-        for (const r of await tick({ root, lanes, settings })) {
+        for (const r of await tick({ root, lanes: state.lanes, settings })) {
           const said = summary(r);
-          if (!said.endsWith('nothing to do')) log(said);
+          if (!said.endsWith('nothing to do') || args.verbose) log(said);
           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;
@@ -1005,6 +1021,7 @@ async function serve(root) {
     }
   } finally {
     lock.release();
+    if (args.pidfile) { try { unlinkSync(args.pidfile); } catch { /* gone */ } }
   }
   log('stopped');
   return 0;

package/board/dispatch.mjs

@@ -94,12 +94,24 @@ function pidAlive(pid) {
 
 // ------------------------------------------------------------------ settings
 
+/**
+ * Hermes's default for kanban.max_in_progress when none is set: one worker per 512 MiB of the host's memory, between
+ * two and eight, from /proc/meminfo; none where that cannot be read (which caps nothing).
+ */
+function derivedMaxInProgress() {
+  try {
+    const total = Number(/^MemTotal:\s+(\d+)/m.exec(readFileSync('/proc/meminfo', 'utf8'))?.[1]);
+    return Number.isFinite(total) && total > 0 ? Math.max(2, Math.min(Math.floor(total / 1024 / 512), 8)) : null;
+  } catch { return null; }
+}
+
 /** The board's settings: the home's `kanban:` block, Hermes's keys and supercode's own (`machines`, `session_grace_seconds`). */
 export function boardSettings(kanban = {}) {
   const pos = (v) => (Number.isInteger(Number(v)) && Number(v) >= 1 ? Number(v) : null);
   return {
     failureLimit: pos(kanban.failure_limit) ?? DEFAULT_FAILURE_LIMIT,
-    maxInProgress: pos(kanban.max_in_progress),
+    maxInProgress: pos(kanban.max_in_progress) ?? derivedMaxInProgress(),
+    crashGrace: Number.isInteger(Number(process.env.HERMES_KANBAN_CRASH_GRACE_SECONDS)) && process.env.HERMES_KANBAN_CRASH_GRACE_SECONDS !== '' && Number(process.env.HERMES_KANBAN_CRASH_GRACE_SECONDS) >= 0 ? Number(process.env.HERMES_KANBAN_CRASH_GRACE_SECONDS) : 30,
     perProfile: pos(kanban.max_in_progress_per_profile),
     defaultAssignee: String(kanban.default_assignee ?? '').trim() || null,
     reviewDispatch: kanban.review_dispatch !== false,
@@ -171,7 +183,7 @@ function supervise(board, fleet, settings, report) {
           if (Number(task.claim_expires) <= t + 60) extendClaim(db, id, { ttl: settings.ttl, reason: 'pid_alive', extra: { worker_pid: session.pid } });
           return;
         }
-        if (t - Number(session.launched_at ?? 0) < 30) return;
+        if (t - Number(session.launched_at ?? 0) < settings.crashGrace) return;
         // how the worker ended, from the exit code its wrapper wrote (Hermes reads its reaped children's)
         const code = session.exit_file && existsSync(session.exit_file) ? Number(readFileSync(session.exit_file, 'utf8').trim()) : null;
         if (code === 75) {
@@ -337,7 +349,7 @@ function start(board, fleet, lanes, settings, report, { only = null, hostRunning
   const stop = paused(board.root);
   if (stop) { report.paused = stop; return; }
   const pressure = memoryPressure();
-  let headlessStarted = 0;
+  let localStarted = 0;
   const order = 'ORDER BY priority DESC, created_at ASC';
   const ready = board.db.prepare(`SELECT id, status, assignee FROM tasks WHERE status = 'ready' AND claim_lock IS NULL ${order}`).all();
   const review = settings.reviewDispatch ? board.db.prepare(`SELECT id, status, assignee FROM tasks WHERE status = 'review' AND claim_lock IS NULL ${order}`).all() : [];
@@ -357,11 +369,11 @@ function start(board, fleet, lanes, settings, report, { only = null, hostRunning
       const task = getTask(db, row.id);
       if (!task || task.status !== row.status || task.claim_lock) return null;
       let why = guard(db, task, lane, fleet, settings, lanesBudget);
-      if (!why && lane.surface !== 'pane') {
-        // a one-shot worker runs on this machine: its memory, and Hermes's respawn guard
-        if (pressure === 'critical' || (pressure === 'elevated' && headlessStarted >= 1)) why = `this machine's memory pressure is ${pressure}; the card starts when it eases`;
-        else why = respawnGuard(db, task, settings, row.status);
-      }
+      // this machine's memory bounds what starts here: every one-shot worker, and a pane session on this machine
+      const here = lane.surface !== 'pane' || normalMachine(task.machine ?? '') === localMachine();
+      if (!why && here && (pressure === 'critical' || (pressure === 'elevated' && localStarted >= 1))) why = `this machine's memory pressure is ${pressure}; the card starts when it eases`;
+      // Hermes's respawn guard, on every lane (a pane card whose session is still live is kept, never started twice)
+      if (!why) why = respawnGuard(db, task, settings, row.status);
       if (why) { noteGuard(db, row.id, why); report.queued.push([row.id, why]); return null; }
       if (!row.assignee) {
         db.prepare('UPDATE tasks SET assignee = ? WHERE id = ?').run(assignee, row.id);
@@ -375,7 +387,7 @@ function start(board, fleet, lanes, settings, report, { only = null, hostRunning
       const session = lane.surface === 'pane'
         ? launchPane(board, claimed.task, claimed.runId, lane, fleet, { input: row.status === 'review' ? reviewAsk(board, claimed.task) : null })
         : launchHeadless(board, claimed.task, claimed.runId, lane, settings);
-      if (lane.surface !== 'pane') headlessStarted += 1;
+      if (lane.surface !== 'pane' || normalMachine(claimed.task.machine ?? '') === localMachine()) localStarted += 1;
       if (budget) budget.left -= 1;
       if (readyBudget && readyBudget !== budget) readyBudget.left -= 1;
       report.started.push([row.id, session.address ?? `pid ${session.pid}`, session.mode]);
@@ -664,9 +676,9 @@ function notice(kind, task, p, role) {
   }
 }
 
-function send(from, label, to, body, key) {
+function send(from, label, to, body, key, { queue = false } = {}) {
   const request = {
-    op: 'send', from, from_name: `${label} board`, to, queue: false, id: key,
+    op: 'send', from, from_name: `${label} board`, to, queue, id: key,
     body: `[Board notice from the ${label} board] ${body}\n\n(An automated notice from the board's dispatcher; replies to this address go nowhere.)`,
   };
   const r = sc(['message', 'remote-deliver'], { input: JSON.stringify(request), timeout: 60_000 });
@@ -707,7 +719,8 @@ function notify(board, fleet, report) {
           text = c ? `💬 card ${sub.task_id}, ${p.author}:\n${c.body}` : null;
         } else text = notice(ev.kind, task, p, role);
         if (text) {
-          send(from, board.label, sub.chat_id, text, `board-${sub.task_id}-${ev.id}-${sub.chat_id.slice(-12)}`);
+          // Hermes's delivery modes: `notify` is passive (read at the session's next turn), `wake`/`notify+wake` start its turn
+          send(from, board.label, sub.chat_id, text, `board-${sub.task_id}-${ev.id}-${sub.chat_id.slice(-12)}`, { queue: sub.delivery_mode === 'notify' });
           report.notified.push([sub.task_id, ev.kind, sub.chat_id]);
         }
         cursor = ev.id;
@@ -735,7 +748,7 @@ const CHAT_KINDS = ['completed', 'blocked', 'gave_up', 'crashed', 'timed_out', '
  * A chat-platform subscription's events, sent through the orchestrator's own channel adapters (the daemon hosts them;
  * `serve` hosts none, as a Hermes CLI without its gateway delivers none). Answers what was sent and what failed.
  */
-export async function notifyChats(root, adapters, log = () => {}) {
+export async function notifyChats(root, adapters, log = () => {}, wake = null) {
   const sent = [];
   for (const slug of listBoards(root)) {
     const board = openBoard(root, slug);
@@ -755,6 +768,12 @@ export async function notifyChats(root, adapters, log = () => {}) {
           if (text) {
             // a completed card's deliverables go with it as uploads, as Hermes's notifier sends them
             const files = ev.kind === 'completed' ? artifactsOf(payload, task).map((path) => ({ path })) : [];
+            const mode = sub.delivery_mode || 'notify';
+            // `wake`/`notify+wake`: the chat's own session gets the event as a turn (Hermes's wake), through the daemon
+            if (mode !== 'notify' && wake) {
+              try { await wake(sub, `${slug !== 'default' ? `[${slug}] ` : ''}${text}`); } catch (error) { log('warn', `board ${slug}: waking ${sub.platform}:${sub.chat_id} for ${sub.task_id} failed: ${error.message}`); }
+            }
+            if (mode === 'wake') { sent.push([sub.task_id, ev.kind, `${sub.platform}:${sub.chat_id} (wake)`]); cursor = ev.id; continue; }
             try {
               await adapter.send({ kind: 'explicit', platform: sub.platform, chat_id: sub.chat_id, ...(sub.thread_id ? { thread_id: sub.thread_id } : {}) }, { text: `${slug !== 'default' ? `[${slug}] ` : ''}${text}`, ...(files.length ? { files } : {}) });
               sent.push([sub.task_id, ev.kind, `${sub.platform}:${sub.chat_id}`]);

package/board/engine.mjs

@@ -65,7 +65,14 @@ export function endRun(db, taskId, { outcome, status = null, summary = null, err
   const row = one(db, 'SELECT current_run_id FROM tasks WHERE id = ?', taskId);
   if (!row?.current_run_id) return null;
   const runId = Number(row.current_run_id);
-  const keep = metadata === undefined ? one(db, 'SELECT metadata FROM task_runs WHERE id = ?', runId)?.metadata ?? null : (metadata ? JSON.stringify(metadata) : null);
+  const was = one(db, 'SELECT metadata FROM task_runs WHERE id = ?', runId)?.metadata ?? null;
+  const keep = metadata === undefined ? was : (metadata ? JSON.stringify(metadata) : null);
+  // a run taken back (reclaim, archive, a reopened ancestor) stops its one-shot worker on this machine, as Hermes
+  // terminates a reclaimed worker (a board's one-shot workers run where the board is); a pane session is a person-visible session and is never killed from the board
+  const worker = outcome === 'reclaimed' ? json(was, {})?.supercode : null;
+  if (worker?.surface === 'headless' && worker.pid) {
+    try { process.kill(-worker.pid, 'SIGTERM'); } catch { try { process.kill(worker.pid, 'SIGTERM'); } catch { /* gone */ } }
+  }
   run(db, `UPDATE task_runs SET status = ?, outcome = ?, summary = ?, error = ?, metadata = ?, ended_at = ?, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL
            WHERE id = ? AND ended_at IS NULL`, status ?? outcome, outcome, summary, error, keep, now(), runId);
   run(db, 'UPDATE tasks SET current_run_id = NULL WHERE id = ?', taskId);
@@ -417,11 +424,22 @@ export function unblock(board, id) {
 }
 
 /** Implementation done, awaiting review (not a block): the review lane, optionally under a reviewer profile. */
-export function requestReview(board, id, { summary = null, metadata = null, reviewer = null } = {}) {
+export function requestReview(board, id, { summary = null, metadata = null, reviewer = null, force = false } = {}) {
   return tx(board, (db) => {
     const task = must(db, id);
     if (!parentsDone(db, id)) throw new Error(`${id} waits on parents that are not done`);
     if (!['running', 'ready'].includes(task.status)) throw new Error(`${id} is ${task.status}; only a running or ready card goes to review`);
+    // a live claim is its worker's to hand off; anyone else says so on purpose (Hermes's guard)
+    if (task.status === 'running' && task.claim_lock && !force) throw new Error(`${id} is running under a live claim; its worker requests review, or pass --force to override on purpose`);
+    // a re-review goes back to the reviewer who asked for the changes
+    if (!reviewer) {
+      const changed = one(db, "SELECT id FROM task_runs WHERE task_id = ? AND outcome = 'changes_requested' ORDER BY id DESC LIMIT 1", id);
+      if (changed) {
+        const asked = json(one(db, "SELECT payload FROM task_events WHERE task_id = ? AND run_id = ? AND kind = 'changes_requested' ORDER BY id DESC LIMIT 1", id, changed.id)?.payload, {}) ?? {};
+        if (!asked.reviewer) throw new Error(`${id}'s last changes request names no reviewer; pass --reviewer`);
+        reviewer = asked.reviewer;
+      }
+    }
     run(db, `UPDATE tasks SET status = 'review', claim_lock = NULL, claim_expires = NULL, worker_pid = NULL${reviewer ? ', assignee = ?' : ''} WHERE id = ?`, ...(reviewer ? [reviewer, id] : [id]));
     const runId = endRun(db, id, { outcome: 'review_requested', status: 'review', summary, metadata: metadata ?? undefined }) ?? (summary || metadata ? synthesizeRun(db, id, { outcome: 'review_requested', summary, metadata }) : null);
     event(db, id, 'review_requested', { summary: String(summary ?? '').trim().split('\n')[0].slice(0, 400) || null, implementer: task.assignee, reviewer }, runId);
@@ -442,6 +460,35 @@ export function requestChanges(board, id, { reason = null, reviewer = null, impl
   });
 }
 
+/**
+ * A done (or archived) card reopened: back to ready (todo while a parent is open), and every descendant that had moved on
+ * because of it pulled back to todo (Hermes's dashboard reopen, `invalidate_descendants_for_parent_reopen`).
+ */
+export function reopen(board, id, { author = 'user', reason = null } = {}) {
+  return tx(board, (db) => {
+    const task = must(db, id);
+    if (!['done', 'archived'].includes(task.status)) throw new Error(`${id} is ${task.status}; only a done or archived card is reopened`);
+    const status = parentsDone(db, id) ? 'ready' : 'todo';
+    run(db, 'UPDATE tasks SET status = ?, completed_at = NULL WHERE id = ?', status, id);
+    event(db, id, 'status', { status, reason: reason ?? 'reopened', previous_status: task.status });
+    const invalidated = [];
+    const t = now();
+    const rows = all(db, `WITH RECURSIVE d(id) AS (SELECT child_id FROM task_links WHERE parent_id = ? UNION SELECT l.child_id FROM task_links l JOIN d ON d.id = l.parent_id)
+                          SELECT t.id, t.status FROM d JOIN tasks t ON t.id = d.id ORDER BY t.id`, id);
+    for (const row of rows) {
+      if (!['ready', 'review', 'running', 'done'].includes(row.status)) continue;
+      const resume = row.status === 'review' ? 'review' : row.status === 'running' ? retryStatus(db, row.id) : 'ready';
+      const runId = row.status === 'running' ? endRun(db, row.id, { outcome: 'reclaimed', status: 'todo', summary: `ancestor ${id} reopened` }) : null;
+      run(db, "UPDATE tasks SET status = 'todo', completed_at = NULL, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL, current_run_id = NULL, consecutive_failures = 0 WHERE id = ?", row.id);
+      event(db, row.id, 'descendant_invalidated', { ancestor: id, prior_status: row.status, new_status: 'todo', resume_status: resume }, runId);
+      event(db, row.id, 'status', { status: 'todo', reason: 'ancestor_reopened', parent: id, previous_status: row.status, resume_status: resume }, runId);
+      run(db, 'INSERT INTO task_comments (task_id, author, body, created_at) VALUES (?, ?, ?, ?)', row.id, author, `Invalidated: ancestor ${id} was reopened; retracted from '${row.status}' to 'todo' (will resume via '${resume}').`, t);
+      invalidated.push({ id: row.id, prior_status: row.status });
+    }
+    return { status, invalidated };
+  });
+}
+
 export function schedule(board, id, reason = null) {
   return tx(board, (db) => {
     const task = must(db, id);
@@ -516,7 +563,7 @@ function recomputeIn(db, failureLimit = DEFAULT_FAILURE_LIMIT) {
 export function subscribeIn(db, id, address, role = 'creator') {
   const cursor = one(db, 'SELECT COALESCE(MAX(id), 0) AS c FROM task_events WHERE task_id = ?', id).c;
   run(db, `INSERT OR IGNORE INTO kanban_notify_subs (task_id, platform, chat_id, thread_id, chat_type, delivery_mode, delivery_metadata, created_at, last_event_id)
-           VALUES (?, 'supercode', ?, '', 'dm', 'notify', ?, ?, ?)`, id, address, JSON.stringify({ role }), now(), cursor);
+           VALUES (?, 'supercode', ?, '', 'dm', 'notify+wake', ?, ?, ?)`, id, address, JSON.stringify({ role }), now(), cursor);
 }
 
 export function subscribe(board, id, address, role = 'creator') {

package/board/tools.mjs

@@ -0,0 +1,169 @@
+// The board's tools for a worker the dispatcher started (docs/architecture/orchestrator.md §2.9): Hermes's fourteen
+// `kanban_*` tools, by the same names and arguments, answered by supercode's own engine on the board file. A worker is
+// scoped as Hermes scopes one: `HERMES_KANBAN_TASK` is its task (the default for `task_id`, and the only task its
+// lifecycle tools may change), `HERMES_KANBAN_RUN_ID` its run (a superseded run changes nothing), and the listing and
+// unblocking tools are the orchestrator's, not a worker's. Answers are JSON text: `{ ok: true, … }` or `{ error }`.
+import { mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { DEFAULT_BOARD, event, json, openBoard, tx } from './store.mjs';
+import * as engine from './engine.mjs';
+
+const ok = (fields = {}) => JSON.stringify({ ok: true, ...fields });
+const error = (message) => JSON.stringify({ error: message });
+
+// secrets a worker may paste into a handoff, masked before they are stored (Hermes redacts a handoff the same way)
+const SECRET = [
+  /\b(sk-[A-Za-z0-9_-]{16,}|sk-ant-[A-Za-z0-9_-]{16,}|ghp_[A-Za-z0-9]{20,}|gho_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|xox[abpr]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z_-]{30,})\b/g,
+  /\b(Bearer\s+)[A-Za-z0-9._~+/-]{16,}=*/g,
+  /\b((?:api[_-]?key|token|secret|password|passwd)\s*[:=]\s*)["']?[^\s"',;]{8,}/gi,
+];
+export function redact(value) {
+  if (typeof value === 'string') return SECRET.reduce((text, re) => text.replace(re, (m, a) => (m.startsWith(a) && a !== m ? `${a}***` : '***')), value);
+  if (Array.isArray(value)) return value.map(redact);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redact(v)]));
+  return value;
+}
+
+const LIFECYCLE = new Set(['kanban_complete', 'kanban_block', 'kanban_request_review', 'kanban_request_changes', 'kanban_heartbeat', 'kanban_attach', 'kanban_attach_url', 'kanban_unblock']);
+const ORCHESTRATOR_ONLY = new Set(['kanban_list', 'kanban_unblock']);
+
+/** One board tool call. `root` is the home; `env` the worker's task environment (`HERMES_KANBAN_*`). */
+export async function boardTool(root, name, args = {}, env = {}) {
+  const own = env.HERMES_KANBAN_TASK || null;
+  const runId = env.HERMES_KANBAN_RUN_ID ? Number(env.HERMES_KANBAN_RUN_ID) : null;
+  const author = env.HERMES_PROFILE || 'worker';
+  if (own && ORCHESTRATOR_ONLY.has(name)) return error(`${name} is the orchestrator's; a dispatched worker uses kanban_complete, kanban_block, kanban_heartbeat or kanban_comment for its own task`);
+  const tid = args.task_id || own;
+  if (!['kanban_list', 'kanban_create', 'kanban_link'].includes(name) && !tid) return error('task_id is required (or HERMES_KANBAN_TASK in the environment)');
+  if (own && LIFECYCLE.has(name) && tid !== own) return error(`worker is scoped to task ${own}; refusing to change ${tid}. Use kanban_comment to hand off to other tasks, or kanban_create for follow-up work.`);
+  const slug = args.board || env.HERMES_KANBAN_BOARD || DEFAULT_BOARD;
+  let board;
+  try { board = openBoard(root, slug); } catch (e) { return error(e.message); }
+  board.label = slug;
+  const current = () => tx(board, (db) => engine.getTask(db, tid));
+  // a worker whose run was superseded (reclaimed, re-dispatched) no longer speaks for the card
+  const ownRun = () => {
+    if (!own || tid !== own || !runId) return null;
+    const t = current();
+    return t && Number(t.current_run_id) !== runId ? `run ${runId} of ${tid} is no longer its current run; nothing was changed` : null;
+  };
+  try {
+    switch (name) {
+      case 'kanban_show': {
+        const card = tx(board, (db) => { const c = engine.showCard(db, tid); c.context = engine.cardContext(db, tid); return c; });
+        const t = card.task;
+        return JSON.stringify({
+          task: { id: t.id, title: t.title, body: t.body, assignee: t.assignee, status: t.status, tenant: t.tenant, priority: t.priority, workspace_kind: t.workspace_kind,
+            workspace_path: t.workspace_path, created_by: t.created_by, created_at: t.created_at, started_at: t.started_at, completed_at: t.completed_at, result: t.result,
+            current_run_id: t.current_run_id, model_override: t.model_override, provider_override: t.provider_override },
+          parents: card.parents.map((p) => p.id), children: card.children,
+          comments: card.comments, events: card.events.slice(-50), runs: card.runs.map((r) => ({ id: r.id, profile: r.profile, status: r.status, outcome: r.outcome, summary: r.summary, error: r.error, metadata: r.metadata, started_at: r.started_at, ended_at: r.ended_at })),
+          worker_context: card.context,
+        });
+      }
+      case 'kanban_list': {
+        const limit = args.limit === undefined ? 100 : Number(args.limit);
+        if (!Number.isInteger(limit) || limit < 1) return error('limit must be an integer >= 1');
+        const cards = tx(board, (db) => engine.listCards(db, { status: args.status ?? null, assignee: args.assignee ?? null, includeArchived: Boolean(args.include_archived) }))
+          .filter((t) => !args.tenant || t.tenant === args.tenant).slice(0, limit);
+        return ok({ tasks: cards.map((t) => ({ id: t.id, title: t.title, assignee: t.assignee, status: t.status, priority: t.priority, tenant: t.tenant, machine: t.machine })), count: cards.length });
+      }
+      case 'kanban_complete': {
+        const stale = ownRun(); if (stale) return error(stale);
+        const summary = args.summary ? redact(String(args.summary)) : null;
+        const result = args.result ? redact(String(args.result)) : null;
+        if (!summary && !result) return error('provide at least one of: summary (preferred), result');
+        let metadata = args.metadata === undefined || args.metadata === null ? null : redact(args.metadata);
+        if (metadata !== null && (typeof metadata !== 'object' || Array.isArray(metadata))) return error('metadata must be an object');
+        const artifacts = [args.artifacts].flat().filter((a) => typeof a === 'string' && a.trim()).map((a) => a.trim());
+        if (artifacts.length) metadata = { ...(metadata ?? {}), artifacts: [...new Set([...(metadata?.artifacts ?? []), ...artifacts])] };
+        // cards the handoff says it created must exist (Hermes refuses a handoff naming cards nobody made)
+        const created = [args.created_cards].flat().filter(Boolean).map(String);
+        if (created.length) {
+          const phantom = tx(board, (db) => created.filter((c) => !engine.getTask(db, c)));
+          if (phantom.length) {
+            tx(board, (db) => event(db, tid, 'completion_blocked_hallucination', { phantom_cards: phantom, verified_cards: created.filter((c) => !phantom.includes(c)) }));
+            return error(`created_cards names cards that do not exist: ${phantom.join(', ')}. Create them with kanban_create first, or leave them out.`);
+          }
+        }
+        if (env.HERMES_SESSION_ID && own === tid) metadata = { ...(metadata ?? {}), worker_session_id: env.HERMES_SESSION_ID };
+        engine.complete(board, tid, { summary, result, metadata });
+        return ok({ task_id: tid, status: 'done' });
+      }
+      case 'kanban_block': {
+        const stale = ownRun(); if (stale) return error(stale);
+        const status = engine.block(board, tid, { reason: args.reason ? redact(String(args.reason)) : null, kind: args.kind ?? null });
+        return ok({ task_id: tid, status });
+      }
+      case 'kanban_request_review': {
+        const stale = ownRun(); if (stale) return error(stale);
+        engine.requestReview(board, tid, { summary: args.summary ? redact(String(args.summary)) : null, metadata: args.metadata ? redact(args.metadata) : null, reviewer: args.reviewer ?? null, force: own === tid });
+        return ok({ task_id: tid, status: 'review' });
+      }
+      case 'kanban_request_changes': {
+        const stale = ownRun(); if (stale) return error(stale);
+        engine.requestChanges(board, tid, { reason: args.reason ? redact(String(args.reason)) : null, reviewer: author });
+        return ok({ task_id: tid });
+      }
+      case 'kanban_heartbeat': {
+        const stale = ownRun(); if (stale) return error(stale);
+        engine.heartbeat(board, tid, args.note ?? null);
+        return ok({ task_id: tid });
+      }
+      case 'kanban_comment': {
+        if (!String(args.body ?? '').trim()) return error('body is required');
+        const n = engine.comment(board, tid, author, redact(String(args.body)));
+        return ok({ task_id: tid, comment_id: n });
+      }
+      case 'kanban_attach': case 'kanban_attach_url': {
+        let data;
+        let filename = args.filename;
+        if (name === 'kanban_attach') {
+          if (!args.content_base64) return error('content_base64 is required');
+          data = Buffer.from(String(args.content_base64), 'base64');
+        } else {
+          if (!/^https?:\/\//.test(String(args.url ?? ''))) return error('url must be http(s)');
+          const res = await fetch(args.url);
+          if (!res.ok) return error(`fetching ${args.url}: HTTP ${res.status}`);
+          data = Buffer.from(await res.arrayBuffer());
+          filename ??= basename(new URL(args.url).pathname) || 'download';
+        }
+        if (data.length > 25 * 1024 * 1024) return error('an attachment is at most 25 MiB');
+        const safe = basename(String(filename ?? 'attachment')).replace(/[^A-Za-z0-9._ -]/g, '_') || 'attachment';
+        const dir = join(slug === DEFAULT_BOARD ? join(root, 'kanban', 'attachments') : join(root, 'kanban', 'boards', slug, 'attachments'), tid);
+        mkdirSync(dir, { recursive: true });
+        let path = join(dir, safe);
+        for (let n = 1; (() => { try { statSync(path); return true; } catch { return false; } })(); n += 1) path = join(dir, `${n}-${safe}`);
+        writeFileSync(path, data);
+        const id = engine.addAttachment(board, tid, { file: { path, size: data.length }, name: safe, contentType: args.content_type ?? null, author });
+        return ok({ task_id: tid, attachment_id: id, path });
+      }
+      case 'kanban_attachments':
+        return ok({ task_id: tid, attachments: tx(board, (db) => engine.attachments(db, tid)).map((a) => ({ id: a.id, filename: a.filename, size: a.size, content_type: a.content_type, path: a.stored_path })) });
+      case 'kanban_create': {
+        const workspace = args.workspace_kind ? `${args.workspace_kind}${args.workspace_path ? `:${args.workspace_path}` : ''}` : undefined;
+        const made = engine.createCard(board, {
+          title: args.title, body: args.body ? redact(String(args.body)) : null, assignee: args.assignee ?? null, parents: [args.parents ?? []].flat(), tenant: args.tenant ?? null,
+          priority: args.priority ?? 0, workspace, project: args.project ?? null, triage: Boolean(args.triage), idempotencyKey: args.idempotency_key ?? null,
+          maxRuntime: args.max_runtime_seconds ?? null, initialStatus: args.initial_status ?? null, skills: args.skills ?? null, model: args.model ?? null, provider: args.provider ?? null,
+          goal: args.goal_mode ? { maxTurns: args.goal_max_turns ?? null } : null, createdBy: author,
+        });
+        return ok({ task_id: made.id, existing: made.existing, status: tx(board, (db) => engine.getTask(db, made.id)).status });
+      }
+      case 'kanban_unblock':
+        return ok({ task_id: tid, status: engine.unblock(board, tid) });
+      case 'kanban_link':
+        if (!args.parent_id || !args.child_id) return error('parent_id and child_id are required');
+        engine.link(board, args.parent_id, args.child_id);
+        return ok({ parent_id: args.parent_id, child_id: args.child_id });
+      default:
+        return error(`no board tool ${name}`);
+    }
+  } catch (e) {
+    return error(`${name}: ${e.message}`);
+  } finally {
+    board.close();
+  }
+}
+
+export { json };

package/board/worker-prompt.mjs

@@ -0,0 +1,36 @@
+// What a headless worker the board started reads in its system prompt (docs/architecture/orchestrator.md §2.9): the
+// task protocol, in supercode's words, and the skills its card pins, read from the profile's own skill folders. Hermes
+// gives its workers the same two things; this is supercode's version of both.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { skillSources } from '../hermes-home.mjs';
+
+/** The task protocol: how a worker the board started reads and closes its task. */
+export function taskProtocol(taskId) {
+  return [
+    '# Your task comes from the board',
+    `You were started for board task ${taskId} (it is also in HERMES_KANBAN_TASK). The board's tools are yours:`,
+    '- `kanban_show` reads your task: its body, its parents\' handoffs, earlier attempts and its thread. Read it first.',
+    '- `kanban_heartbeat` says you are still working on a long step; `kanban_comment` leaves a note on any task.',
+    '- `kanban_create` files follow-up work (with `parents` to make it wait on another task); `kanban_link` adds a dependency.',
+    '- When the work is done, `kanban_complete` with a `summary` a person can read (and `metadata`, `artifacts`, `created_cards` where they apply).',
+    '- If the work needs review, `kanban_request_review` instead. If you cannot go on, `kanban_block` with a `reason` and its `kind`',
+    '  (needs_input, capability, transient, or dependency when it waits on another task).',
+    'End every run with exactly one of complete, request_review or block: a run that ends without one is counted as a failure.',
+    'You may change only your own task\'s lifecycle; other tasks hear from you through comments.',
+  ].join('\n');
+}
+
+/** The skills a card pins, each as its SKILL.md reads, from the profile's skill folders; '' when none resolve. */
+export function pinnedSkills(profileDir, names = []) {
+  if (!names.length) return '';
+  const sources = skillSources(profileDir);
+  const out = [];
+  for (const name of names) {
+    const dir = sources.get(name);
+    const file = dir && join(dir, 'SKILL.md');
+    if (file && existsSync(file)) out.push(`## Skill: ${name}\n\n${readFileSync(file, 'utf8').trim()}`);
+    else out.push(`## Skill: ${name}\n\n(This profile has no skill named ${name}.)`);
+  }
+  return `# Skills this task pins\n\n${out.join('\n\n')}`;
+}

package/board.mjs

@@ -31,7 +31,7 @@ function dispatchOnce(root) {
 }
 
 /** 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 = () => {}, adapters = {} }) {
+export async function startBoard({ root, config = {}, log = () => {}, adapters = {}, wake = null }) {
   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; }
@@ -52,7 +52,7 @@ export async function startBoard({ root, config = {}, log = () => {}, adapters =
       const { reports, error } = await dispatchOnce(root);
       if (error) { log('warn', `board: tick failed: ${error}`); return; }
       // chat-platform subscriptions are delivered here, through the daemon's own channel adapters
-      try { await notifyChats(root, adapters, log); } catch (error) { log('warn', `board: chat notices failed: ${error.message}`); }
+      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;

package/hermes-cli.mjs

@@ -276,17 +276,12 @@ elif op == "approval":
         elif out["verdict"] == "deny":
             out["message"] = (f"BLOCKED: Command flagged as dangerous ({danger[2]}) but single-query mode (-q) runs without a user present to approve it. "
                 "Find an alternative approach that avoids this command. To allow dangerous commands in single-query mode, set approvals.single_query_mode: approve in config.yaml.")
-elif op == "kanban_prompt":
-    from agent.prompt_builder import KANBAN_GUIDANCE
-    from agent.skill_commands import build_preloaded_skills_prompt
-    skills = build_preloaded_skills_prompt(a.get("skills") or [], task_id=a.get("task"))[0] if a.get("skills") else ""
-    out = {"guidance": KANBAN_GUIDANCE, "skills": skills or ""}
 elif op == "schedule":
     from cron.jobs import parse_schedule
     try: out = parse_schedule(a["text"])
     except ValueError as error: out = {"error": str(error)}
 else:
-    import tools.memory_tool, tools.session_search_tool, tools.skills_tool, tools.kanban_tools
+    import tools.memory_tool, tools.session_search_tool, tools.skills_tool
     from tools.registry import registry
     kw = {}
     if a["name"] == "memory": kw["store"] = memory_store()[0]
@@ -340,14 +335,6 @@ export async function hermesApproval(profileDir, { command = null, context = 'co
   return runHermes(profileDir, { op: 'approval', command, context });
 }
 
-/**
- * What Hermes's agent adds to a dispatched worker's system prompt: `KANBAN_GUIDANCE` (the task protocol)
- * and the task's force-loaded skills (`build_preloaded_skills_prompt`, as `hermes --skills` loads them).
- */
-export function kanbanPrompt(profileDir, { skills = [], task = null, env = {} } = {}) {
-  return runHermes(profileDir, { op: 'kanban_prompt', skills, task }, env);
-}
-
 /** The memory Hermes's agent would carry into a session starting now, as its system prompt carries it; '' for none. */
 export async function memorySnapshot(profileDir) {
   if (!hermesInstall()?.python) return '';

package/kanban-worker.mjs

@@ -12,7 +12,8 @@ import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
 import { load } from './orchestration.mjs';
 import { INSTRUCTION_ARGUMENTS, activationCwd, activationEnv, sandboxArguments, approvalPolicy, limitArguments, materializePersona, materializeSkills, modelArguments, turnCounter, userHomeArguments, userHomePersona } from './activation.mjs';
 import { workerRoute } from './worker-route.mjs';
-import { KANBAN_ENV, untrustedServerVerdict, hermesApproval, hermesInstall, hermesToolEnv, kanbanPrompt, memorySnapshot, mirrorSession } from './hermes-cli.mjs';
+import { KANBAN_ENV, untrustedServerVerdict, hermesApproval, hermesInstall, hermesToolEnv, memorySnapshot, mirrorSession } from './hermes-cli.mjs';
+import { pinnedSkills, taskProtocol } from './board/worker-prompt.mjs';
 import { mountOrchestratorMcp } from './mcp/mount.mjs';
 import { normalizeWorkerEvent, WORKER_STORE } from './loop.mjs';
 import { permissionResponse } from './reducer.mjs';
@@ -65,8 +66,8 @@ export async function runKanbanWorker(argv, env = process.env) {
   const runEnv = { ...hermesToolEnv(profile.dir), ...activationEnv({ root, profile, surfaceKey, vault }), ...route.env, ...task };
   // Hermes's system prompt for a dispatched worker: the home's memory, the task protocol, the task's skills
   const memory = await memorySnapshot(profile.dir).catch(() => '');
-  const board = await kanbanPrompt(profile.dir, { skills: args.skills, task: taskId, env: task });
-  const instructions = [userHomePersona(profile), memory, board.guidance, board.skills].filter(Boolean).join('\n\n');
+  // the task protocol and the pinned skills, supercode's own (board/worker-prompt.mjs)
+  const instructions = [userHomePersona(profile), memory, taskProtocol(taskId), pinnedSkills(profile.dir, args.skills)].filter(Boolean).join('\n\n');
 
   const client = new SupercodeHarnessClient(env.SUPERCODE_BIN ? { command: env.SUPERCODE_BIN } : {});
   try {

package/loop.mjs

@@ -85,7 +85,14 @@ export class Orchestrator {
     // reject unhandled, which Node treats as fatal and which stopped the daemon
     if (this.autoTick) { this.timer = setInterval(() => { this.tick().catch(() => undefined); }, TICK_MS); this.timer.unref?.(); }
     // the home's board, dispatched as a Hermes gateway dispatches it (docs/plans/hermes-compat.md row 14)
-    if (this.autoTick) this.board = await startBoard({ root: this.state.root, config: this.state.profiles.default?.residue?.config ?? {}, log: this.log, adapters: this.adapters });
+    if (this.autoTick) this.board = await startBoard({
+      root: this.state.root, config: this.state.profiles.default?.residue?.config ?? {}, log: this.log, adapters: this.adapters,
+      // a board notice as a turn in the subscribed chat's own session (Hermes's wake), sent as the subscriber
+      wake: (sub, text) => this.dispatchLogged(events.inbound({
+        profile: sub.notifier_profile || 'default', key: { platform: sub.platform, kind: sub.chat_type || 'dm', chat_id: sub.chat_id, ...(sub.thread_id ? { thread_id: sub.thread_id } : {}) },
+        sender: sub.user_id || 'kanban-notifier', sender_name: 'board', text, at: this.clock(),
+      })),
+    });
   }
 
   /**

package/mcp/server.mjs

@@ -20,7 +20,8 @@ import { createInterface } from 'node:readline';
 import { connect } from 'node:net';
 import { join } from 'node:path';
 import { KANBAN_TOOLS, PROTOCOL_VERSION, SERVER_NAME, TOOLS } from './tools.mjs';
-import { KANBAN_ENV, hermesTool } from '../hermes-cli.mjs';
+import { KANBAN_ENV } from '../hermes-cli.mjs';
+import { boardTool } from '../board/tools.mjs';
 
 /** Env var naming the socket, when the loop wants one off the root's default. */
 export const SOCKET_ENV = 'SUPERCODE_ORCHESTRATOR_SOCK';
@@ -51,13 +52,13 @@ const profileDir = (binding) => (binding.profile === 'default' ? binding.root :
 const published = (binding) => (binding.kanban ? [...TOOLS, ...KANBAN_TOOLS] : TOOLS);
 
 /**
- * A board tool, answered by Hermes's own handler in this process: the task, its run and its claim are
- * this worker's environment, as they are a Hermes worker's, never the daemon's.
+ * A board tool, answered by supercode's own board (board/tools.mjs) on the home's board file: the task, its run and
+ * its claim are this worker's environment, as they are a Hermes worker's, never the daemon's.
  */
 async function kanbanCall(binding, name, args) {
   try {
-    const out = await hermesTool(profileDir(binding), name, args, { env: binding.kanban });
-    return { ok: true, result: { ran: name, verbatim: typeof out === 'string' ? out : JSON.stringify(out) } };
+    const out = await boardTool(binding.root, name, args, binding.kanban ?? {});
+    return { ok: true, result: { ran: name, verbatim: out } };
   } catch (error) {
     return { ok: false, error: error.message };
   }

package/package.json

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