@volter/supercode-orchestrator 0.4.147 → 0.4.149

package/board/ci.mjs

@@ -1,27 +1,36 @@
-// 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, statSync } 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 { branchCheckouts, checkoutOf, resolveWorkspace } from './workspace.mjs';
 
 const observations = new Map();
 const key = (board, id) => `${board.root}\0${board.slug}\0${id}`;
 const run = (program, args, cwd) => {
+  if (cwd) {
+    let directory = false;
+    try { directory = statSync(cwd).isDirectory(); } catch { /* reported below */ }
+    if (!directory) throw new Error(`Repository checkout ${cwd} is unavailable; resolve the card's declared workspace before verifying its source.`);
+  }
   const result = spawnSync(program, args, { cwd, encoding: 'utf8', timeout: 30_000, maxBuffer: 2 * 1024 * 1024 });
   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 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 = {}) {
-  const state = inspectCompletionEvidence(board, id, entry, payload);
+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,114 +46,174 @@ 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; }
-  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;
+/** The latest explicitly requested PRs are 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;
+}
+
+/** The PRs an evidence record covers: every PR of one arc review (the first is also its top-level PR). */
+export const candidatePullRequests = (ci) => ci?.prs ?? (ci?.pr ? [{ repository: ci.repository, branch: ci.branch, commit: ci.commit, source_sha: ci.source_sha ?? ci.commit, pr: ci.pr }] : []);
+const originOf = (path) => /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/.exec(run('git', ['remote', 'get-url', 'origin'], path))?.[1] ?? 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();
+
+function branchCheckout(board, id, repository) {
+  const task = board.db.prepare('SELECT t.branch_name, c.machine FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.id=?').get(id);
+  try { return checkoutOf(task?.machine, repository, task?.branch_name ?? `wt/${id}`)?.path ?? null; } catch { return null; }
+}
+
+/** Every opened PR of the arc: each open PR whose head is the card's branch or a `wt/<card id>` branch, in the
+ *  card's own repository and in every repository this machine keeps a checkout of. One review covers them all;
+ *  the caller decides the transition. */
+export function openReviewPullRequests(board, id) {
+  const own = repositoryWorkspace(board, id);
+  if (!own) 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'], own);
+  const ownRepository = originOf(own);
+  if (!ownRepository) return null;
+  const mine = (head) => head === branch || [`wt/${id}`, `wt/${id.replace(/^t_/, 't-')}`].some((prefix) => head === prefix || head.startsWith(`${prefix}-`) || head.startsWith(`${prefix}/`));
+  const prs = [];
+  for (const repository of new Set([ownRepository, ...knownRepositories()])) {
+    // Discovery is shared per repository for one minute; each selected PR/head is re-read before it authorizes a move.
+    let list = pullRequestLists.get(repository);
+    if (!list || Date.now() - list.at >= 60_000) {
+      let items = [];
+      try { items = JSON.parse(run('gh', ['pr', 'list', '--repo', repository, '--state', 'open', '--limit', '1000', '--json', 'url,headRefOid,headRefName,baseRefName,isCrossRepository'])); }
+      catch (error) { if (repository === ownRepository) throw error; } // another repository unreachable here is not this arc's
+      list = { at: Date.now(), items };
+      if (pullRequestLists.size >= 64) pullRequestLists.delete(pullRequestLists.keys().next().value);
+      pullRequestLists.set(repository, list);
     }
-    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 });
+    for (const pr of list.items) if (!pr.isCrossRepository && mine(pr.headRefName)) prs.push({ url: pr.url, head: pr.headRefOid });
+  }
+  if (!prs.length) return null;
+  return { pr: prs.map((p) => p.url), pr_head: prs.map((p) => p.head), branch };
+}
+
+/** The repositories this machine keeps a checkout of. */
+function knownRepositories() {
+  try { return [...new Set(branchCheckouts(null, '*').map((row) => row.repository))]; } catch { return []; }
+}
+
+/** Whether the arc's open PRs (`[{ url, head }]`) call for its review. Before any verdict: while some head has none.
+ *  After a verdict: only once a PR that verdict judged shows a new head. A PR that joins the arc, or one that merged or
+ *  closed, does not by itself bring the arc back: after changes are requested the next run is the implementer's. */
+export function reviewDue(board, id, prs) {
+  const unjudged = prs.some((p) => !judgedHead(board, id, p.head));
+  const last = board.db.prepare(`SELECT r.payload FROM task_events r WHERE r.task_id = ? AND r.kind = 'review_requested'
+    AND EXISTS (SELECT 1 FROM task_events v WHERE v.task_id = r.task_id AND v.kind IN ('changes_requested', 'review_pass') AND v.id > r.id)
+    ORDER BY r.id DESC LIMIT 1`).get(id);
+  if (!last) return unjudged;
+  const judged = candidatePullRequests(JSON.parse(last.payload)?.ci);
+  return unjudged && judged.some((j) => prs.some((p) => p.url === j.pr.url && p.head !== j.commit));
+}
+
+/** The verdict already recorded on `head` of the card's PR: a changes-requested or pass that answered
+ * a review request naming that head, before the next request. A head is reviewed once. */
+export function judgedHead(board, id, head) {
+  if (!head) return null;
+  return board.db.prepare(`SELECT v.id, v.kind FROM task_events r JOIN task_events v ON v.task_id = r.task_id
+    AND v.kind IN ('changes_requested', 'review_pass') AND v.id > r.id
+    AND v.id < COALESCE((SELECT MIN(n.id) FROM task_events n WHERE n.task_id = r.task_id AND n.kind = 'review_requested' AND n.id > r.id), 9223372036854775807)
+    WHERE r.task_id = ? AND r.kind = 'review_requested' AND (json_extract(r.payload, '$.ci.commit') = ?
+      OR EXISTS (SELECT 1 FROM json_each(r.payload, '$.ci.prs') p WHERE json_extract(p.value, '$.commit') = ?)) ORDER BY v.id LIMIT 1`).get(id, head, head) ?? null;
+}
+
+export function inspectCompletionEvidence(board, id, entry, payload = {}, stage = 'completion') {
+  const state = { required: false, ready: true, reason: null, phase: 'source', deployed_sha: null };
+  try {
+    if (stage === 'completion' || stage === 'acceptance') {
+      const supplied = payload.commit ?? payload.metadata?.commit;
+      if (supplied) {
+        const path = repositoryWorkspace(board, id);
+        if (!path) throw new Error('The named commit needs a resolved repository workspace.');
+        Object.assign(state, { repository: originOf(path), 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 passed = candidatePullRequests(row && JSON.parse(row.payload)?.ci);
+        const wanted = candidatePullRequests(candidate);
+        if (wanted.length !== passed.length || wanted.some((w) => !passed.some((p) => p.pr.url === w.pr.url && p.commit === w.commit))) throw new Error('The current PR heads need their independent verdict before acceptance.');
+        for (const w of wanted) {
+          const pr = JSON.parse(run('gh', ['pr', 'view', w.pr.url, '--repo', w.repository, '--json', 'state,headRefOid']));
+          if (!['OPEN', 'MERGED'].includes(pr.state) || pr.headRefOid !== w.commit) throw new Error(`The head of ${w.pr.url} 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 own = repositoryWorkspace(board, id);
+    const asked = stage === 'review_verdict' ? reviewCandidate(board, id) : null;
+    const urls = [].concat(payload.pr ?? payload.metadata?.pr ?? candidatePullRequests(asked).map((c) => c.pr.url)).filter(Boolean);
+    if (!own) {
+      if (urls.length) 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 });
+    // A verdict with no requested PR (a scratch arc) keeps its own contract. An arc's review
+    // always names every opened PR it changed, independent of completion_ci.
+    if (stage === 'review_verdict' && !asked && !urls.length) return state;
+    Object.assign(state, { required: true, ready: false });
+    if (!urls.length) throw new Error('Name each opened PR with --pr.');
+    const named = [].concat(stage === 'review_verdict'
+      ? payload.reviewed_sha ?? payload.pr_head ?? payload.commit ?? []
+      : payload.pr_head ?? payload.commit ?? payload.metadata?.pr_head ?? payload.metadata?.commit ?? []).filter(Boolean);
+    if (stage === 'request_review' && named.length !== urls.length) throw new Error('Name each PR head with --pr-head, one for each --pr, in the same order.');
+    if (stage === 'review_verdict' && !named.length) throw new Error('Name every reviewed PR head with --reviewed-sha.');
+    const prs = urls.map((url, index) => verifyPullRequest(board, id, entry, own, url, stage === 'request_review' ? named[index] : null, stage));
+    if (stage === 'request_review') {
+      // A review is asked for only while some PR has a head no verdict has judged.
+      if (!reviewDue(board, id, prs.map((p) => ({ url: p.pr.url, head: p.commit })))) throw new Error('The PRs the last verdict judged have no new head; push a new head before requesting review.');
+    } else if (asked) {
+      const requested = candidatePullRequests(asked);
+      if (requested.length !== prs.length || requested.some((r) => !prs.some((p) => p.pr.url === r.pr.url && p.commit === r.commit))) throw new Error('The verdict covers the requested PRs at their requested heads; a PR whose head moved needs a new review request.');
+      if (requested.some((r) => !named.includes(r.commit))) throw new Error('Name every reviewed PR head with --reviewed-sha.');
+      const latest = board.db.prepare('SELECT metadata FROM task_runs WHERE task_id=? ORDER BY id DESC LIMIT 1').get(id);
+      const bound = candidatePullRequests(latest && JSON.parse(latest.metadata ?? '{}')?.supercode?.review_candidate);
+      if (bound.length && (bound.length !== requested.length || bound.some((b) => !requested.some((r) => r.pr.url === b.pr.url && r.commit === b.commit)))) throw new Error('This reviewer run was launched for different PR heads.');
     }
-    state.deployed_sha = commit;
-    state.ready = true;
-    state.reason = null;
-  } catch (error) { state.reason = error.message; }
+    Object.assign(state, { ...prs[0], ready: true, reason: null, ...(prs.length > 1 ? { prs } : {}) });
+  } catch (error) { Object.assign(state, { required: true, ready: false, reason: error.message }); }
   return state;
 }
 
+/** One PR of an arc review, read from GitHub and, for a review request, from the card branch's checkout. */
+function verifyPullRequest(board, id, entry, own, url, supplied, stage) {
+  if (typeof url !== 'string' || !/^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/[1-9][0-9]*\/?$/.test(url)) throw new Error('Name the opened PR URL with --pr.');
+  const repository = new URL(url).pathname.split('/').slice(1, 3).join('/');
+  // An arc may change several repositories. A PR is read from GitHub; its pushed head is the reviewed one. The
+  // card's own checkout, and this machine's checkout of another repository on the card's branch when it keeps one,
+  // must also hold that head with nothing uncommitted.
+  const path = originOf(own) === repository ? own : branchCheckout(board, id, repository);
+  const observed = JSON.parse(run('gh', ['pr', 'view', url, '--repo', repository, '--json', 'url,number,state,headRefOid,headRefName,baseRefName,isCrossRepository']));
+  if (observed.state !== 'OPEN' || observed.isCrossRepository) throw new Error(`Source review needs an open PR from its repository (${url}).`);
+  const head = supplied ?? observed.headRefOid;
+  if (!/^[a-f0-9]{40}$/.test(head)) throw new Error('Name the full PR head commit with --pr-head (reviewer: --reviewed-sha).');
+  if (observed.headRefOid !== head) throw new Error(`The head of ${url} changed to ${observed.headRefOid}; request review of that head before recording a verdict.`);
+  const branch = observed.headRefName;
+  const mainBranch = entry.params.completion_ci?.main_branches?.[repository] ?? 'main';
+  if (branch === mainBranch || observed.baseRefName !== mainBranch) throw new Error(`${url} must propose its worktree branch to the repository main branch.`);
+  if (stage === 'request_review' && path) {
+    run('git', ['check-ref-format', '--branch', branch], path);
+    if (run('git', ['rev-parse', 'HEAD'], path) !== head) throw new Error(`The head named for ${url} must be its worktree head.`);
+    run('git', ['diff', '--quiet', 'HEAD'], path);
+    if (run('git', ['ls-files', '--others', '--exclude-standard'], path)) throw new Error(`Commit the untracked work in ${path} before requesting review.`);
+    const pushed = run('git', ['ls-remote', '--heads', 'origin', `refs/heads/${branch}`], path).split(/\s+/)[0];
+    if (pushed !== head) throw new Error(`Push the exact head of ${url} before requesting review.`);
+  }
+  return { repository, branch, commit: head, source_sha: head, pr: { url: observed.url, number: observed.number, head, branch, base: observed.baseRefName } };
+}
+
 const digest = bytes => createHash('sha256').update(bytes).digest('hex');
 /** Read the tracked workflow revision the next serve tick will load. */
 export function workflowRevision(root) {

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
@@ -47,26 +48,32 @@ Hermes Kanban's verbs, with their flags:
 supercode's own:
   init --backing sqlite|files · boards create <slug> --backing sqlite|files
       Where the board is kept: sqlite is Hermes's kanban.db (the default); files is one JSON file per card.
-  create … --machine M --subtask-of ARC --notify ADDRESS|--no-notify --no-start [--review-only]
+  create … --machine M --subtask-of ARC --notify ADDRESS|--no-notify --no-start
       With a pane lane and room, a card starts at once and answers "started" with its session; else it answers why it
       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
   create ... --adopt <session>  hold dispatch until that live session is attached
   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)...: hand over every open PR the arc changed, each at its pushed head; one review covers them all.
+  request-state <id> --state done (--reviewed-sha SHA)...: record the verdict on every 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.
 `;
 
-const MULTI = new Set(['parent', 'skill', 'worker', 'child', 'ids', 'rm']);
+const MULTI = new Set(['parent', 'skill', 'worker', 'child', 'ids', 'rm', 'pr', 'pr-head', 'reviewed-sha']);
 const FLAGS = new Set(['json', 'triage', 'no-notify', 'no-start', 'all', 'force', 'help', 'mine', 'archived', 'reclaim', 'dry-run',
-  'goal', 'no-goal', 'review-only', 'no-review-only', 'off', 'switch', 'delete', 'no-attachments', 'include-logs', 'verbose']);
+  'goal', 'no-goal', 'off', 'switch', 'delete', 'no-attachments', 'include-logs', 'verbose']);
 // flags that take every following word up to the next flag (Hermes's nargs='+')
 const GREEDY = new Set(['ids', 'rm']);
 
@@ -172,11 +179,11 @@ async function laneState(root) {
 }
 
 /** The caller's own supercode address, when it is a session supercode can reach (for its card's notices). */
+// The calling session's own address, as its actor is named: no fleet scan (a `message list` costs seconds).
 function callerAddress() {
   const id = callerSession();
   if (!id) return null;
-  const fleet = observeFleet();
-  return [...fleet.alive].find((a) => a.endsWith(`:${id}`)) ?? null;
+  return `sc:${localMachine()}:${id === process.env.CODEX_THREAD_ID ? 'codex' : 'claude-code'}:${id}`;
 }
 
 const callerName = () => process.env.HERMES_PROFILE || process.env.USER || 'user';
@@ -199,7 +206,7 @@ const cardDict = (t) => ({
   created_by: t.created_by, created_at: t.created_at, started_at: t.started_at, completed_at: t.completed_at, result: t.result,
   skills: t.skills ?? [], max_retries: t.max_retries, model_override: t.model_override, provider_override: t.provider_override,
   session_id: t.session_id, workflow_template_id: t.workflow_template_id, current_step_key: t.current_step_key,
-  machine: t.machine ?? null, subtask_of: t.subtask_of ?? null, review_only: Boolean(t.review_only),
+  machine: t.machine ?? null, subtask_of: t.subtask_of ?? null,
 });
 
 /** Hermes's durations: seconds, or 30s / 5m / 2h / 1d. */
@@ -231,7 +238,6 @@ const metadataOf = (v) => {
 export async function runWorkflow(argv) {
   const args = parse(argv);
   const [verb, ...rest] = args._;
-  if (args['review-only'] && args['no-review-only']) throw new Error('Choose review-only or no-review-only, not both.');
   if (!verb || verb === 'help' || args.help) { process.stdout.write(HELP); return 0; }
   const root = homeOf(args);
   const slug = boardOf(root, args);
@@ -274,7 +280,7 @@ export async function runWorkflow(argv) {
         const migrated = openZtrackBoard(preparing, { create: true, document: args.document, seed: { db: source.db, mapping }, init: layOut, root, slug, compatPath: paths.sqlite });
         migrated.close();
       } finally { source.close(); }
-      renameSync(`${preparing}.runtime.db`, `${paths.ztrack}.runtime.db`);
+      renameSync(`${preparing}.board.db`, `${paths.ztrack}.board.db`);
       renameSync(preparing, paths.ztrack);
       say(args, `Board migrated to ${args.document}; kanban.db is now a Hermes export`, { ok: true, backing: 'ztrack', document: args.document });
       return 0;
@@ -290,7 +296,6 @@ export async function runWorkflow(argv) {
 
     case 'create': {
       need(1, 'a title');
-      const { lanes, settings } = await laneState(root);
       const maxRetries = args['max-retries'] !== undefined ? Number(args['max-retries']) : null;
       if (maxRetries !== null && !(maxRetries >= 1)) throw new Error(`--max-retries must be >= 1 (got ${args['max-retries']}); use 1 to trip on the first failure`);
       const meta = boardMeta(root, slug);
@@ -302,22 +307,19 @@ export async function runWorkflow(argv) {
         workspace, branch: args.branch, parents: args.parent, priority: args.priority, tenant: args.tenant,
         triage: args.triage, idempotencyKey: args['idempotency-key'], maxRuntime: duration(args['max-runtime']),
         maxRetries, skills: args.skill, model: args.model, provider: args.provider, createdBy: args['created-by'] ?? callerName(),
-        noStart: Boolean(args['no-start']), adopt: args.adopt ?? null, reviewOnly: Boolean(args['review-only']),
+        noStart: Boolean(args['no-start']), adopt: args.adopt ?? null,
         every: args.every ?? null, sessionId: callerSession(), subtaskOf: args['subtask-of'] ?? null, initialStatus: args['initial-status'] ?? null,
         project: args.project ?? meta.project_id ?? null, goal: args.goal ? { maxTurns: args['goal-max-turns'] ? Number(args['goal-max-turns']) : null } : args['no-goal'] ? false : null,
       }), true);
       let answer = { id: created.id, existing: created.existing };
       if (args.adopt) {
         withBoard(b => { if (!rolesFor(b.db, created.id, sid, workflowFor(root).params).includes('manager')) throw new Error('Only the manager adopts an existing session.'); });
+        const { settings } = await laneState(root);
         const adopted = withBoard(b => adoptSession(b, created.id, args.adopt, { ttl: settings.ttl }));
         answer = { ...answer, started: true, session: adopted.address, mode: adopted.mode };
-      } else if (!args['no-start'] && !created.existing && !args['subtask-of']) {
-        const [report] = await tick({ root, lanes, settings, only: created.id, slugs: [slug] });
-        const started = report.started.find(([t]) => t === created.id);
-        const queued = report.queued.find(([t]) => t === created.id);
-        const failed = report.failed.find(([t]) => t === created.id);
-        answer = { ...answer, ...(started ? { started: true, session: started[1], mode: started[2] } : {}), ...(queued ? { started: false, waits: queued[1] } : {}), ...(failed ? { started: false, failed: failed[1] } : {}) };
       }
+      // Starting a card is the dispatcher's: this write's wake hint reaches it, and the card's
+      // thread records the start. A create never runs a dispatch tick inline.
       // the creator hears what happens from here on; a start answered above is not told twice
       const address = args['no-notify'] ? null : args.notify ?? callerAddress();
       if (address) withBoard((b) => engine.subscribe(b, created.id, address, 'creator'));
@@ -544,7 +546,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, 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 +576,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,8 +631,8 @@ 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'])) {
-          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() }));
+        if (verb === 'specify' && (args.title !== undefined || args.body !== undefined || args.workspace !== undefined || args.branch !== undefined)) {
+          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, author: args.author ?? callerAddress() ?? callerName() }));
           results.push({ id: t, specified: true, status: moved.to });
         } else if (verb === 'decompose' && args.child?.length) {
           const children = args.child.map((c) => { const [title, assignee] = c.split(/@(?=[^@]*$)/); return { title: title.trim(), assignee: assignee?.trim() || undefined }; });
@@ -711,6 +713,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 +871,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 +1110,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 +1129,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. */
@@ -1200,8 +1217,13 @@ async function serve(root, args = {}) {
         await new Promise(resolve => setTimeout(resolve, 250));
         continue;
       }
+      // A serve never ticks on code older than the installed orchestrator, also right after an
+      // installation window: its keeper starts the new one, whose board store this one does not keep.
+      const replaced = (() => { const now = installed(); return running && now && now !== running ? now : null; })();
+      if (replaced) { log(`orchestrator ${replaced} is installed (this serve runs ${running}); stopping, for its keeper to start the new one`); break; }
       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 +1232,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 +1256,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));