@volter/supercode-orchestrator 0.4.147 → 0.4.149

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'];
@@ -37,7 +37,7 @@ export function getTask(db, id) {
   const row = one(db, 'SELECT * FROM tasks WHERE id = ?', id);
   if (!row) return null;
   const ours = one(db, 'SELECT * FROM supercode_cards WHERE task_id = ?', id);
-  return { ...row, workspace_anchor: ours?.workspace_anchor ?? null, review_only: Boolean(ours?.review_only), blocked_by: json(ours?.blocked_by, []) ?? [], paused: json(ours?.paused, null), archived: Boolean(ours?.archived), every: ours?.every ?? null, skills: json(row.skills, []) ?? [], machine: ours?.machine ?? null, subtask_of: ours?.subtask_of ?? null };
+  return { ...row, workspace_anchor: ours?.workspace_anchor ?? null, blocked_by: json(ours?.blocked_by, []) ?? [], paused: json(ours?.paused, null), archived: Boolean(ours?.archived), every: ours?.every ?? null, skills: json(row.skills, []) ?? [], machine: ours?.machine ?? null, subtask_of: ours?.subtask_of ?? null };
 }
 
 function must(db, id) {
@@ -152,10 +152,36 @@ function projectOf(root, idOrSlug) {
   } catch { return null; } finally { db.close(); }
 }
 
+/**
+ * A card's Tasks are its subtasks (the document renders them as its Tasks section). Task lines written in an arc's
+ * body (`## Tasks` then `- [ ] step`, its indented lines the step's own text) are answered as the steps to file as
+ * its subtasks, and leave the body. A Tasks section with no task line is the body's own text.
+ */
+export function bodyTasks(body) {
+  const lines = String(body ?? '').split('\n');
+  const at = lines.findIndex((line) => /^#{2,3}\s+Tasks\s*$/i.test(line));
+  if (at < 0) return { body, tasks: [] };
+  let end = lines.findIndex((line, i) => i > at && /^#{1,3}\s/.test(line));
+  if (end < 0) end = lines.length;
+  const section = lines.slice(at + 1, end);
+  if (!section.some((line) => /^[-*] \[[ xX]\]/.test(line))) return { body, tasks: [] };
+  const tasks = [];
+  for (const line of section) {
+    if (!line.trim()) continue;
+    const step = /^[-*] \[ \]\s+(\S.*)$/.exec(line);
+    if (step) tasks.push({ title: step[1].trim(), body: [] });
+    else if (/^\s+\S/.test(line) && tasks.length) tasks.at(-1).body.push(line.replace(/^\s{1,4}/, ''));
+    else throw new Error("A card's Tasks section holds open task lines ('- [ ] <step>', each filed as a subtask, with its own indented lines); record finished work as a comment and move other text out of the section");
+  }
+  const rest = [...lines.slice(0, at), ...lines.slice(end)].join('\n').replace(/\n{3,}/g, '\n\n').trim();
+  return { body: rest || null, tasks: tasks.map((t) => ({ title: t.title, body: t.body.join('\n') || null })) };
+}
+
 export function createCard(board, spec) {
-  if (spec.reviewOnly !== undefined && typeof spec.reviewOnly !== 'boolean') throw new Error('reviewOnly must be a boolean');
   const title = String(spec.title ?? '').trim();
   if (!title) throw new Error('a card has a title');
+  const steps = spec.subtaskOf ? [] : bodyTasks(spec.body).tasks;
+  if (steps.length) spec = { ...spec, body: bodyTasks(spec.body).body };
   const ws = parseWorkspace(spec.workspace ?? 'scratch');
   if (spec.branch && ws.kind === 'scratch') throw new Error('a scratch workspace has no repository branch');
   const parents = [...new Set((spec.parents ?? []).filter(Boolean))];
@@ -184,10 +210,6 @@ export function createCard(board, spec) {
     if (missing.length) throw new Error(`unknown parent card(s): ${missing.join(', ')}`);
     const arc = spec.subtaskOf ? getTask(db, spec.subtaskOf) : null;
     const entry = workflowFor(board.root);
-    if (spec.reviewOnly) {
-      const permitted = entry.params.review_only_by;
-      if (arc || spec.every || initial || !Array.isArray(permitted) || !callerRoles(db, arc?.id ?? '').some(role => permitted.includes(role))) throw new Error('Only a permitted manager creates a review-only arc, without recurrence, subtasks or an initial-status override.');
-    }
     if (spec.subtaskOf && !arc) throw new Error(`no card ${spec.subtaskOf} to be a subtask of`);
     if (arc?.subtask_of) throw new Error(`${arc.id} is itself a subtask of ${arc.subtask_of}; a subtask belongs to an arc`);
     let id = newTaskId();
@@ -216,13 +238,13 @@ export function createCard(board, spec) {
       spec.skills?.length ? JSON.stringify(spec.skills) : null, spec.maxRetries ?? null, spec.model ?? null, spec.provider ?? null,
       spec.reasoning ?? null, spec.sessionId ?? null, spec.project ?? null, spec.goal ? 1 : 0, spec.goal?.maxTurns ?? null);
     const machine = spec.machine ?? arc?.machine ?? null;
-    run(db, 'INSERT OR REPLACE INTO supercode_cards (task_id,machine,subtask_of,workspace_anchor,workspace_root,review_only) VALUES (?,?,?,?,?,?)', id, machine, arc?.id ?? null, declared.repository, checked?.mainRoot ?? null, spec.reviewOnly ? 1 : 0);
+    run(db, 'INSERT OR REPLACE INTO supercode_cards (task_id,machine,subtask_of,workspace_anchor,workspace_root) VALUES (?,?,?,?,?)', id, machine, arc?.id ?? null, declared.repository, checked?.mainRoot ?? null);
     for (const p of parents) addDependency(db, entry, id, p);
     // where it starts is the workflow's `initial` (Hermes: triage, blocked, todo behind open parents, else ready)
     // the create's own words: whether it asked to be a goal card (null: the workflow decides), triage, its arc
     const status = startNew(db, board, entry, getTask(db, id), { triage: Boolean(spec.triage), initial_status: initial,
-      review_only: Boolean(spec.reviewOnly), every: spec.every ?? null, goal: spec.goal === undefined || spec.goal === null ? null : spec.goal !== false, subtask_of: arc?.id ?? null });
-    event(db, id, 'created', { creator: actorOf(), assignee: spec.assignee || null, status, review_only: Boolean(spec.reviewOnly), parents, tenant: spec.tenant ?? null, ...(machine ? { machine } : {}), ...(arc ? { subtask_of: arc.id } : {}) });
+      every: spec.every ?? null, goal: spec.goal === undefined || spec.goal === null ? null : spec.goal !== false, subtask_of: arc?.id ?? null });
+    event(db, id, 'created', { creator: actorOf(), assignee: spec.assignee || null, status, parents, tenant: spec.tenant ?? null, ...(machine ? { machine } : {}), ...(arc ? { subtask_of: arc.id } : {}) });
     if ((spec.noStart || spec.adopt) && !arc) event(db, id, 'dispatch_held', { session: spec.adopt ?? null, reason: spec.adopt ? 'awaiting adoption' : 'created with --no-start' });
     if (parents.length) inheritSubscriptions(db, id, parents);
     if (arc) {
@@ -232,7 +254,9 @@ export function createCard(board, spec) {
     }
     if (initial === 'running' && arc && entry.workflow.run) setStatus(db, entry.workflow, id, 'running');
     else if (initial === 'running') claimIn(db, id, { ttl: claimTtl() });
-    return { id, existing: false };
+    // the body's task lines, as subtasks the creator filed, in this same write
+    const subtasks = steps.map((step) => createCard(board, { ...step, subtaskOf: id, assignee: spec.assignee || null }).id);
+    return { id, existing: false, ...(subtasks.length ? { subtasks } : {}) };
   });
 }
 
@@ -343,11 +367,16 @@ 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) };
+  const evidencePhase = ['complete', 'request_review', 'request_state'].includes(name) ? completionPhase(board, id, entry, name, payload, roles ?? callerRoles(board.db, id)) : null;
+  if (evidencePhase) payload = { ...payload, ci: observeCompletionEvidence(board, id, entry, payload, evidencePhase) };
+  if (payload.ci?.required && !payload.ci.ready && (name !== 'request_state' || evidencePhase === 'review_verdict')) 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 +384,34 @@ 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);
+    const phase = completionPhase(board, id, entry, 'request_state', payload, roles);
+    const evidence = inspectCompletionEvidence(board, id, entry, payload, phase);
+    // An ordinary request mails a decision to the manager, not a completion.
+    // Keep a failed source observation in that mail. A reviewer recording an
+    // actual verdict still has to verify the requested PR head.
+    if (phase === 'review_verdict' && evidence.required && !evidence.ready) throw new Error(evidence.reason ?? 'The reviewed PR head could not be verified.');
+    return [id, evidence];
+  }));
+  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 +433,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 +509,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 });
@@ -468,16 +524,24 @@ export const schedule = (board, id, reason = null, { roles } = {}) => act(board,
 export const promote = (board, id, { actor = 'user', reason = null, force = false, roles } = {}) => act(board, id, 'promote', { roles, payload: { actor, reason, force } });
 export const reclaim = (board, id, reason = null, { roles } = {}) => act(board, id, 'reclaim', { roles, payload: { reason } });
 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 } = {}) {
+export async function specify(board, id, { title = null, body = null, workspace = null, branch = 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 } : {}) } });
+  // an arc's new task lines are filed as its subtasks once the specify itself is accepted
+  const steps = body != null && !one(board.db, 'SELECT subtask_of FROM supercode_cards WHERE task_id = ?', id)?.subtask_of ? bodyTasks(body) : { body, tasks: [] };
+  const done = await act(board, id, 'specify', { roles, payload: { title, body: steps.body, author, ...(declaration ? { workspace: declaration } : {}) } });
+  for (const step of steps.tasks) createCard(board, { ...step, subtaskOf: id, assignee: getTask(board.db, id)?.assignee || null });
+  return done;
 }
 export const editResult = (board, id, { result, summary = null, metadata = undefined, roles } = {}) => act(board, id, 'edit', { roles, payload: { result, summary, metadata } });
 export const heartbeat = (board, id, note = null, { roles, until = null } = {}) => act(board, id, 'heartbeat', { roles, payload: { note, until } });
@@ -522,12 +586,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 +610,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;
@@ -597,7 +698,6 @@ export function cardContext(db, id) {
   const task = must(db, id);
   const out = [`# Card ${task.id}: ${task.title}`, ''];
   out.push(`Status: ${task.status}. Machine: ${task.machine ?? 'unset'}. Workspace: ${task.workspace_kind}${task.workspace_anchor ? ` ${task.workspace_anchor}` : task.workspace_path ? ` ${task.workspace_path}` : ''}${task.branch_name ? ` (branch ${task.branch_name})` : ''}.${task.subtask_of ? ` A subtask of ${task.subtask_of}.` : ''}`);
-  if (task.review_only) out.push('Purpose: review-only. Record the independent verdict with request-state --state done --reason <verdict> --evidence <artifact>; its creator or manager accepts this review job.');
   if (task.body) out.push('', cap(task.body, 8 * 1024));
   const parents = all(db, 'SELECT t.id, t.title, t.result FROM tasks t JOIN task_links l ON l.parent_id = t.id WHERE l.child_id = ?', id);
   if (parents.length) {

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/store.mjs

@@ -73,7 +73,7 @@ const OURS = `CREATE TABLE IF NOT EXISTS supercode_cards (task_id TEXT PRIMARY K
 CREATE TABLE IF NOT EXISTS supercode_effects (id INTEGER PRIMARY KEY AUTOINCREMENT, effect TEXT NOT NULL);`;
 // `stage`: the card's workflow status where kanban.db stores another (a `reviewing` card is `running` to Hermes)
 // `since`: when the card entered its workflow status; `after_fired`: which of the status's `after` moves have run since
-const OURS_COLUMNS = { workspace_anchor: 'TEXT', workspace_root: 'TEXT', subtask_of: 'TEXT', review_only: 'INTEGER DEFAULT 0', stage: 'TEXT', since: 'INTEGER', after_fired: 'TEXT', blocked_by: 'TEXT', paused: 'TEXT', archived: 'INTEGER DEFAULT 0', every: 'TEXT', next_run_at: 'INTEGER' };
+const OURS_COLUMNS = { workspace_anchor: 'TEXT', workspace_root: 'TEXT', subtask_of: 'TEXT', stage: 'TEXT', since: 'INTEGER', after_fired: 'TEXT', blocked_by: 'TEXT', paused: 'TEXT', archived: 'INTEGER DEFAULT 0', every: 'TEXT', next_run_at: 'INTEGER' };
 
 // ------------------------------------------------------------------ backings
 //
@@ -172,18 +172,21 @@ export const tx = (board, fn) => {
 export const view = (board, fn) => fn(board.db);
 
 // A deferred native transaction, with the whole operation retried on an optimistic conflict.
-// There is no separate application writer lock or contention timeout.
+// There is no separate application writer lock or contention timeout. A write inside one is part of it.
+const inTx = new WeakSet();
 function sqliteTx(db, fn) {
+  if (inTx.has(db)) return fn(db);
   for (;;) {
     try {
       db.exec('BEGIN');
+      inTx.add(db);
       const out=fn(db);
       db.exec('COMMIT');
       return out;
     } catch(error) {
       try {db.exec('ROLLBACK');} catch {}
       if (!/locked|busy/i.test(error.message))throw error;
-    }
+    } finally { inTx.delete(db); }
   }
 }
 

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
@@ -74,7 +80,7 @@ export async function boardTool(root, name, args = {}, env = {}) {
         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, review_only: Boolean(t.review_only) },
+            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,
@@ -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': {
@@ -170,7 +176,7 @@ export async function boardTool(root, name, args = {}, env = {}) {
           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, reviewOnly: args.review_only ?? false,
+          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 });
       }