@volter/supercode-orchestrator 0.4.146 → 0.4.148

package/board/ci.mjs

@@ -1,11 +1,10 @@
-// Deployment evidence is observed before a board mutation. No network or Git
-// process runs inside the optimistic transaction that decides completion.
+// Review candidates are observed before a board mutation. No network or Git
+// process runs inside the optimistic transaction. Deployment is not a completion gate.
 import { spawnSync } from 'node:child_process';
-import { readFileSync, realpathSync, writeFileSync, renameSync, lstatSync } from 'node:fs';
+import { readFileSync, realpathSync, writeFileSync, renameSync } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
-import { homedir } from 'node:os';
-import { pathToFileURL } from 'node:url';
 import { createHash } from 'node:crypto';
+import { resolveWorkspace } from './workspace.mjs';
 
 const observations = new Map();
 const key = (board, id) => `${board.root}\0${board.slug}\0${id}`;
@@ -14,14 +13,19 @@ const run = (program, args, cwd) => {
   if (result.status !== 0) throw new Error(`${program}: ${(result.stderr || result.error?.message || 'command failed').trim().slice(-500)}`);
   return result.stdout.trim();
 };
-const codePath = path => path && !/^(?:docs\/|\.volter\/tracker\/)/.test(path) && (!/\.(?:md|txt|png|jpg|svg)$/i.test(path) || /(?:^|\/)prompts\//.test(path));
 
 export function completionEvidence(board, id) {
-  return observations.get(key(board, id)) ?? { required: true, ready: false, reason: 'Deployment evidence has not been observed; request review or done through the board CLI with --commit and --ci-run.' };
+  return observations.get(key(board, id)) ?? { required: false, ready: true, phase: 'source', deployed_sha: null };
 }
 
-export function observeCompletionEvidence(board, id, entry, payload = {}) {
-  const state = inspectCompletionEvidence(board, id, entry, payload);
+export function completionPhase(board, id, entry, verb, payload, roles = []) {
+  if (verb === 'request_review') return 'request_review';
+  if ((verb === 'request_state' && payload.state === 'done' || verb === 'complete') && roles.includes('reviewer')) return 'review_verdict';
+  return verb === 'complete' ? 'acceptance' : 'completion';
+}
+
+export function observeCompletionEvidence(board, id, entry, payload = {}, phase = 'completion') {
+  const state = inspectCompletionEvidence(board, id, entry, payload, phase);
   observations.set(key(board, id), state);
   return state;
 }
@@ -37,111 +41,103 @@ export function withCompletionEvidence(board, id, state, fn) {
   }
 }
 
-export function inspectCompletionEvidence(board, id, entry, payload = {}) {
-  const state = { required: true, ready: false, reason: null };
-  if (!entry.params.completion_ci) { Object.assign(state, { required: false, ready: true }); return state; }
+/** The latest explicitly requested PR is the reviewer's candidate, never the deployment tip. */
+export function reviewCandidate(board, id) {
+  const row = board.db.prepare("SELECT payload FROM task_events WHERE task_id=? AND kind='review_requested' ORDER BY id DESC LIMIT 1").get(id);
+  const payload = row && JSON.parse(row.payload);
+  return payload?.ci?.pr ? payload.ci : null;
+}
+
+function repositoryWorkspace(board, id) {
+  const task = board.db.prepare('SELECT t.*,c.subtask_of,c.workspace_anchor,c.machine FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.id=?').get(id);
+  const parent = task?.subtask_of && board.db.prepare('SELECT t.*,c.workspace_anchor,c.machine FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.id=?').get(task.subtask_of);
+  const workspace = task?.workspace_kind === 'scratch' ? parent : task;
+  return workspace?.workspace_kind !== 'scratch' && workspace?.workspace_anchor ? resolveWorkspace(workspace, false).path : workspace?.workspace_kind !== 'scratch' ? workspace?.workspace_path : null;
+}
+
+const pullRequestLists = new Map();
+
+/** Find an opened PR for this card's declared worktree branch; caller decides the transition. */
+export function openReviewPullRequest(board, id) {
+  const path = repositoryWorkspace(board, id);
+  if (!path) return null;
+  const task = board.db.prepare('SELECT branch_name FROM tasks WHERE id=?').get(id);
+  const branch = task?.branch_name ?? run('git', ['branch', '--show-current'], path);
+  if (!branch) return null;
+  const repository = /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/.exec(run('git', ['remote', 'get-url', 'origin'], path))?.[1];
+  if (!repository) return null;
+  // Discovery is shared per repository for one minute; the selected PR/head is
+  // always re-read by inspectCompletionEvidence before it authorizes a move.
+  let list = pullRequestLists.get(repository);
+  if (!list || Date.now() - list.at >= 60_000) {
+    list = { at: Date.now(), items: JSON.parse(run('gh', ['pr', 'list', '--repo', repository, '--state', 'open', '--limit', '1000', '--json', 'url,headRefOid,headRefName,baseRefName,isCrossRepository'], path)) };
+    if (pullRequestLists.size >= 32) pullRequestLists.delete(pullRequestLists.keys().next().value);
+    pullRequestLists.set(repository, list);
+  }
+  const prs = list.items.filter(pr => pr.headRefName === branch && !pr.isCrossRepository);
+  if (prs.length !== 1) return null;
+  return { pr: prs[0].url, pr_head: prs[0].headRefOid, commit: prs[0].headRefOid, branch };
+}
+
+export function inspectCompletionEvidence(board, id, entry, payload = {}, stage = 'completion') {
+  const state = { required: false, ready: true, reason: null, phase: 'source', deployed_sha: null };
   try {
-    const task = board.db.prepare('SELECT t.*,c.subtask_of,c.workspace_anchor FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.id=?').get(id);
-    const parent = task?.subtask_of && board.db.prepare('SELECT workspace_path FROM tasks WHERE id=?').get(task.subtask_of);
-    const path = task?.workspace_path ?? parent?.workspace_path;
-    const old = board.db.prepare("SELECT payload FROM task_events WHERE task_id=? AND kind IN ('review_requested','state_requested','review_pass') ORDER BY id DESC LIMIT 20").all(id)
-      .map(row => { try { return JSON.parse(row.payload)?.ci; } catch { return null; } }).find(ci => ci?.commit);
-    const supplied = payload.commit ?? payload.metadata?.commit ?? old?.commit;
-    if (!path) {
-      if (supplied) throw new Error('The named commit needs a resolved repository workspace.');
-      Object.assign(state, { required: false, ready: true }); return state;
-    }
-    const history = run('git', ['log', '--all', '--format=%H%x00', '--name-only', '--fixed-strings', `--grep=${id}`], path);
-    const records = [...history.matchAll(/([a-f0-9]{40})\0([^\0]*?)(?=[a-f0-9]{40}\0|$)/gs)];
-    const latest = records.find(([, , names]) => names.split('\n').some(codePath))?.[1];
-    if (!latest && !supplied) { Object.assign(state, { required: false, ready: true }); return state; }
-    const commit = run('git', ['rev-parse', '--verify', `${supplied ?? latest}^{commit}`], path);
-    if (latest) run('git', ['merge-base', '--is-ancestor', latest, commit], path);
-    const remote = run('git', ['remote', 'get-url', 'origin'], path);
-    const repo = /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/.exec(remote)?.[1];
-    if (!repo) throw new Error('Deployment evidence requires this workspace\'s GitHub origin.');
-    Object.assign(state, { commit, repository: repo });
-    const controller = entry.params.completion_ci.controller_deployments?.[repo];
-    if (controller) {
-      const expand = value => value.startsWith('~/') ? join(homedir(), value.slice(2)) : value;
-      const installed = expand(controller.installed_path);
-      if (!lstatSync(installed).isSymbolicLink()) throw new Error('The controller installation must be the declared checkout symlink.');
-      const skill = realpathSync(installed), checkout = run('git', ['rev-parse', '--show-toplevel'], skill);
-      const origin = /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/.exec(run('git', ['remote', 'get-url', 'origin'], checkout))?.[1];
-      if (origin !== repo) throw new Error('The controller installation points to another repository.');
-      const head = run('git', ['rev-parse', 'HEAD'], checkout);
-      run('git', ['merge-base', '--is-ancestor', commit, head], checkout);
-      run('git', ['diff', '--quiet', 'HEAD', '--', relative(checkout, join(skill, 'scripts'))], checkout);
-      const sourceHash = run(process.execPath, ['--experimental-strip-types', '--input-type=module', '-e',
-        'const m=await import(process.argv[1]); process.stdout.write(m.installedSourceHash())', pathToFileURL(join(skill, 'scripts/controller-diagnostics.ts')).href], checkout);
-      const port = Number(readFileSync(expand(controller.port_file), 'utf8').trim());
-      if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('The controller has no valid retained port.');
-      const url = `http://127.0.0.1:${port}/health`;
-      const health = JSON.parse(run('curl', ['--fail', '--silent', '--show-error', '--max-time', '2', url], checkout));
-      if (!health.alive || !health.cdp_connected || health.restart_required !== false || health.controller?.source_hash !== sourceHash || health.installed_source_hash !== sourceHash) throw new Error('The running browser controller has not loaded the committed installed code.');
-      Object.assign(state, { ready: true, workflow: 'installed browser controller', run_id: `${health.controller.pid}@${health.controller.started_at}`, status: 'completed', conclusion: 'success', deployed_sha: head, url, source_hash: sourceHash });
+    const path = repositoryWorkspace(board, id);
+    if (stage === 'completion' || stage === 'acceptance') {
+      const supplied = payload.commit ?? payload.metadata?.commit;
+      if (supplied) {
+        if (!path) throw new Error('The named commit needs a resolved repository workspace.');
+        const repository = /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/.exec(run('git', ['remote', 'get-url', 'origin'], path))?.[1];
+        Object.assign(state, { repository, commit: run('git', ['rev-parse', '--verify', `${supplied}^{commit}`], path) });
+      }
+      const candidate = stage === 'acceptance' ? reviewCandidate(board, id) : null;
+      if (candidate) {
+        const row = board.db.prepare("SELECT payload FROM task_events WHERE task_id=? AND kind='review_pass' ORDER BY id DESC LIMIT 1").get(id);
+        const pass = row && JSON.parse(row.payload)?.ci;
+        if (pass?.commit !== candidate.commit || pass?.pr?.url !== candidate.pr.url) throw new Error('The current PR head needs its independent verdict before acceptance.');
+        const pr = JSON.parse(run('gh', ['pr', 'view', candidate.pr.url, '--repo', candidate.repository, '--json', 'state,headRefOid'], path));
+        if (!['OPEN', 'MERGED'].includes(pr.state) || pr.headRefOid !== candidate.commit) throw new Error('The PR head changed after its verdict; request a new review.');
+        Object.assign(state, { ...candidate, ready: true, reason: null });
+      }
       return state;
     }
-    if (entry.params.completion_ci.keeper_repositories?.includes(repo)) {
-      const receiptPath = join(board.root, 'runtime-deployment.json');
-      const receipt = JSON.parse(readFileSync(receiptPath, 'utf8'));
-      if (receipt.repository !== repo || receipt.completed_at < Number(run('git', ['show', '-s', '--format=%ct', commit], path)) * 1000) throw new Error('No keeper tick after this runtime commit.');
-      run('git', ['merge-base', '--is-ancestor', commit, receipt.head], receipt.checkout);
-      const current = workflowRevision(board.root);
-      if (!current || current.head !== receipt.head || current.workflow_hash !== receipt.workflow_hash) throw new Error('The retained keeper tick does not describe the live checkout and loaded workflow revision.');
-      Object.assign(state, { ready: true, workflow: 'launchd keeper', run_id: `${receipt.pid}@${receipt.completed_at}`, status: 'completed', conclusion: 'success', deployed_sha: receipt.head, url: receiptPath });
+    const asked = stage === 'review_verdict' ? reviewCandidate(board, id) : null;
+    const pr = payload.pr ?? payload.metadata?.pr ?? asked?.pr?.url;
+    if (!path) {
+      if (pr) throw new Error('A PR candidate needs a resolved repository workspace.');
       return state;
     }
-    const configured = entry.params.completion_ci.workflows?.[repo] ?? entry.params.completion_ci.workflows?.['*'];
-    if (!Array.isArray(configured) || !configured.length) throw new Error(`No deployment workflow is declared for ${repo} in completion_ci.workflows.`);
-    const matchedRules = (entry.params.completion_ci.path_workflows?.[repo] ?? []).map(rule => ({ ...rule,
-      changed_at: records.find(([, , names]) => names.split('\n').some(path => rule.paths.some(prefix => path.startsWith(prefix))))?.[1]
-    })).filter(rule => rule.changed_at);
-    const requestedRun = payload.ci_run ?? payload['ci-run'] ?? payload.metadata?.ci_run ?? (old?.commit === commit ? old?.run_id : null);
-    let receipt;
-    if (requestedRun) {
-      receipt = JSON.parse(run('gh', ['run', 'view', String(requestedRun), '--repo', repo, '--json', 'databaseId,workflowName,headSha,status,conclusion,url'], path));
-    } else {
-      const runs = JSON.parse(run('gh', ['run', 'list', '--repo', repo, '--commit', commit, '--limit', '100', '--json', 'databaseId,workflowName,headSha,status,conclusion,url'], path));
-      receipt = runs.find(row => configured.includes(row.workflowName));
-    }
-    if (!receipt) throw new Error(`No deployment CI run exists for ${repo}@${commit}.`);
-    Object.assign(state, { run_id: receipt.databaseId, workflow: receipt.workflowName, status: receipt.status, conclusion: receipt.conclusion, url: receipt.url });
-    if (receipt.headSha !== commit) throw new Error(`CI run ${receipt.databaseId} is for ${receipt.headSha}, not ${commit}.`);
-    if (!configured.includes(receipt.workflowName)) throw new Error(`${receipt.workflowName} is not a declared deployment workflow for ${repo}.`);
-    if (receipt.status !== 'completed' || receipt.conclusion !== 'success') throw new Error(`Deployment CI ${receipt.databaseId} is ${receipt.status}/${receipt.conclusion || 'pending'}.`);
-    // A later SDK publication need not rebuild unchanged native code. It does
-    // need a successful native deployment containing this task's native changes.
-    // Retain each artifact's actual SHA, rather than calling the SDK run a native release.
-    state.coverage = [];
-    const deployments = new Map();
-    for (const rule of matchedRules) {
-      if (rule.workflows.includes(receipt.workflowName)) continue;
-      for (const workflow of rule.workflows) {
-        if (!deployments.has(workflow)) deployments.set(workflow, JSON.parse(run('gh', ['run', 'list', '--repo', repo, '--workflow', workflow, '--limit', '100', '--json', 'databaseId,workflowName,headSha,status,conclusion,url'], path)));
-      }
-      const successful = rule.workflows.flatMap(workflow => deployments.get(workflow)).filter(row => row.status === 'completed' && row.conclusion === 'success');
-      const covering = successful.find(row => {
-        if (!rule.workflows.includes(row.workflowName) || !configured.includes(row.workflowName)) return false;
-        try {
-          run('git', ['merge-base', '--is-ancestor', rule.changed_at, row.headSha], path);
-          try {
-            run('git', ['merge-base', '--is-ancestor', commit, row.headSha], path);
-            return true;
-          } catch {}
-          run('git', ['merge-base', '--is-ancestor', row.headSha, commit], path);
-          // Any later change in these paths requires another native deployment,
-          // even when a different task authored that change.
-          return run('git', ['diff', '--name-only', row.headSha, commit], path).split('\n').every(name => !rule.paths.some(prefix => name.startsWith(prefix)));
-        } catch { return false; }
-      });
-      if (!covering) throw new Error(`No successful ${rule.workflows.join('/')} deployment covers ${rule.paths.join(', ')} through ${commit}.`);
-      state.coverage.push({ paths: rule.paths, commit: covering.headSha, workflow: covering.workflowName, run_id: covering.databaseId, conclusion: covering.conclusion, url: covering.url });
+    // Repository-free review-only jobs keep their own verdict contract. Ordinary
+    // implementation reviews always name an opened PR, independent of completion_ci.
+    if (stage === 'review_verdict' && !asked && !pr) return state;
+    Object.assign(state, { required: true, ready: false });
+    if (typeof pr !== 'string' || !/^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/[1-9][0-9]*\/?$/.test(pr)) throw new Error('Name the opened PR URL with --pr.');
+    const repository = /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/.exec(run('git', ['remote', 'get-url', 'origin'], path))?.[1];
+    if (!repository || new URL(pr).pathname.split('/').slice(1, 3).join('/') !== repository) throw new Error('The PR must belong to this workspace repository.');
+    const observed = JSON.parse(run('gh', ['pr', 'view', pr, '--repo', repository, '--json', 'url,number,state,headRefOid,headRefName,baseRefName,isCrossRepository'], path));
+    if (observed.state !== 'OPEN' || observed.isCrossRepository) throw new Error('Source review needs an open PR from this repository.');
+    const supplied = payload.pr_head ?? payload.reviewed_sha ?? payload.commit ?? payload.metadata?.pr_head ?? payload.metadata?.commit;
+    if (!supplied || !/^[a-f0-9]{40}$/.test(supplied)) throw new Error('Name the full PR head commit with --pr-head (reviewer: --reviewed-sha).');
+    if (observed.headRefOid !== supplied) throw new Error(`PR head changed to ${observed.headRefOid}; request review of that head before recording a verdict.`);
+    const branch = payload.branch ?? payload.metadata?.branch ?? observed.headRefName;
+    const mainBranch = entry.params.completion_ci?.main_branches?.[repository] ?? 'main';
+    if (branch !== observed.headRefName || branch === mainBranch || observed.baseRefName !== mainBranch) throw new Error('The PR must propose its named worktree branch to the repository main branch.');
+    if (stage === 'request_review') {
+      run('git', ['check-ref-format', '--branch', branch], path);
+      if (run('git', ['rev-parse', 'HEAD'], path) !== supplied) throw new Error('The named PR head must be this worktree head.');
+      run('git', ['diff', '--quiet', 'HEAD'], path);
+      if (run('git', ['ls-files', '--others', '--exclude-standard'], path)) throw new Error('Commit the untracked work before requesting review.');
+      const pushed = run('git', ['ls-remote', '--heads', 'origin', `refs/heads/${branch}`], path).split(/\s+/)[0];
+      if (pushed !== supplied) throw new Error('Push the exact PR head before requesting review.');
+    } else if (asked) {
+      if (asked.commit !== supplied || asked.pr.url !== observed.url) throw new Error('The verdict must name the requested PR and head.');
+      const latest = board.db.prepare('SELECT metadata FROM task_runs WHERE task_id=? ORDER BY id DESC LIMIT 1').get(id);
+      const bound = latest && JSON.parse(latest.metadata ?? '{}')?.supercode?.review_candidate;
+      if (bound && (bound.commit !== supplied || bound.pr?.url !== observed.url)) throw new Error('This reviewer run was launched for a different PR head.');
     }
-    state.deployed_sha = commit;
-    state.ready = true;
-    state.reason = null;
-  } catch (error) { state.reason = error.message; }
+    Object.assign(state, { ready: true, repository, branch, commit: supplied, source_sha: supplied,
+      pr: { url: observed.url, number: observed.number, head: supplied, branch, base: observed.baseRefName }, reason: null });
+  } catch (error) { Object.assign(state, { required: true, ready: false, reason: error.message }); }
   return state;
 }
 

package/board/cli.mjs

@@ -36,9 +36,10 @@ Hermes Kanban's verbs, with their flags:
   block <id> [reason] (--on <card> | --waiting-on <message id>) [--ids ...]   schedule <id> [reason] [--ids ...]
   pause <id> --reason <why>   resume <id>   cancel <id>   set-every <id> <interval|none>
   request-state <id> --state block|pause|done|cancelled --reason <why> [--on <card>|--waiting-on <message>] [--evidence <pointers>]
-  unblock <id>... [--reason]   request-review <id> [--summary] [--reviewer] [--force]   request-changes <id> <reason>   reopen-review <id>...   reopen <id>... [--reason]
+  unblock <id>... [--reason]   request-review <id> --pr URL --pr-head SHA [--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]
+  specify <id> [--title --body] [--workspace scratch|worktree:<repository>|dir:<repository>] [--branch NAME] [--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 [--interval S] [--max N] [--failure-limit N] [--pidfile F] [--verbose]   gc [--event-retention-days] [--log-retention-days]   repair
@@ -52,6 +53,8 @@ supercode's own:
       waits, and its creator is told when it starts. A subtask is worked by its arc's session and never starts alone.
   move <id> <machine|none>   adopt <id> <session> [--assignee P] [--role ROLE]   close <id>   serve (= daemon)   list --machine M
   notify-subscribe <id> --address sc:<machine>:<harness>:<id> [--role creator|worker|dependency]
+  notify-subscribe <dependency> --for-card <your-arc>: subscribe only your arc's session to dependency notices.
+  notify-unsubscribe <dependency> --for-card <your-arc>: remove that arc's subscription only.
   Any verb … --at sc:<machine>:board:<home>: sent as mail to a board kept on another machine.
   <event> <id>... [reason] [--<field> value]: any other event the board's workflow declares, its flags the event's fields.
   start <id>               release a --no-start hold and start through the declared workflow
@@ -59,6 +62,11 @@ supercode's own:
   goto <id> <status> [reason] [--<field> value]: the event the workflow says takes the card to that status, sent.
 
   specify <id> --review-only|--no-review-only: a manager declares a standalone independent review job.
+  specify <id> --workspace dir:<repository> --branch NAME: the manager retargets a stopped card without replacing its history.
+  request-review <id> --pr URL --pr-head SHA [--branch NAME]: hand over an open PR at its pushed head.
+  request-state <id> --state done --reviewed-sha SHA: record the verdict for the requested PR head.
+  request-state <id>... --state STATE --reason REASON: request several decisions in one retained manager mail.
+  complete <id>: creator/manager accepts the independently reviewed arc; deployment CI is not a board gate.
   specify/decompose with no spec start a session on the triage card to write it. A card's own session may comment on,
   heartbeat and request review of its card, specify or decompose it in triage, and work its subtasks. The home's
   workflow declares who may block, pause or finish a card; request-state mails its manager without changing state.
@@ -544,7 +552,7 @@ export async function runWorkflow(argv) {
     case 'complete': {
       need(1, 'a card id');
       const metadata = metadataOf(args.metadata);
-      for (const t of rest) await withBoardAsync((b) => engine.complete(b, t, { summary: args.summary ?? null, result: args.result ?? null, metadata: metadata ?? null, commit: args.commit ?? null, ci_run: args['ci-run'] ?? null }));
+      for (const t of rest) await withBoardAsync((b) => engine.complete(b, t, { summary: args.summary ?? null, result: args.result ?? null, metadata: 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'] ?? null, reviewed_sha: args['reviewed-sha'] ?? null }));
       say(args, rest.map((t) => `Completed ${t}`).join('\n'), { ok: true, completed: rest }); return 0;
     }
     case 'edit': {
@@ -574,7 +582,7 @@ export async function runWorkflow(argv) {
       if (args.reason) for (const [t] of results) await withBoardAsync((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'); await withBoardAsync((b) => engine.requestReview(b, id, { summary: args.summary ?? null, reviewer: args.reviewer ?? null, metadata: metadataOf(args.metadata) ?? null, commit: args.commit ?? null, ci_run: args['ci-run'] ?? null, force: Boolean(args.force), expectedRunId: workerRun(b.db, id, sid) })); say(args, `${id} → review`, { ok: true }); return 0;
+    case 'request-review': need(1, 'a card id'); await withBoardAsync((b) => engine.requestReview(b, id, { summary: args.summary ?? null, reviewer: args.reviewer ?? null, metadata: metadataOf(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.head ?? args.commit ?? null, force: Boolean(args.force), expectedRunId: workerRun(b.db, id, sid) })); say(args, `${id} → review`, { ok: true }); return 0;
     case 'request-changes': need(2, 'a card id and the reason'); await withBoardAsync((b) => engine.requestChanges(b, id, { reason: rest.slice(1).join(' '), reviewer: args.reviewer ?? null })); 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)
@@ -629,7 +637,7 @@ export async function runWorkflow(argv) {
       if (!targets[0]) throw new Error(`${verb} needs a card id, or --all`);
       const results = [];
       for (const t of targets) {
-        if (verb === 'specify' && (args.title !== undefined || args.body !== undefined || args.workspace !== undefined || args['review-only'] || args['no-review-only'])) {
+        if (verb === 'specify' && (args.title !== undefined || args.body !== undefined || args.workspace !== undefined || args.branch !== undefined || args['review-only'] || args['no-review-only'])) {
           const moved = await withBoardAsync((b) => engine.specify(b, t, { title: args.title ?? null, body: args.body ?? null, workspace: args.workspace ?? null, branch: args.branch ?? null, reviewOnly: args['review-only'] ? true : args['no-review-only'] ? false : null, author: args.author ?? callerAddress() ?? callerName() }));
           results.push({ id: t, specified: true, status: moved.to });
         } else if (verb === 'decompose' && args.child?.length) {
@@ -711,6 +719,12 @@ export async function runWorkflow(argv) {
 
     case 'notify-subscribe': case 'notify-unsubscribe': {
       need(1, 'a card id');
+      if (args['for-card']) {
+        if (args.address || args['chat-id'] || args['thread-id'] || (args.platform && args.platform !== 'supercode') || (args.role && args.role !== 'dependency')) throw new Error('--for-card targets that arc\'s session; do not supply another recipient or audience.');
+        const subscription = withBoard(board => engine.subscribeDependency(board, args['for-card'], id, { remove: verb === 'notify-unsubscribe' }));
+        say(args, verb === 'notify-unsubscribe' ? `Removed ${args['for-card']}'s dependency subscription to ${id}` : `${args['for-card']} hears ${id} through ${subscription.address}`, { ok: true, ...subscription });
+        return 0;
+      }
       const platform = args.platform ?? 'supercode';
       const chat = args['chat-id'] ?? args.address ?? (platform === 'supercode' ? callerAddress() : null);
       if (!chat) throw new Error(`${verb} names the subscriber: --platform P --chat-id C (a supercode session's address with --platform supercode)`);
@@ -863,9 +877,10 @@ export async function runWorkflow(argv) {
       if (!declared) throw new Error(`no workflow verb ${verb}; \`supercode workflow help\` lists them`);
       need(1, 'a card id');
       const { _: _words, root: _r, board: _b, json: _j, at: _a, ids: _i, ...fields } = args;
-      const payload = { ...fields, ci_run: args['ci-run'] ?? fields.ci_run, deployed_sha: args['deployed-sha'] ?? fields.deployed_sha, waiting_on: args['waiting-on'] ?? fields.waiting_on, reason: args.reason ?? (rest.slice(1).join(' ') || null) };
+      const payload = { ...fields, ci_run: args['ci-run'] ?? fields.ci_run, deployed_sha: args['deployed-sha'] ?? fields.deployed_sha, reviewed_sha: args['reviewed-sha'] ?? fields.reviewed_sha, pr_head: args['pr-head'] ?? fields.pr_head, waiting_on: args['waiting-on'] ?? fields.waiting_on, reason: args.reason ?? (name === 'request_state' ? null : rest.slice(1).join(' ') || null) };
       const results = [];
-      for (const t of [id, ...(args.ids ?? [])]) results.push([t, (await withBoardAsync((b) => engine.act(b, t, name, { payload }))).to]);
+      if (name === 'request_state') results.push(...await withBoardAsync(board => engine.requestStateMany(board, [...rest, ...(args.ids ?? [])], payload)));
+      else for (const t of [id, ...(args.ids ?? [])]) results.push([t, (await withBoardAsync((b) => engine.act(b, t, name, { payload }))).to]);
       say(args, results.map(([t, s]) => name === 'request_state' ? `${t}: ${payload.state} requested; state remains ${s}. Mail delivery is recorded on the card.` : `${t} → ${s}`).join('\n'), { ok: true, results }); return 0;
     }
   }
@@ -1101,7 +1116,11 @@ function rolesFor(db, cardId, sessionId, params = {}) {
   const current = task.current_run_id ? json(db.prepare('SELECT metadata FROM task_runs WHERE id = ?').get(task.current_run_id)?.metadata, {})?.supercode : null;
   if (current?.session_id === sessionId) roles.push(current.role ?? 'implementer');
   else if (engine.lastSession(db, cardId)?.session_id === sessionId) roles.push('implementer');
-  if (task.subtask_of && engine.lastSession(db, task.subtask_of)?.session_id === sessionId) roles.push('arc');
+  if (task.subtask_of) {
+    const parent = engine.getTask(db, task.subtask_of);
+    const worker = parent?.current_run_id ? engine.currentRun(db, parent.id)?.metadata?.supercode : engine.lastSession(db, task.subtask_of);
+    if (worker?.session_id === sessionId) roles.push('arc');
+  }
   return roles;
 }
 
@@ -1116,14 +1135,18 @@ function authorize(db, verb, rest, args, own) {
   // (what a session may do to a card is its workflow's: each transition's `by`)
   if ((['pause', 'resume'].includes(verb) && !rest[0]) || ['swarm', 'dispatch', 'daemon', 'serve', 'gc', 'repair', 'adopt', 'close', 'move', 'claim', 'attach-rm', 'migrate'].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"
-  const creator = completionOwnerOf(db, card.id);
-  if (creator && creator === actorOf()) return;
-  if (verb === 'comment' && isLatestReviewer(db, card.id, actorOf())) return;
-  // a card's session writes its own card and its subtasks; what it may do with them is the workflow's (`by`)
-  if (card.id !== own.id && card.subtask_of !== own.id) refuse(`writes only its own card and its subtasks, not ${card.id}`);
-  for (const other of args.ids ?? []) if (other !== own.id && engine.getTask(db, other)?.subtask_of !== own.id) refuse(`writes only its own card and its subtasks, not ${other}`);
+  if (['notify-subscribe', 'notify-unsubscribe'].includes(verb) && args['for-card']) {
+    if (args['for-card'] !== own.id) refuse(`subscribes only its own arc (--for-card ${own.id})`);
+    return;
+  }
+  const targets = verb === 'request-state' ? [...rest, ...(args.ids ?? [])] : [rest[0], ...(args.ids ?? [])];
+  for (const target of targets) {
+    const card = engine.getTask(db, target);
+    if (!card) continue;
+    if (completionOwnerOf(db, card.id) === actorOf()) continue;
+    if (verb === 'comment' && isLatestReviewer(db, card.id, actorOf())) continue;
+    if (card.id !== own.id && card.subtask_of !== own.id) refuse(`writes only its own card and its subtasks, not ${card.id}`);
+  }
 }
 
 /** Close the live sessions of a card that is not running (its worker's and its reviewers'), freeing its machine's place. */
@@ -1202,6 +1225,7 @@ async function serve(root, args = {}) {
       }
       pausedSaid = Boolean(paused(root)) && pausedSaid;
       let interval = 60;
+      let nextMailAt = Infinity;
       const began = Date.now();
       if (wakeReason) log(`dispatch wake ${wakeReason.sources.join(', ')}; event age ${began - wakeReason.at}ms`);
       wakeReason = null;
@@ -1210,6 +1234,7 @@ async function serve(root, args = {}) {
         const settings = { ...state.settings, ...override };
         interval = settings.interval;
         for (const r of await tick({ root, lanes: state.lanes, settings, params, deploymentReceipt: true })) {
+          nextMailAt = Math.min(nextMailAt, r.next_mail_at ?? Infinity);
           const said = summary(r);
           if (r.deployment) log(`runtime deployed ${r.deployment.repository}@${r.deployment.head}; workflow ${r.deployment.workflow_hash}; tick ${r.deployment.completed_at}`);
           if (!said.endsWith('nothing to do') || args.verbose) log(said);
@@ -1233,7 +1258,7 @@ async function serve(root, args = {}) {
       // the next tick is due an interval after this one began (a long tick is not followed by a full interval's wait)
       events.refresh();
       if (!stopped && !moved) {
-        wakeReason = await events.wait(Math.max(0, interval * 1000 - (Date.now() - began)));
+        wakeReason = await events.wait(Math.max(0, Math.min(interval * 1000 - (Date.now() - began), nextMailAt - Date.now())));
         // A busy event stream is coalesced to at most one tick per second.
         const remaining = 1000 - (Date.now() - began);
         if (remaining > 0 && !stopped) await new Promise(done => setTimeout(done, remaining));