@volter/supercode-orchestrator 0.4.148 → 0.4.149

package/board/ci.mjs

@@ -1,14 +1,19 @@
 // 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 } from 'node:fs';
+import { readFileSync, realpathSync, writeFileSync, renameSync, statSync } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
 import { createHash } from 'node:crypto';
-import { resolveWorkspace } from './workspace.mjs';
+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();
@@ -41,13 +46,17 @@ export function withCompletionEvidence(board, id, state, fn) {
   }
 }
 
-/** The latest explicitly requested PR is the reviewer's candidate, never the deployment tip. */
+/** 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);
@@ -57,90 +66,154 @@ function repositoryWorkspace(board, id) {
 
 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;
+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'], 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 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);
+    }
+    for (const pr of list.items) if (!pr.isCrossRepository && mine(pr.headRefName)) prs.push({ url: pr.url, head: pr.headRefOid });
   }
-  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 };
+  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 {
-    const path = repositoryWorkspace(board, id);
     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.');
-        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) });
+        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 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.');
+        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;
     }
+    const own = repositoryWorkspace(board, id);
     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.');
+    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;
     }
-    // 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;
+    // 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 (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 (!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') {
-      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.');
+      // 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) {
-      if (asked.commit !== supplied || asked.pr.url !== observed.url) throw new Error('The verdict must name the requested PR and head.');
+      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 = 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.');
+      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.');
     }
-    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 });
+    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,7 +36,7 @@ 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> --pr URL --pr-head SHA [--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] [--workspace scratch|worktree:<repository>|dir:<repository>] [--branch NAME] [--all]
   decompose <id> [--child "<title>[@<profile>]"]... [--all]
@@ -48,7 +48,7 @@ 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
@@ -61,10 +61,9 @@ supercode's own:
   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 [--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-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,
@@ -72,9 +71,9 @@ supercode's own:
   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']);
 
@@ -180,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';
@@ -207,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. */
@@ -239,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);
@@ -282,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;
@@ -298,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);
@@ -310,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'));
@@ -552,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, branch: args.branch ?? null, pr: args.pr ?? null, pr_head: args['pr-head'] ?? null, reviewed_sha: args['reviewed-sha'] ?? 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': {
@@ -637,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.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() }));
+        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 }; });
@@ -1223,6 +1217,10 @@ 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;

package/board/dispatch.mjs

@@ -15,7 +15,7 @@
 // Every side effect follows a committed transition: a card is claimed before its session is launched, and a
 // subscriber's cursor moves only after its notice was delivered, so two dispatchers over one board never both
 // launch and a crash between the two steps is answered by the next tick.
-import { inspectCompletionEvidence, openReviewPullRequest, withCompletionEvidence, reviewCandidate, workflowRevision, retainWorkflowTick } from './ci.mjs';
+import { inspectCompletionEvidence, openReviewPullRequests, reviewDue, withCompletionEvidence, reviewCandidate, workflowRevision, retainWorkflowTick } from './ci.mjs';
 import { createRequire } from 'node:module';
 import { spawn as spawnChild, spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
@@ -333,13 +333,13 @@ function supervise(board, fleet, settings, report, entry, effects) {
         return;
       }
       // a run past its runtime limit (the status's `run.limits.runtime`), as Hermes times its workers out
-      if (limits.runtime && runRow && session?.wait_started_at == null && runWorkingSeconds(runRow, t) > Number(limits.runtime)) {
+      if (limits.runtime && runRow && runWorkingSeconds(runRow, t) > Number(limits.runtime)) {
         observe('timed_out', { limit_seconds: limits.runtime, error: `ran past max_runtime ${limits.runtime}s` }, 'timed_out');
         return;
       }
       if (session?.surface === 'headless') {
         // Hermes's stale check: a worker running past the limit with no heartbeat in the last hour is stopped
-        if (limits.stale && runRow && session?.wait_started_at == null && runWorkingSeconds(runRow, t) >= Number(limits.stale) && !(task.last_heartbeat_at && t - Number(task.last_heartbeat_at) < 3600)) {
+        if (limits.stale && runRow && runWorkingSeconds(runRow, t) >= Number(limits.stale) && !(task.last_heartbeat_at && t - Number(task.last_heartbeat_at) < 3600)) {
           observe('stale', { timeout_seconds: limits.stale, pid: session.pid, error: `no heartbeat after ${t - Number(runRow.started_at)}s running` }, 'reclaimed');
           return;
         }
@@ -690,7 +690,7 @@ export function closeRequested(board, report, { taskId = null, caller = null } =
         if (reading.alive) {
           const protectedNow = active.some(r => addressOf(json(r.metadata, {})?.supercode) === addressOf(session));
           if (protectedNow) throw new Error('close deferred: native session is owned by an unended run');
-          if (session.lifecycle_notice_pending) throw new Error(`close deferred: lifecycle notice ${session.lifecycle_notice_pending} has not been delivered`);
+          if (noticeHoldsClose(session, null)) throw new Error(`close deferred: lifecycle notice ${session.lifecycle_notice_pending} has not been filed`);
           stopSession(board, session);
         }
       } else {
@@ -703,7 +703,7 @@ export function closeRequested(board, report, { taskId = null, caller = null } =
       if (observed.error) throw new Error(observed.error);
       if (observed.live.has(session.pane)) {
         const pendingNotice = view(board, (db) => db.prepare("SELECT id FROM supercode_effects WHERE json_extract(effect, '$.kind')='session_notice' AND json_extract(effect, '$.runId')=? LIMIT 1").get(row.id));
-        if (pendingNotice || session.lifecycle_notice_pending) throw new Error(`close deferred: lifecycle notice ${pendingNotice?.id ?? session.lifecycle_notice_pending} has not been delivered: ${session.lifecycle_notice_error ?? 'pending'}`);
+        if (noticeHoldsClose(session, pendingNotice)) throw new Error(`close deferred: lifecycle notice ${pendingNotice?.id ?? session.lifecycle_notice_pending} has not been filed: ${session.lifecycle_notice_error ?? 'pending'}`);
         const protectedNow = view(board, (db) => db.prepare(`SELECT metadata FROM task_runs r WHERE r.ended_at IS NULL OR EXISTS (SELECT 1 FROM tasks t WHERE t.current_run_id = r.id)`).all())
           .some((r) => { const s = json(r.metadata, {})?.supercode; return s?.pane === session.pane && normalMachine(s.machine) === normalMachine(session.machine); });
         if (protectedNow) throw new Error(`close deferred: pane ${session.pane} is owned by an unended run`);
@@ -744,7 +744,6 @@ function observeIdle(board, fleet, settings, report, entry, effects) {
       if (!(entry.workflow.statuses[status]?.on?.session_idle || entry.workflow.on?.session_idle || entry.workflow.run?.on?.session_idle)) return;
       const runRow = currentRun(db, id);
       const session = runRow?.metadata?.supercode;
-      if (session?.wait_started_at != null) return;
       if (!session?.session_id || !['pane', 'native'].includes(session.surface) || session.offline_since != null) return;
       if (session.surface === 'native' && fleet.native?.get(addressOf(session))?.alive !== true) return;
       const live = fleet.sessions.find((x) => x.address === addressOf(session));
@@ -814,26 +813,31 @@ export async function sessionNotice(board, e) {
   try {
     if (!e.address) throw new Error('lifecycle notice awaits the owned launch session identity');
     receipt = await send(boardAddress(board.label), board.label, e.address, e.text, effectMessageKey(e));
-    if (!receipt.delivered) error = receipt.reason ?? 'notice queued; native transcript confirmation pending'; }
+    // A notice filed in the session's mailbox is done: the session reads its mail at its next
+    // turn, and a resumed session first. Only a notice no mailbox took is retried.
+    if (!receipt.delivered && !receipt.queued) error = receipt.reason ?? 'notice was not filed'; }
   catch (failure) { error = String(failure.message).slice(-500); }
   tx(board, (db) => {
     const session = json(db.prepare('SELECT metadata FROM task_runs WHERE id = ?').get(e.runId)?.metadata, {})?.supercode;
     if (session) setRunSession(db, e.runId, { ...session,
-      ...(error ? { lifecycle_notice_error: error } : { lifecycle_notice_error: null, ...(session.lifecycle_notice_pending === e.durableId ? { lifecycle_notice_pending: null } : {}) }) });
-    if (!error || session?.lifecycle_notice_error !== error) event(db, e.id, error ? (receipt?.queued ? 'session_notice_queued' : 'session_notice_failed') : 'session_notice_delivered', { address: e.address, verb: e.verb, source_event: e.sourceEvent, notice: e.durableId, receipt, ...(error ? { error, retry: true } : {}) }, e.runId);
+      ...(error ? { lifecycle_notice_error: error, lifecycle_notice_failures: Number(session.lifecycle_notice_failures ?? 0) + 1 }
+        : { lifecycle_notice_error: null, lifecycle_notice_failures: 0, ...(session.lifecycle_notice_pending === e.durableId ? { lifecycle_notice_pending: null } : {}) }) });
+    if (!error || session?.lifecycle_notice_error !== error) event(db, e.id, error ? 'session_notice_failed' : receipt?.delivered ? 'session_notice_delivered' : 'session_notice_queued', { address: e.address, verb: e.verb, source_event: e.sourceEvent, notice: e.durableId, receipt, ...(error ? { error, retry: true } : {}) }, e.runId);
   });
   return !error;
 }
 
+// A close waits for its run's lifecycle notice to be filed, but not past this many failed
+// attempts: an unreachable session must not hold its pane, and its slot's next launch, forever.
+const NOTICE_ATTEMPTS_BEFORE_CLOSE = 3;
+const noticeHoldsClose = (session, pending) => Boolean(pending || session.lifecycle_notice_pending)
+  && Number(session.lifecycle_notice_failures ?? 0) < NOTICE_ATTEMPTS_BEFORE_CLOSE;
+
 /** A session effect a committed move asked for: a message to the card's current actor, or closing a slot's pane. */
 export async function sessionEffect(board, e) {
   if (e.kind === 'send_to_actor') {
     const row = view(board, db => e.runId ? db.prepare('SELECT metadata FROM task_runs WHERE id=?').get(e.runId) : null);
     const session = json(row?.metadata, {})?.supercode;
-    if (session?.wait_started_at != null) {
-      tx(board, db => event(db, e.id, 'actor_notice_suppressed', { notice: e.durableId, reason: 'run is waiting', run_id: e.runId }, e.runId));
-      return true;
-    }
     const address = addressOf(session);
     let receipt;
     try {
@@ -1078,6 +1082,10 @@ function reconcileLaunches(board, fleet, report, entry, effects, settings, lanes
 
 function launchPane(board, task, runId, lane, fleet, { input = null, slot = 'worker', meta = {} } = {}) {
   const machine = normalMachine(task.machine);
+  // Whether a board session opens a terminal window on its machine is the workflow's choice, stated on every launch;
+  // no machine default decides it.
+  const window = workflowFor(board.root).params.session_window;
+  if (typeof window !== 'boolean') throw unavailable('the workflow declares no params.session_window (true or false): whether a board session opens a window on its machine is the workflow\'s choice');
   {
     const made = resolveLocalWorkspace(board, task);
     tx(board, (db) => {
@@ -1090,7 +1098,7 @@ function launchPane(board, task, runId, lane, fleet, { input = null, slot = 'wor
   if (lane.harness === 'codex' && lane.reasoning_effort) tail.push('-c', `model_reasoning_effort=${JSON.stringify(lane.reasoning_effort)}`);
   const harness = HARNESSES[lane.harness] ? lane.harness : 'claude-code';
   const how = HARNESSES[harness];
-  const base = ['open', '--new', how.program, '--detach', '--on', task.machine, '--cwd', task.workspace_path];
+  const base = ['open', '--new', how.program, '--detach', `--window=${window}`, '--on', task.machine, '--cwd', task.workspace_path];
   // the slot's last session: kept when live, resumed when lost, never another slot's (a reviewer's is its own)
   // a close its session's own command asked for is carried out first, so its pane is gone before the slot's next
   // session starts (never two processes on one session)
@@ -1778,36 +1786,43 @@ export async function plan({ root, lanes, settings, slugs = null, params = {} })
 }
 
 /** An opened PR asks for the declared review transition once the arc's tasks are closed. */
+// A task written in the card's own Tasks section that did not become a subtask holds its review too.
 async function activatePullRequestReviews(board, entry, report, effects, { only = null } = {}) {
   const candidates = view(board, db => db.prepare(`SELECT t.id FROM tasks t JOIN supercode_cards c ON c.task_id=t.id
-    WHERE c.subtask_of IS NULL AND COALESCE(c.review_only,0)=0 AND c.every IS NULL
+    WHERE c.subtask_of IS NULL AND c.every IS NULL
     AND t.workspace_kind!='scratch' ${only ? 'AND t.id=?' : ''}`).all(...(only ? [only] : [])));
   for (const { id } of candidates) {
     const eligible = db => {
       const task = getTask(db, id);
       if (!task) return false;
       const scope = scopeOf(db, board, task, { params: entry.params });
-      return task && transitionsFor(entry.workflow, statusOf(db, task), 'request_review').some(t => !t.by || t.by.includes('platform')) &&
-        !scope.card.dispatch_hold && !scope.card.paused && !scope.card.blocked_by.length &&
-        scope.card.subtasks.every(t => ['done', 'cancelled'].includes(t.status));
+      if (!transitionsFor(entry.workflow, statusOf(db, task), 'request_review').some(t => !t.by || t.by.includes('platform')) ||
+        scope.card.dispatch_hold || scope.card.paused || scope.card.blocked_by.length) return false;
+      // The card's Tasks are its subtasks; an open one holds the review, and says so.
+      const open = scope.card.subtasks.filter(t => !['done', 'cancelled'].includes(t.status));
+      return open.length ? open : true;
     };
-    if (!view(board, eligible)) continue;
+    const ready = view(board, eligible);
+    if (!ready) continue;
+    if (ready !== true) { report.queued.push([id, `review waits: ${ready.length} open task(s) in the card's Tasks: ${ready[0].id} ${ready[0].title}`]); continue; }
     try {
-      const payload = openReviewPullRequest(board, id);
-      if (!payload) continue;
+      const payload = openReviewPullRequests(board, id);
+      // The arc's open PRs ask for one review only while some head has no verdict: after changes are
+      // requested the next run is the implementer's, until a new head is pushed.
+      if (!payload || !reviewDue(board, id, payload.pr.map((url, index) => ({ url, head: payload.pr_head[index] })))) continue;
       const evidence = inspectCompletionEvidence(board, id, entry, payload, 'request_review');
       if (!evidence.ready) throw new Error(evidence.reason);
       refreshCardInputs(board, id, { commits: true });
       const moved = tx(board, db => {
         const task = getTask(db, id);
-        if (!eligible(db)) return null;
+        if (eligible(db) !== true) return null;
         return withCompletionEvidence(board, id, evidence, () => fire(db, board, entry, id, 'request_review', {
-          roles: ['platform'], payload: { ...payload, run_id: task.current_run_id, summary: `Opened PR ${payload.pr} at ${payload.pr_head}`, ci: evidence }
+          roles: ['platform'], payload: { ...payload, run_id: task.current_run_id, summary: `Opened ${payload.pr.map((url, index) => `${url} at ${payload.pr_head[index]}`).join(', ')}`, ci: evidence }
         }));
       });
       if (moved) {
         effects.push(...moved.effects);
-        (report.review_requested ??= []).push({ id, pr: payload.pr, head: payload.pr_head });
+        (report.review_requested ??= []).push({ id, prs: payload.pr, heads: payload.pr_head });
       }
     } catch (error) { report.queued.push([id, `PR review waits: ${error.message}`]); }
   }