@volter/supercode-orchestrator 0.4.147 → 0.4.148

package/board/dispatch.mjs

@@ -15,7 +15,7 @@
 // Every side effect follows a committed transition: a card is claimed before its session is launched, and a
 // subscriber's cursor moves only after its notice was delivered, so two dispatchers over one board never both
 // launch and a crash between the two steps is answered by the next tick.
-import { workflowRevision, retainWorkflowTick } from './ci.mjs';
+import { inspectCompletionEvidence, openReviewPullRequest, withCompletionEvidence, reviewCandidate, workflowRevision, retainWorkflowTick } from './ci.mjs';
 import { createRequire } from 'node:module';
 import { spawn as spawnChild, spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
@@ -24,12 +24,14 @@ import { basename, dirname, join } from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { view, boardPath, claimer, event, json, listBoards, logsDir, now, openBoard, setActor, tx } from './store.mjs';
-import { doors, fire, loadWorkflow, resumeOf, runSpec, runWorkingSeconds, requestSessionClose, retireSupersededRuns, refreshRelationAnswers, transitionsFor, scopeOf, statusOf, templateValue, workflowFor } from './workflow.mjs';
+import { doors, fire, loadWorkflow, resumeOf, runSpec, runWorkingSeconds, requestSessionClose, retireSupersededRuns, refreshCardInputs, refreshRelationAnswers, transitionsFor, scopeOf, statusOf, templateValue, workflowFor } from './workflow.mjs';
 import { checkWorkspace, assertWorkspaceOwner, resolveWorkspace } from './workspace.mjs';
 import { evaluate, holds, render } from './expr.mjs';
+import { identifyNotice } from './notices.mjs';
+import { pendingRequestMail } from './request-mail.mjs';
 import {
   cardContext, claimTtl, currentRun, DEFAULT_FAILURE_LIMIT, extendClaim, getTask, lastSession,
-  recomputeReady, runEffects, setRunSession, subscribeIn, subscriptions,
+  recomputeReady, runEffects, setRunSession, subscribeIn, subscriptions, reconcileDependencySubscriptions,
 } from './engine.mjs';
 
 const WORKER = fileURLToPath(new URL('../bin/hermes-worker.mjs', import.meta.url));
@@ -589,7 +591,7 @@ export function launchRun(board, entry, id, lane, fleet, settings) {
     const reviewer = view(board, (db) => lastSession(db, id, slot));
     if (slot === 'worker' || (worker?.session_id && worker.session_id === reviewer?.session_id)) throw new Error('a reviewer must have a different session from the implementer');
   }
-  const meta = { status, role: spec.role, slot };
+  const meta = { status, role: spec.role, slot, ...(spec.role === 'reviewer' ? { review_candidate: reviewCandidate(board, id) } : {}) };
   try {
     const result = surface === 'pane'
       ? launchPane(board, task, runId, lane, fleet, { input: prompt, slot, meta })
@@ -652,17 +654,26 @@ export function closeRequested(board, report, { taskId = null, caller = null } =
   const panes = new Map();
   for (const row of rows) {
     let session = json(board.db.prepare('SELECT metadata FROM task_runs WHERE id = ?').get(row.id)?.metadata, {})?.supercode;
-    if (session?.launch_key && !session.pane && (row.ended_at || session.close_requested)) {
+    if (!session || session.close_transferred_to || session.close_confirmed_at) continue;
+    if (session.launch_key && (session.launch_pending || !session.pane) && (row.ended_at || session.close_requested)) {
       let receipt = null, receiptError = null;
-      try { receipt = launchReceipt(board, session); } catch (error) { receiptError = error.message; }
-      if (receipt?.pane) { bindLaunch(board, row, session, receipt.pane, session.session_id); session = { ...session, pane: receipt.pane }; }
+      try {
+        receipt = launchReceipt(board, session);
+        if (!receipt) receipt = cancelUnissuedLaunch(board, session);
+      } catch (error) { receiptError = error.message; }
+      if (unissuedLaunch(receipt, session) && retireUnissuedLaunch(board, row, session, receipt)) {
+        (report.closed ??= []).push({ task_id: row.task_id, ...session, receipt });
+        continue;
+      }
+      if (receipt?.pane && receipt.status !== 'issued' && (receipt.status || receipt.live || receipt.exit)) { bindLaunch(board, row, session, receipt.pane, session.session_id); session = { ...session, pane: receipt.pane }; }
       else {
-        const error = `close deferred: ${receiptError ?? `awaiting launch receipt ${session.launch_key}`}`;
+        const error = `close deferred: ${receiptError ?? `awaiting terminal launch receipt ${session.launch_key} (${receipt?.status ?? 'unknown'})`}`;
         tx(board, (db) => {
           setRunSession(db, row.id, { close_error: error, close_requested: session.close_requested ?? now() });
           if (session.close_error !== error) event(db, row.task_id, 'session_close_failed', { error, retry: true }, row.id);
         });
         report.undelivered.push([row.task_id, addressOf(session), error]);
+        continue;
       }
     }
     if ((!session?.pane && session?.surface !== 'native') || session.close_transferred_to || session.close_confirmed_at || (!row.ended_at && !session.close_requested)) continue;
@@ -790,7 +801,10 @@ export async function sessionNotice(board, e) {
   const prior = view(board, (db) => json(db.prepare('SELECT metadata FROM task_runs WHERE id=?').get(e.runId)?.metadata, {})?.supercode);
   if (prior?.close_confirmed_at) {
     tx(board, (db) => {
-      event(db, e.id, 'session_notice_failed', { address: e.address, verb: e.verb, notice: e.durableId, error: 'session closure already confirmed; notice cannot be delivered', retry: false }, e.runId);
+      const unissued = unissuedLaunch(prior.launch_cancellation, prior);
+      event(db, e.id, unissued ? 'session_notice_not_required' : 'session_notice_failed', { address: e.address, verb: e.verb, notice: e.durableId,
+        error: unissued ? 'machine confirmed launch was not issued; no session exists to notify' : 'session closure already confirmed; notice cannot be delivered', retry: false,
+        ...(unissued ? { receipt: prior.launch_cancellation } : {}) }, e.runId);
       if (prior.lifecycle_notice_pending === e.durableId) setRunSession(db, e.runId, { lifecycle_notice_pending: null });
     });
     return true;
@@ -928,6 +942,45 @@ function launchReceipt(board, session) {
   return receipt;
 }
 
+function cancelUnissuedLaunch(board, session) {
+  const result = sc(['teams', 'launches', 'cancel', session.launch_key, ...onMachine(session.machine)],
+    { timeout: 30_000, as: boardAddress(board.label) });
+  if (result.code !== 0) throw unavailable(`launch cancellation unavailable on ${session.machine}; retain ${session.launch_key}: ${(result.stderr || result.stdout).trim().slice(-300)}`);
+  const receipt = lastJson(result.stdout);
+  if (!receipt || receipt.key !== session.launch_key) throw unavailable(`invalid cancellation receipt for ${session.launch_key}`);
+  return receipt;
+}
+
+function unissuedLaunch(receipt, session) {
+  return receipt?.key === session?.launch_key && receipt?.status === 'cancelled' && receipt?.cancelled === true &&
+    receipt?.outcome === 'not_issued' && receipt?.live === false && receipt?.pane === null;
+}
+
+function retireUnissuedLaunch(board, row, session, receipt, { entry = null, effects = [] } = {}) {
+  if (!unissuedLaunch(receipt, session)) return false;
+  const result = tx(board, db => {
+    const current = db.prepare('SELECT ended_at, metadata FROM task_runs WHERE id=?').get(row.id);
+    const saved = json(current?.metadata, {})?.supercode;
+    if (!saved || saved.launch_key !== session.launch_key || saved.pane || saved.address || saved.pid) return { retired: false, effects: [] };
+    if (!current.ended_at && (!entry || getTask(db, row.task_id)?.current_run_id !== row.id)) return { retired: false, effects: [] };
+    if (saved.close_confirmed_at) return { retired: true, effects: [] };
+    const collected = [];
+    const at = now();
+    setRunSession(db, row.id, { launch_pending: false, launch_cancellation: receipt, launch_error: 'machine confirmed launch was not issued',
+      close_requested: saved.close_requested ?? at, closed_at: at, close_confirmed_at: at, close_error: null,
+      forgotten: saved.mode === 'fresh' ? true : Boolean(saved.forgotten) });
+    event(db, row.task_id, 'session_launch_cancelled', { key: session.launch_key, machine: session.machine, receipt }, row.id);
+    if (!current.ended_at) {
+      const moved = fire(db, board, entry, row.task_id, 'spawn_failed', { roles: ['platform'], payload: { error: `launch ${session.launch_key} was not issued; its machine retired the key` } });
+      collected.push(...moved.effects);
+    }
+    event(db, row.task_id, 'session_closed', { key: session.launch_key, machine: session.machine, reason: 'launch not issued', receipt }, row.id);
+    return { retired: true, effects: collected };
+  });
+  effects.push(...result.effects);
+  return result.retired;
+}
+
 function bindLaunch(board, row, session, pane, sid) {
   return tx(board, (db) => {
     const current = db.prepare('SELECT ended_at, metadata FROM task_runs WHERE id=?').get(row.id);
@@ -989,13 +1042,22 @@ function reconcileLaunches(board, fleet, report, entry, effects, settings, lanes
       report.failed.push([id,error.message]);
     }
   }
-  const rows = view(board, (db) => db.prepare(`SELECT id, task_id, ended_at, metadata FROM task_runs
+  const rows = view(board, (db) => db.prepare(`SELECT id, task_id, started_at, ended_at, metadata FROM task_runs
     WHERE json_extract(metadata, '$.supercode.launch_pending') = 1
     AND json_extract(metadata, '$.supercode.close_confirmed_at') IS NULL`).all());
   for (const row of rows) {
     const s = json(row.metadata, {})?.supercode;
     try {
-      const receipt = launchReceipt(board, s);
+      let receipt = launchReceipt(board, s);
+      if (!receipt && (row.ended_at || now() - Number(s.launched_at ?? row.started_at) >= settings.launchWindow)) receipt = cancelUnissuedLaunch(board, s);
+      if (unissuedLaunch(receipt, s)) {
+        if (!retireUnissuedLaunch(board, row, s, receipt, { entry, effects })) report.failed.push([row.task_id, 'negative launch receipt conflicts with a bound session; retaining ownership']);
+        continue;
+      }
+      if (receipt?.status === 'issued' || (receipt?.live === false && !receipt.status && !receipt.exit)) {
+        report.queued.push([row.task_id, `launch ${s.launch_key} is issued or uncertain; retaining ownership`]);
+        continue;
+      }
       if (!receipt?.pane) { report.queued.push([row.task_id, s.launch_error ?? `awaiting launch receipt ${s.launch_key}`]); continue; }
       const sid = s.session_id ?? fleet.sessions?.find((f) => f.pane === receipt.pane && String(f.address).startsWith(`sc:${s.machine}:${s.harness}:`))?.address.split(':')[3];
       bindLaunch(board, row, s, receipt.pane, receipt.live ? sid : null);
@@ -1350,23 +1412,31 @@ async function send(from, label, to, body, key, { queue = false, ask = false, su
  * (the id is the send's idempotency key). One that fails is tried again next tick.
  */
 export async function sendBoardMessages(board, report, taskId = null) {
-  const rows = view(board, (db) => db.prepare(`SELECT id, task_id, payload FROM task_events e WHERE kind = 'board_message' AND NOT EXISTS
-    (SELECT 1 FROM task_events s WHERE s.kind = 'board_message_sent' AND s.task_id = e.task_id AND json_extract(s.payload, '$.event') = e.id) ORDER BY id`).all());
-  for (const row of rows) {
-    if (taskId && row.task_id !== taskId) continue;
-    const m = json(row.payload, {}) ?? {};
+  const pending = view(board, db => db.prepare(`SELECT 1 FROM task_events original WHERE kind='board_message'
+    AND NOT EXISTS (SELECT 1 FROM task_events sent WHERE sent.kind='board_message_sent'
+      AND sent.task_id=original.task_id AND json_extract(sent.payload,'$.event')=original.id) LIMIT 1`).get());
+  if (!pending) return;
+  const planned = tx(board, db => pendingRequestMail(db, taskId));
+  if (Number.isFinite(planned.nextAt)) report.next_mail_at = Math.min(report.next_mail_at ?? Infinity, planned.nextAt);
+  for (const mail of planned.ready) {
+    const first = mail.members[0];
     try {
-      const task = view(board, db => getTask(db, row.task_id));
-      const receipt = await send(boardAddress(board.label), board.label, m.to, m.text, m.message_id ?? `board-message-${row.id}`, { ask: Boolean(m.message_id), subject: `${task?.title || row.task_id} · ${m.message_id ? 'Question' : 'Update'}` });
+      const task = view(board, db => getTask(db, first.task_id));
+      const subject = mail.requester ? `State requests · ${mail.members.length} request(s) · ${task?.title || first.task_id}` : `${task?.title || first.task_id} · ${mail.message_id ? 'Question' : 'Update'}`;
+      const receipt = await send(boardAddress(board.label), board.label, mail.to, mail.text, mail.message_id ?? `board-message-${first.id}`, { ask: Boolean(mail.message_id), subject });
       if (!receipt.delivered) throw new Error(receipt.reason ?? 'queued; native transcript confirmation pending');
-      tx(board, (db) => event(db, row.task_id, 'board_message_sent', { event: row.id, to: m.to, receipt, ...(m.message_id ? { message_id: m.message_id } : {}) }));
+      tx(board, db => {
+        for (const member of mail.members) event(db, member.task_id, 'board_message_sent', { event: member.id, to: mail.to, receipt, ...(mail.message_id ? { message_id: mail.message_id, request_id: member.message_id ?? mail.message_id } : {}) });
+      });
     } catch (error) {
       const reason = String(error.message).slice(-200);
-      report.undelivered.push([row.task_id, m.to, reason]);
+      for (const member of mail.members) report.undelivered.push([member.task_id, mail.to, reason]);
       tx(board, db => {
-        const previous = db.prepare("SELECT payload,created_at FROM task_events WHERE task_id=? AND kind='board_message_failed' AND json_extract(payload,'$.event')=? ORDER BY id DESC LIMIT 1").get(row.task_id, row.id);
-        if (json(previous?.payload, {})?.reason !== reason || now() - (previous?.created_at ?? 0) >= 60)
-          event(db, row.task_id, 'board_message_failed', { event: row.id, to: m.to, message_id: m.message_id, reason });
+        for (const member of mail.members) {
+          const previous = db.prepare("SELECT payload,created_at FROM task_events WHERE task_id=? AND kind='board_message_failed' AND json_extract(payload,'$.event')=? ORDER BY id DESC LIMIT 1").get(member.task_id, member.id);
+          if (json(previous?.payload, {})?.reason !== reason || now() - (previous?.created_at ?? 0) >= 60)
+            event(db, member.task_id, 'board_message_failed', { event: member.id, to: mail.to, message_id: mail.message_id, reason });
+        }
       });
     }
   }
@@ -1399,6 +1469,7 @@ function ensureSubscriptions(board, entry) {
   const managers = Array.isArray(entry.params.managers) ? entry.params.managers.map(String) : [];
   const toManagers = Object.keys(entry.workflow.notify?.manager ?? {}).length > 0;
   tx(board, (db) => {
+    reconcileDependencySubscriptions(db);
     for (const t of db.prepare("SELECT id, current_run_id FROM tasks WHERE status NOT IN ('done', 'archived')").all()) {
       if (toManagers) for (const m of managers) subscribeIn(db, t.id, m, 'manager');
       if (!t.current_run_id) continue;
@@ -1418,6 +1489,7 @@ async function notify(board, fleet, report, entry) {
   const from = boardAddress(board.label);
   // each subscription's notices go in order; different subscribers are told side by side
   await pool(subscriptions(board.db).filter((sub) => sub.platform === 'supercode'), SEND_CONCURRENCY, async (sub) => {
+    if (sub.delivery_metadata?.dependent_card && sub.delivery_metadata.waiting_recipient) return;
     const role = ['worker', 'dependency', 'manager'].includes(sub.delivery_metadata?.role) ? sub.delivery_metadata.role : 'creator';
     // a session the fleet does not list this tick is told next tick: one reading is not a loss (a loaded box drops
     // sessions from a read, and a dropped subscription never came back), and a session that is replaced on its card
@@ -1425,7 +1497,7 @@ async function notify(board, fleet, report, entry) {
     if (role !== 'creator' && fleet.ok && !fleet.alive.has(sub.chat_id)) return;
     const kinds = heardBy(entry, role);
     if (!kinds.length) return;
-    const events = board.db.prepare(`SELECT id, kind, payload, created_at FROM task_events WHERE task_id = ? AND id > ? AND kind IN (${kinds.map(() => '?').join(', ')}) ORDER BY id`)
+    const events = board.db.prepare(`SELECT id, kind, payload, created_at, run_id FROM task_events WHERE task_id = ? AND id > ? AND kind IN (${kinds.map(() => '?').join(', ')}) ORDER BY id`)
       .all(sub.task_id, sub.last_event_id, ...kinds);
     if (!events.length) return;
     // the card as the workflow names it (its status the workflow's: triaging, reviewing, stopped; `stored_as` kanban.db's)
@@ -1444,7 +1516,8 @@ async function notify(board, fleet, report, entry) {
           text = c ? noticeOf(entry, role, ev.kind, task, p, c) : null;
         } else text = noticeOf(entry, role, ev.kind, task, p);
         if (text) {
-          const receipt = await send(from, board.label, sub.chat_id, text, `board-${sub.task_id}-${ev.id}-${sub.chat_id.slice(-12)}`, { queue: !entry.workflow.run && sub.delivery_mode === 'notify', subject: `${task?.title || sub.task_id} · ${ev.kind.replaceAll('_', ' ')}` });
+          const body = ['worker', 'dependency'].includes(role) ? identifyNotice(ev, text) : text;
+          const receipt = await send(from, board.label, sub.chat_id, body, `board-${sub.task_id}-${ev.id}-${sub.chat_id.slice(-12)}`, { queue: !entry.workflow.run && sub.delivery_mode === 'notify', subject: `${ev.kind.replaceAll('_', ' ')} · run ${ev.run_id ?? 'none'} · event ${ev.id} · ${task?.title || sub.task_id}` });
           if (!receipt.delivered) { pending = Boolean(receipt.queued); throw new Error(receipt.reason ?? 'native delivery confirmation pending'); }
           tx(board, (db) => event(db, sub.task_id, 'notice_delivered', { source_event: ev.id, kind: ev.kind, address: sub.chat_id, receipt }));
           report.notified.push([sub.task_id, ev.kind, sub.chat_id]);
@@ -1463,12 +1536,13 @@ async function notify(board, fleet, report, entry) {
     }
     // the cursor moves past what was delivered (a failed delivery is retried next tick; the mail id dedupes)
     tx(board, (db) => {
-      const where = "WHERE task_id = ? AND platform = 'supercode' AND chat_id = ?";
-      db.prepare(`UPDATE kanban_notify_subs SET last_event_id = ? ${where} AND last_event_id < ?`).run(cursor, sub.task_id, sub.chat_id, cursor);
+      const where = "WHERE task_id = ? AND platform = 'supercode' AND chat_id = ? AND thread_id = ?";
+      const identity = [sub.task_id, sub.chat_id, sub.thread_id ?? ''];
+      db.prepare(`UPDATE kanban_notify_subs SET last_event_id = ? ${where} AND last_event_id < ?`).run(cursor, ...identity, cursor);
       const failures = failed && !pending ? Number(sub.delivery_metadata?.failures ?? 0) + 1 : 0;
-      if (failures >= MAX_SEND_FAILURES) { db.prepare(`DELETE FROM kanban_notify_subs ${where}`).run(sub.task_id, sub.chat_id); return; }
-      if (failures !== Number(sub.delivery_metadata?.failures ?? 0)) db.prepare(`UPDATE kanban_notify_subs SET delivery_metadata = ? ${where}`).run(JSON.stringify({ ...sub.delivery_metadata, failures }), sub.task_id, sub.chat_id);
-      if (task?.status === 'archived' && cursor >= events.at(-1).id) db.prepare(`DELETE FROM kanban_notify_subs ${where}`).run(sub.task_id, sub.chat_id);
+      if (failures >= MAX_SEND_FAILURES) { db.prepare(`DELETE FROM kanban_notify_subs ${where}`).run(...identity); return; }
+      if (failures !== Number(sub.delivery_metadata?.failures ?? 0)) db.prepare(`UPDATE kanban_notify_subs SET delivery_metadata = ? ${where}`).run(JSON.stringify({ ...sub.delivery_metadata, failures }), ...identity);
+      if (task?.status === 'archived' && cursor >= events.at(-1).id) db.prepare(`DELETE FROM kanban_notify_subs ${where}`).run(...identity);
     });
   });
 }
@@ -1703,6 +1777,42 @@ export async function plan({ root, lanes, settings, slugs = null, params = {} })
   return out;
 }
 
+/** An opened PR asks for the declared review transition once the arc's tasks are closed. */
+async function activatePullRequestReviews(board, entry, report, effects, { only = null } = {}) {
+  const candidates = view(board, db => db.prepare(`SELECT t.id FROM tasks t JOIN supercode_cards c ON c.task_id=t.id
+    WHERE c.subtask_of IS NULL AND COALESCE(c.review_only,0)=0 AND c.every IS NULL
+    AND t.workspace_kind!='scratch' ${only ? 'AND t.id=?' : ''}`).all(...(only ? [only] : [])));
+  for (const { id } of candidates) {
+    const eligible = db => {
+      const task = getTask(db, id);
+      if (!task) return false;
+      const scope = scopeOf(db, board, task, { params: entry.params });
+      return task && transitionsFor(entry.workflow, statusOf(db, task), 'request_review').some(t => !t.by || t.by.includes('platform')) &&
+        !scope.card.dispatch_hold && !scope.card.paused && !scope.card.blocked_by.length &&
+        scope.card.subtasks.every(t => ['done', 'cancelled'].includes(t.status));
+    };
+    if (!view(board, eligible)) continue;
+    try {
+      const payload = openReviewPullRequest(board, id);
+      if (!payload) continue;
+      const evidence = inspectCompletionEvidence(board, id, entry, payload, 'request_review');
+      if (!evidence.ready) throw new Error(evidence.reason);
+      refreshCardInputs(board, id, { commits: true });
+      const moved = tx(board, db => {
+        const task = getTask(db, id);
+        if (!eligible(db)) return null;
+        return withCompletionEvidence(board, id, evidence, () => fire(db, board, entry, id, 'request_review', {
+          roles: ['platform'], payload: { ...payload, run_id: task.current_run_id, summary: `Opened PR ${payload.pr} at ${payload.pr_head}`, ci: evidence }
+        }));
+      });
+      if (moved) {
+        effects.push(...moved.effects);
+        (report.review_requested ??= []).push({ id, pr: payload.pr, head: payload.pr_head });
+      }
+    } catch (error) { report.queued.push([id, `PR review waits: ${error.message}`]); }
+  }
+}
+
 /**
  * One tick over every board of the home at `root`. `lanes` from `lanesOf`, `settings` from `boardSettings`.
  * `only` limits starting to one card (a create that answers whether its card started). Each board is ticked under its
@@ -1750,6 +1860,7 @@ export async function tick({ root, lanes, settings, only = null, slugs = null, d
       reconcileLaunches(board, fleet, report, entry, effects, settings, lanes); supervise(board, fleet, settings, report, entry, effects); await runEffects(board, effects.splice(0), { retryNotices: true }); closeRequested(board, report); phase('supervise');
       report.unsettled = [];
       report.promoted = recomputeReady(board, effects, report.unsettled);
+      if (dispatch) await activatePullRequestReviews(board, entry, report, effects, { only });
       await sendBoardMessages(board, report);
       const before = report.started.length;
       if (dispatch) startCards(board, fleet, lanes, settings, report, entry, effects, { only, hostRunning });

package/board/engine.mjs

@@ -13,7 +13,7 @@ import { join, resolve } from 'node:path';
 import { checkWorkspace, assertWorkspaceOwner, declareWorkspace, isLocalWorkspace } from './workspace.mjs';
 import { DatabaseSync } from 'node:sqlite';
 import { view, actorOf, claimer, event, json, newTaskId, now, tx } from './store.mjs';
-import { observeCompletionEvidence } from './ci.mjs';
+import { completionPhase, inspectCompletionEvidence, observeCompletionEvidence, withCompletionEvidence } from './ci.mjs';
 import { addDependency, retireSupersededRuns, refreshCardInputs, requestSessionClose, eventTo, fire, loadWorkflow, setStatus, settle, startNew, statusOf, runEvent, workflowFor } from './workflow.mjs';
 
 export const STATUSES = ['triage', 'todo', 'scheduled', 'ready', 'running', 'blocked', 'review', 'done', 'archived'];
@@ -343,11 +343,15 @@ export function setCaller(fn) { callerRoles = fn; }
 
 export async function act(board, id, name, { roles = null, payload = {}, extra = {} } = {}) {
   const entry = await loadWorkflow(board.root);
+  if (name === 'comment' && (!String(payload.body ?? '').trim() || !String(payload.author ?? '').trim())) throw new Error('a comment has an author and body');
   refreshCardInputs(board, id, { commits: ['complete', 'request_review'].includes(name) });
-  if (['complete', 'request_review', 'request_state'].includes(name)) payload = { ...payload, ci: observeCompletionEvidence(board, id, entry, payload) };
+  if (['complete', 'request_review', 'request_state'].includes(name)) payload = { ...payload, ci: observeCompletionEvidence(board, id, entry, payload, completionPhase(board, id, entry, name, payload, roles ?? callerRoles(board.db, id))) };
+  if (payload.ci?.required && !payload.ci.ready) throw new Error(payload.ci.reason ?? 'The PR candidate could not be verified.');
   const result = tx(board, (db) => {
     roles ??= callerRoles(db, id);
     const r = fire(db, board, entry, id, name, { roles, payload, extra });
+    // Authorization and the comment row share one transaction: a refusal stores nothing.
+    if (name === 'comment') r.commentId = Number(run(db, 'INSERT INTO task_comments (task_id, author, body, created_at) VALUES (?, ?, ?, ?)', id, payload.author.trim(), payload.body.trim(), now()).lastInsertRowid);
     // the cards that wait on it, and its subtasks, see it change
     const related = all(db, 'SELECT task_id, blocked_by FROM supercode_cards').filter((c) => json(c.blocked_by, []).some((b) => b.id === id)).map((c) => c.task_id);
     const around = [...related, ...childrenOf(db, id), ...all(db, 'SELECT task_id AS id FROM supercode_cards WHERE subtask_of = ?', id).map((x) => x.id)];
@@ -355,7 +359,29 @@ export async function act(board, id, name, { roles = null, payload = {}, extra =
     return r;
   });
   await runEffects(board, result.effects);
-  return { from: result.from, to: result.to, moved: result.moved };
+  return { from: result.from, to: result.to, moved: result.moved, ...(result.commentId ? { commentId: result.commentId } : {}) };
+}
+
+export async function requestStateMany(board, ids, payload = {}) {
+  const targets = [...new Set(ids.map(String))];
+  if (!targets.length) throw new Error('A state request names at least one card.');
+  const entry = await loadWorkflow(board.root);
+  const prepared = new Map(targets.map(id => {
+    const roles = callerRoles(board.db, id);
+    return [id, inspectCompletionEvidence(board, id, entry, payload, completionPhase(board, id, entry, 'request_state', payload, roles))];
+  }));
+  for (const evidence of prepared.values()) if (evidence.required && !evidence.ready) throw new Error(evidence.reason ?? 'The reviewed PR head could not be verified.');
+  const result = tx(board, db => {
+    const effects = [];
+    const results = targets.map(id => withCompletionEvidence(board, id, prepared.get(id), () => {
+      const move = fire(db, board, entry, id, 'request_state', { roles: callerRoles(db, id), payload: { ...payload, ci: prepared.get(id) } });
+      effects.push(...move.effects);
+      return [id, move.to];
+    }));
+    return { results, effects };
+  });
+  await runEffects(board, result.effects);
+  return result.results;
 }
 
 /** Take card `id` to `status` by the event the workflow says goes there for this caller (`goto`). */
@@ -377,7 +403,7 @@ export async function goto(board, id, status, { roles = null, payload = {} } = {
 export async function runEffects(board, effects = [], { retryNotices = false } = {}) {
   const requested = new Set(effects.map((e) => e.durableId).filter(Boolean));
   const pending = board.db.prepare('SELECT id, effect FROM supercode_effects ORDER BY id').all()
-    .filter((p) => retryNotices || requested.has(p.id) || json(p.effect, {})?.kind !== 'session_notice');
+    .filter((p) => retryNotices || requested.has(p.id));
   const durable = new Set(pending.map((p) => p.id));
   const combined = [...pending.map((p) => ({ ...json(p.effect, {}), durableId: p.id })), ...effects.filter((e) => !e.durableId || !durable.has(e.durableId))];
   combined.sort((a,b) => Number(b.kind === 'session_notice') - Number(a.kind === 'session_notice'));
@@ -453,14 +479,14 @@ function invalidateDescendants(db, board, id) {
 
 // each of Hermes's verbs is an event of the workflow; the words it takes are the event's payload
 
-export const complete = (board, id, { result = null, summary = null, metadata = null, roles, runId = null, commit = null, ci_run = null } = {}) =>
-  act(board, id, 'complete', { roles, payload: { result, summary, metadata, run_id: runId, commit, ci_run } });
+export const complete = (board, id, { result = null, summary = null, metadata = null, roles, runId = null, commit = null, ci_run = null, branch = null, pr = null, pr_head = null, reviewed_sha = null } = {}) =>
+  act(board, id, 'complete', { roles, payload: { result, summary, metadata, run_id: runId, commit, ci_run, branch, pr, pr_head, reviewed_sha } });
 // a block names the one thing that ends it: a card it waits on (`on`), or the message whose answer it waits for (`waiting_on`)
 export const block = (board, id, { reason = null, on = null, waitingOn = null, roles, runId = null } = {}) =>
   act(board, id, 'block', { roles, payload: { reason, on, waiting_on: waitingOn, run_id: runId } });
 export const unblock = (board, id, { reason = null, on = null, roles } = {}) => act(board, id, 'unblock', { roles, payload: { reason, on } });
-export const requestReview = (board, id, { summary = null, metadata = null, reviewer = null, force = false, expectedRunId = null, roles, commit = null, ci_run = null } = {}) =>
-  act(board, id, 'request_review', { roles, payload: { summary, metadata, reviewer, force, run_id: expectedRunId, commit, ci_run } });
+export const requestReview = (board, id, { summary = null, metadata = null, reviewer = null, force = false, expectedRunId = null, roles, commit = null, ci_run = null, branch = null, pr = null, pr_head = null } = {}) =>
+  act(board, id, 'request_review', { roles, payload: { summary, metadata, reviewer, force, run_id: expectedRunId, commit, ci_run, branch, pr, pr_head } });
 export const requestChanges = (board, id, { reason = null, reviewer = null, roles } = {}) => act(board, id, 'request_changes', { roles, payload: { reason, reviewer } });
 export const reopen = (board, id, { author = 'user', reason = null, roles } = {}) => act(board, id, 'reopen', { roles, payload: { author, reason } });
 export const reopenReview = (board, id, { roles } = {}) => act(board, id, 'reopen_review', { roles });
@@ -470,11 +496,16 @@ export const reclaim = (board, id, reason = null, { roles } = {}) => act(board,
 export const archive = (board, id, { roles } = {}) => act(board, id, 'archive', { roles });
 export function specify(board, id, { title = null, body = null, workspace = null, branch = null, reviewOnly = null, author = 'user', roles } = {}) {
   let declaration = null;
-  if (workspace != null) {
-    const task = getTask(board.db, id), ws = parseWorkspace(workspace);
+  if (workspace != null || branch != null) {
+    const task = getTask(board.db, id);
+    const word = workspace ?? `${task.workspace_kind}${task.workspace_anchor || task.workspace_path ? `:${task.workspace_anchor ?? task.workspace_path}` : ''}`;
+    const ws = parseWorkspace(word);
     if (task.current_run_id) throw new Error('end the current run before changing its workspace');
+    if (branch != null && ws.kind === 'scratch') throw new Error('a scratch workspace has no repository branch');
     declaration = { kind: ws.kind, ...declareWorkspace(ws.kind, ws.path, task.machine, branch) };
+    if (declaration.repository === task.workspace_anchor) declaration.branch ??= task.branch_name;
     if (declaration.kind === 'worktree') declaration.branch ??= `wt/${id}`;
+    if (declaration.kind === 'dir') declaration.path = checkWorkspace(board, { ...task, workspace_kind: declaration.kind, workspace_anchor: declaration.repository, workspace_path: declaration.path, branch_name: declaration.branch }).path;
   }
   if (reviewOnly != null && (typeof reviewOnly !== 'boolean' || !Array.isArray(workflowFor(board.root).params.review_only_by))) throw new Error('This workflow must declare review_only_by before a boolean review-only declaration is changed.');
   return act(board, id, 'specify', { roles, payload: { title, body, author, ...(reviewOnly != null ? { review_only: reviewOnly } : {}), ...(declaration ? { workspace: declaration } : {}) } });
@@ -522,12 +553,8 @@ export async function unlink(board, parent, child, { roles } = {}) {
 export async function comment(board, id, author, body, { roles } = {}) {
   if (!String(body ?? '').trim()) throw new Error('a comment has a body');
   if (!String(author ?? '').trim()) throw new Error('a comment has an author');
-  const commentId = tx(board, (db) => {
-    must(db, id);
-    return Number(run(db, 'INSERT INTO task_comments (task_id, author, body, created_at) VALUES (?, ?, ?, ?)', id, author.trim(), body.trim(), now()).lastInsertRowid);
-  });
-  await act(board, id, 'comment', { roles, payload: { author: author.trim(), body } });
-  return commentId;
+  const result = await act(board, id, 'comment', { roles, payload: { author: author.trim(), body } });
+  return result.commentId;
 }
 
 // ------------------------------------------------------------------ subscriptions
@@ -550,6 +577,47 @@ export function unsubscribe(board, id, address) {
   return tx(board, (db) => run(db, "DELETE FROM kanban_notify_subs WHERE task_id = ? AND platform = 'supercode' AND chat_id = ?", id, address).changes > 0);
 }
 
+function dependencyRecipient(db, id) {
+  const owner = must(db, id);
+  if (owner.archived || ['done', 'cancelled', 'archived'].includes(owner.status)) return null;
+  const session = currentRun(db, id)?.metadata?.supercode ?? lastSession(db, id);
+  return session?.forgotten || session?.close_confirmed_at ? null : session?.address ?? null;
+}
+
+export function subscribeDependency(board, ownerId, sourceId, { remove = false } = {}) {
+  return tx(board, db => {
+    const roles = callerRoles(db, ownerId);
+    if (!roles.some(role => ['implementer', 'reviewer', 'auditor', 'manager', 'owner'].includes(role))) throw new Error('A dependency subscription belongs to your working arc; use --for-card <your-card>.');
+    const owner = must(db, ownerId);
+    if (owner.subtask_of) throw new Error('The dependency subscription names its arc, not a subtask.');
+    must(db, sourceId);
+    const thread = `arc:${ownerId}`;
+    if (remove) return { removed: run(db, "DELETE FROM kanban_notify_subs WHERE task_id=? AND platform='supercode' AND thread_id=? AND json_extract(delivery_metadata,'$.dependent_card')=?", sourceId, thread, ownerId).changes > 0 };
+    const address = dependencyRecipient(db, ownerId);
+    if (!address) throw new Error('The subscribing arc has no current reachable session identity.');
+    const existing = one(db, "SELECT * FROM kanban_notify_subs WHERE task_id=? AND platform='supercode' AND thread_id=? AND json_extract(delivery_metadata,'$.dependent_card')=?", sourceId, thread, ownerId);
+    const cursor = existing?.last_event_id ?? one(db, 'SELECT COALESCE(MAX(id),0) AS cursor FROM task_events WHERE task_id=?', sourceId).cursor;
+    run(db, "DELETE FROM kanban_notify_subs WHERE task_id=? AND platform='supercode' AND thread_id=? AND json_extract(delivery_metadata,'$.dependent_card')=?", sourceId, thread, ownerId);
+    run(db, "INSERT 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+wake',?,?,?)",
+      sourceId, address, thread, JSON.stringify({ role: 'dependency', dependent_card: ownerId }), now(), cursor);
+    event(db, ownerId, 'dependency_subscribed', { source: sourceId, address });
+    return { address, source: sourceId, owner: ownerId };
+  });
+}
+
+export function reconcileDependencySubscriptions(db) {
+  for (const row of all(db, "SELECT * FROM kanban_notify_subs WHERE platform='supercode' AND json_extract(delivery_metadata,'$.dependent_card') IS NOT NULL")) {
+    const metadata = json(row.delivery_metadata, {});
+    const owner = getTask(db, metadata.dependent_card);
+    const address = owner ? dependencyRecipient(db, owner.id) : null;
+    const where = "WHERE task_id=? AND platform='supercode' AND chat_id=? AND thread_id=?";
+    const identity = [row.task_id, row.chat_id, row.thread_id];
+    if (!owner || owner.archived || ['done', 'cancelled', 'archived'].includes(owner.status)) run(db, `DELETE FROM kanban_notify_subs ${where}`, ...identity);
+    else if (address && (address !== row.chat_id || metadata.waiting_recipient)) run(db, `UPDATE kanban_notify_subs SET chat_id=?,delivery_metadata=? ${where}`, address, JSON.stringify({ ...metadata, waiting_recipient: false, failures: 0 }), ...identity);
+    else if (!address && !metadata.waiting_recipient) run(db, `UPDATE kanban_notify_subs SET delivery_metadata=? ${where}`, JSON.stringify({ ...metadata, waiting_recipient: true }), ...identity);
+  }
+}
+
 /** A child hears what its parents' subscribers hear (Hermes copies them at link time); a subtask its arc's session too. */
 function inheritSubscriptions(db, child, parents, { workers = false } = {}) {
   const cursor = one(db, 'SELECT COALESCE(MAX(id), 0) AS c FROM task_events WHERE task_id = ?', child).c;

package/board/notices.mjs

@@ -0,0 +1,5 @@
+export function identifyNotice(event, text) {
+  const time = new Date(Number(event.created_at) * 1000).toISOString();
+  const kind = String(event.kind).replaceAll('_', ' ');
+  return `New board update: ${kind}; run ${event.run_id ?? 'none'}; event ${event.id}; ${time}.\n${text}`;
+}

package/board/request-mail.mjs

@@ -0,0 +1,59 @@
+import { event, json, now } from './store.mjs';
+
+export function pendingRequestMail(db, taskId = null) {
+  const pending = db.prepare(`SELECT id, task_id, payload, created_at FROM task_events original
+    WHERE kind='board_message' AND NOT EXISTS (SELECT 1 FROM task_events sent WHERE sent.kind='board_message_sent'
+      AND sent.task_id=original.task_id AND json_extract(sent.payload,'$.event')=original.id) ORDER BY id`).all()
+    .map(row => ({ ...row, mail: json(row.payload, {}) ?? {} }));
+  if (!pending.length) return { ready: [], nextAt: Infinity };
+  const batches = db.prepare("SELECT payload FROM task_events WHERE kind='board_message_batch' AND id>=? ORDER BY id").all(pending[0].id)
+    .map(row => json(row.payload, {}));
+  const assigned = new Set();
+  const ready = [];
+  let nextAt = Infinity;
+  for (const envelope of batches) {
+    const remaining = pending.filter(row => envelope.members?.some(member => member.id === row.id));
+    if (!remaining.length) continue;
+    for (const row of remaining) assigned.add(row.id);
+    if (!taskId || envelope.members.some(member => member.task_id === taskId)) ready.push(envelope);
+  }
+  const groups = new Map();
+  for (const row of pending) {
+    if (assigned.has(row.id)) continue;
+    if (!row.mail.batch) {
+      if (!taskId || row.task_id === taskId) ready.push({ ...row.mail, members: [{ id: row.id, task_id: row.task_id }] });
+      continue;
+    }
+    const key = JSON.stringify([row.mail.to, row.mail.batch.requester]);
+    const groupsForRequester = groups.get(key) ?? [];
+    let group = groupsForRequester.at(-1);
+    if (!group || row.created_at > group[0].created_at + 60) {
+      group = [];
+      groupsForRequester.push(group);
+      groups.set(key, groupsForRequester);
+    }
+    group.push(row);
+  }
+  for (const groupsForRequester of groups.values()) for (const group of groupsForRequester) {
+    if (taskId && !group.some(row => row.task_id === taskId)) continue;
+    const first = group[0];
+    const last = group.at(-1);
+    const due = Math.min(first.created_at + 60, last.created_at + last.mail.batch.window_seconds);
+    if (now() < due) {
+      nextAt = Math.min(nextAt, due * 1000);
+      continue;
+    }
+    const envelope = {
+      to: first.mail.to,
+      message_id: first.mail.message_id,
+      requester: first.mail.batch.requester,
+      members: group.map(row => ({ id: row.id, task_id: row.task_id, message_id: row.mail.message_id })),
+      text: `State requests from ${first.mail.batch.requester}: ${group.length} request(s) for ${new Set(group.map(row => row.task_id)).size} card(s).\n\n` +
+        group.map(row => `${row.task_id} [${row.mail.message_id}]\n${row.mail.text}`).join('\n\n---\n\n') +
+        `\n\nAnswer with reply_to ${first.mail.message_id}.`,
+    };
+    event(db, first.task_id, 'board_message_batch', envelope);
+    ready.push(envelope);
+  }
+  return { ready, nextAt };
+}

package/board/tools.mjs

@@ -34,7 +34,8 @@ export async function boardTool(root, name, args = {}, env = {}) {
   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; read kanban_show for your task's declared doors, or use kanban_request_state, kanban_heartbeat or kanban_comment`);
-  const tid = args.task_id || own;
+  if (args.task_ids !== undefined && (!Array.isArray(args.task_ids) || !args.task_ids.length || args.task_ids.some(id => typeof id !== 'string' || !id.trim()))) return error('task_ids is a nonempty array of card ids.');
+  const tid = args.task_id || args.task_ids?.[0] || own;
   if (!['kanban_list', 'kanban_create', 'kanban_link'].includes(name) && !tid) return error('task_id is required (or HERMES_KANBAN_TASK in the environment)');
   const slug = args.board || env.HERMES_KANBAN_BOARD || DEFAULT_BOARD;
   // the board's workflow decides what each tool's event does; the worker is its run's role on its own task, and
@@ -44,6 +45,7 @@ export async function boardTool(root, name, args = {}, env = {}) {
     if (!own || !runId) return own ? [] : ['manager'];
     const meta = json(db.prepare('SELECT metadata FROM task_runs WHERE id = ?').get(runId)?.metadata, {})?.supercode ?? {};
     const roles = cardId === own ? [meta.role ?? 'implementer'] : [];
+    if (engine.getTask(db, cardId)?.subtask_of === own) roles.push('arc');
     if (name === 'kanban_comment' && isLatestReviewer(db, cardId, actorOf()) && !roles.includes('reviewer')) roles.push('reviewer');
     if (actorOf() && completionOwnerOf(db, cardId) === actorOf()) roles.push('creator');
     return roles;
@@ -53,8 +55,12 @@ export async function boardTool(root, name, args = {}, env = {}) {
   board.label = slug;
   const callingRun = runId ? json(board.db.prepare('SELECT metadata FROM task_runs WHERE id=?').get(runId)?.metadata, {})?.supercode : null;
   setActor(own && runId ? callingRun?.address ?? `hermes-run:${slug}:${runId}` : null);
-  if (own && LIFECYCLE.has(name) && tid !== own && completionOwnerOf(board.db, tid) !== actorOf()) {
-    board.close(); return error(`worker is scoped to task ${own}; refusing to change ${tid}. Use kanban_comment to hand off to other tasks.`);
+  const targets = name === 'kanban_request_state' ? [...new Set([tid, ...(args.task_ids ?? [])])] : [tid];
+  if (own && LIFECYCLE.has(name)) for (const target of targets) {
+    const arcTask = ['kanban_complete', 'kanban_request_state'].includes(name) && engine.getTask(board.db, target)?.subtask_of === own;
+    if (target !== own && !arcTask && completionOwnerOf(board.db, target) !== actorOf()) {
+      board.close(); return error(`worker is scoped to task ${own}; refusing to change ${target}. Use kanban_comment to hand off to other tasks.`);
+    }
   }
   const current = () => tx(board, (db) => engine.getTask(db, tid));
   // a worker whose run was superseded (reclaimed, re-dispatched) no longer speaks for the card
@@ -106,7 +112,7 @@ export async function boardTool(root, name, args = {}, env = {}) {
           }
         }
         if (env.HERMES_SESSION_ID && own === tid) metadata = { ...(metadata ?? {}), worker_session_id: env.HERMES_SESSION_ID };
-        await engine.complete(board, tid, { summary, result, metadata, commit: args.commit ?? null, ci_run: args.ci_run ?? null });
+        await engine.complete(board, tid, { summary, result, metadata, commit: args.commit ?? null, ci_run: args.ci_run ?? null, branch: args.branch ?? null, pr: args.pr ?? null, pr_head: args.pr_head ?? null, reviewed_sha: args.reviewed_sha ?? null });
         return ok({ task_id: tid, status: 'done' });
       }
       case 'kanban_block': {
@@ -116,12 +122,12 @@ export async function boardTool(root, name, args = {}, env = {}) {
       }
       case 'kanban_request_state': {
         const stale = ownRun(); if (stale) return error(stale);
-        await engine.act(board, tid, 'request_state', { payload: { state: args.state, reason: args.reason, on: args.on ?? null, waiting_on: args.waiting_on ?? null, evidence: args.evidence ?? null, commit: args.commit ?? null, ci_run: args.ci_run ?? null, deployed_sha: args.deployed_sha ?? null } });
-        return ok({ task_id: tid, requested: args.state, changed: false });
+        await engine.requestStateMany(board, targets, { state: args.state, reason: args.reason, on: args.on ?? null, waiting_on: args.waiting_on ?? null, evidence: args.evidence ?? null, commit: args.commit ?? null, ci_run: args.ci_run ?? null, branch: args.branch ?? null, pr: args.pr ?? null, pr_head: args.pr_head ?? null, reviewed_sha: args.reviewed_sha ?? null, deployed_sha: args.deployed_sha ?? null });
+        return ok({ task_id: tid, task_ids: targets, requested: args.state, changed: false });
       }
       case 'kanban_request_review': {
         const stale = ownRun(); if (stale) return error(stale);
-        await engine.requestReview(board, tid, { summary: args.summary ? redact(String(args.summary)) : null, metadata: args.metadata ? redact(args.metadata) : null, commit: args.commit ?? null, ci_run: args.ci_run ?? null, reviewer: args.reviewer ?? null, expectedRunId: own === tid && runId ? runId : null });
+        await engine.requestReview(board, tid, { summary: args.summary ? redact(String(args.summary)) : null, metadata: args.metadata ? redact(args.metadata) : null, commit: args.commit ?? null, ci_run: args.ci_run ?? null, branch: args.branch ?? null, pr: args.pr ?? null, pr_head: args.pr_head ?? args.commit ?? null, reviewer: args.reviewer ?? null, expectedRunId: own === tid && runId ? runId : null });
         return ok({ task_id: tid, status: 'review' });
       }
       case 'kanban_request_changes': {