@volter/supercode-orchestrator 0.5.218 → 0.5.220

package/board/ci.mjs

@@ -5,7 +5,7 @@ import { readFileSync, realpathSync, writeFileSync, renameSync, statSync } from
 import { dirname, join, relative } from 'node:path';
 import { createHash } from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { branchCheckouts, checkoutOf, isLocalWorkspace, resolveWorkspace, plainWorkspace } from './workspace.mjs';
+import { branchCheckouts, checkoutOf, isLocalWorkspace, isWorkspacePath, resolveWorkspace, plainWorkspace } from './workspace.mjs';
 import { noteStep } from '@volter/supercode-harness-sdk/slow-log';
 import { githubFetch, githubDiscovery } from './github-rest.mjs';
 import { cardHandleOf } from './store.mjs';
@@ -189,7 +189,8 @@ async function githubUncached(path, all = false, { purpose = 'validation' } = {}
       throw Object.assign(new Error(`GitHub: ${result.error.trim().slice(-500)}${nativeCode ? ` (${nativeCode})` : ''}`, { cause: result.cause }), result.rateLimit
         ? { code: 'github_rate_limited', status: result.status, retry_at: result.rateLimit.retryAt, deferred: true }
         : result.code ? { code: result.code, deferred: result.code === 'github_read_admission_full' }
-        : result.cause?.code ? { code: result.cause.code, deferred: result.cause.code === 'GITHUB_BUDGET' } : {});
+        : result.cause?.code ? { code: result.cause.code, deferred: result.cause.code === 'GITHUB_BUDGET' }
+        : result.status ? { status: result.status } : {});
     }
     return result.body;
 }
@@ -295,13 +296,19 @@ export const candidatePullRequests = (ci) => ci?.prs ?? (ci?.pr ? [{ repository:
 // The repository a checkout declares (remote.origin.url), not where a URL rewrite sends its transport.
 const originOf = async (path) => /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/.exec(await run('git', ['config', '--get', 'remote.origin.url'], path))?.[1] ?? null;
 
-/** The card's checkout as its machine answers for it (path, repository, branch), and whether it is on this machine:
- *  git runs only in a checkout here, and another machine's is known by what its door said. */
-async function repositoryWorkspace(board, id) {
+/** The card whose workspace is the card's: the card itself, or a scratch subtask's arc; null for a scratch arc. */
+function workspaceOwner(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 owner = task?.workspace_kind === 'scratch' ? parent : task;
-  if (!owner || owner.workspace_kind === 'scratch') return null;
+  return !owner || owner.workspace_kind === 'scratch' ? null : owner;
+}
+
+/** The card's checkout as its machine answers for it (path, repository, branch), and whether it is on this machine:
+ *  git runs only in a checkout here, and another machine's is known by what its door said. */
+async function repositoryWorkspace(board, id) {
+  const owner = workspaceOwner(board, id);
+  if (!owner) return null;
   // the worktree's folder, when it is still to be made, is named for its card (workspace.mjs worktreeFolder)
   const workspace = { ...owner, handle: cardHandleOf(board, owner.id) };
   const here = isLocalWorkspace(workspace);
@@ -380,7 +387,7 @@ function checkoutPresent(path) {
 /** The sibling checkouts an arc registered: each subtask (and the card itself) that declares a repository
  *  workspace and a branch, e.g. `create "<what>" --subtask-of <arc> --workspace worktree:<repository> --branch <name>`.
  *  Their PRs are the arc's whatever the branch is named. */
-function registeredBranches(board, id) {
+function registeredBranches(board, id, sources = arcSources(board.db, id)) {
   // Keep the two keys in their own lookups. An OR across the joined tables makes SQLite scan every task.
   // Exclude the arc from the second arm even if a malformed record names itself as its subtask.
   const rows = board.db.prepare(`SELECT t.branch_name, t.workspace_kind, c.workspace_anchor FROM tasks t JOIN supercode_cards c ON c.task_id=t.id
@@ -392,8 +399,8 @@ function registeredBranches(board, id) {
     if (!row.workspace_anchor || /^(\/|~|[A-Za-z]:[\\/])/.test(row.workspace_anchor)) continue;
     out.push({ repository: row.workspace_anchor.replace(/^github\.com\//i, '').replace(/\.git$/, ''), branch: row.branch_name });
   }
-  // and each repository and branch the arc declared as its own (arcSources)
-  for (const declared of arcSources(board.db, id)) if (!out.some((r) => r.repository.toLowerCase() === declared.repository.toLowerCase() && r.branch === declared.branch)) out.push(declared);
+  // and each repository and branch the arc declared as its own (arcSources, or the declaration about to replace it)
+  for (const declared of sources) if (!out.some((r) => r.repository.toLowerCase() === declared.repository.toLowerCase() && r.branch === declared.branch)) out.push(declared);
   return out;
 }
 
@@ -407,6 +414,30 @@ export function arcSources(db, id) {
   return declared.filter((b) => typeof b?.repository === 'string' && typeof b?.branch === 'string').map((b) => ({ repository: b.repository, branch: b.branch }));
 }
 
+/** The arc's repositories, the only ones its `--pr` declarations may name (ADR 0003): the card's own workspace's and each
+ *  registered branch's (its tasks' and its `--source` declaration; `sources`, a declaration about to replace that one,
+ *  stands in for it). Answers them lower-cased, with the workspace and registered branches they were read from. */
+export async function arcRepositories(board, id, sources = arcSources(board.db, id)) {
+  const own = await repositoryWorkspace(board, id);
+  const registered = registeredBranches(board, id, sources).map(r => ({ ...r, repository: r.repository.toLowerCase() }));
+  const ownRepository = (own?.repository ?? (own?.here ? await originOf(own.path) : null))?.toLowerCase();
+  return { own, registered, ownRepository, repositories: new Set([ownRepository, ...registered.map(r => r.repository)].filter(Boolean)) };
+}
+
+/** The arc's repositories the board's own records name, read without asking any machine or git: each registered branch's
+ *  and the card's workspace anchor when it names a repository (not a path). A subset of arcRepositories, so a URL in it
+ *  needs no workspace resolved (engine.comment); one outside it is checked against arcRepositories. */
+export function recordedArcRepositories(board, id, sources = arcSources(board.db, id)) {
+  const owner = workspaceOwner(board, id), anchor = owner?.workspace_anchor;
+  let anchored = null;
+  try { anchored = anchor && !isWorkspacePath(anchor) ? plainWorkspace(owner.workspace_kind, anchor).repository : null; } catch { /* an unreadable anchor is resolved by its machine */ }
+  return new Set([anchored, ...registeredBranches(board, id, sources).map(r => r.repository)].filter(Boolean).map(r => r.toLowerCase()));
+}
+
+/** Each PR URL whose repository is not one of `repositories` (arcRepositories), with that repository as the URL names it. */
+export const outsideArcRepositories = (urls, repositories) => urls.map(url => ({ url, repository: repositoryOf(url) }))
+  .filter(source => !repositories.has(source.repository.toLowerCase()));
+
 /** Legacy branches carry the globally unique native id. Keyed handles are local to a board, so their branches
  *  count only by exact recorded repository/branch identity (openReviewPullRequests), never by a handle prefix. */
 export const namedWorkBranch = (id, head) => [`wt/${id}`, `wt/${id.replace(/^t_/, 't-')}`].some((prefix) => head === prefix || head.startsWith(`${prefix}-`) || head.startsWith(`${prefix}/`));
@@ -440,12 +471,25 @@ export async function openReviewPullRequests(board, id, { fresh = false, checkWo
 }
 
 async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces = false, refuseStacked = false, repositories = [], strict = false } = {}, scope = null) {
-  const own = await repositoryWorkspace(board, id);
-  const registered = registeredBranches(board, id).map(r => ({ ...r, repository: r.repository.toLowerCase() }));
-  if (!own && !registered.length) return null;
+  const { own, registered, ownRepository, repositories: arcScope } = await arcRepositories(board, id);
+  // A source declaration (an implementer's or manager's card comment, engine.comment) adds merged or moved PRs that
+  // discovery cannot see; it never hides what discovery found. Its PRs are bounded by the arc's repositories (the card's
+  // workspace, its declared sources, its tasks' registered branches) and, here, each repository where the board finds the
+  // arc's own work branch (a wt/<card> PR in a sibling repository, discovered or declared). engine.comment refuses a PR
+  // outside the first three when it is declared; a declaration still outside all of them (stored before that refusal,
+  // or left outside later by a --source change, a cancelled or retargeted task, or a changed workspace) is refused here,
+  // by every review request, verdict and acceptance, as `undeclared`, naming the PR and its repository, never dropped
+  // (volter-ai/volter#134 left four t_ef2aa6ce review requests with no word). A PR the review already includes is never refused.
+  const declaration = board.db.prepare("SELECT payload FROM task_events WHERE task_id=? AND kind='commented' AND json_type(payload,'$.sources')='array' ORDER BY id DESC LIMIT 1").get(id);
+  const declared = (declaration ? JSON.parse(declaration.payload).sources : []).filter(source => typeof source?.url === 'string');
+  const undeclared = (outside) => refusalOf(outside.map(({ url, repository }) => refused('undeclared', url, `${url} is declared as a source of ${id}, but ${repository} is not one of the arc's repositories (its workspace, its declared sources, its tasks', or one holding its wt/${id} branch), so a declaration cannot name it: declare the repository on the arc: comment ${id} "<why>" --source ${repository}:<branch> (with every other source the arc changes), or declare the arc's PRs again without it (--pr none declares none).`)));
+  // A card with no repository of its own and none registered (scratch) has no discovery: every declared PR is outside.
+  if (!ownRepository && !registered.length) {
+    const outside = outsideArcRepositories(declared.map(source => source.url), arcScope);
+    if (outside.length) throw undeclared(outside);
+    return null;
+  }
   const task = board.db.prepare('SELECT branch_name FROM tasks WHERE id=?').get(id);
-  const ownRepository = (own?.repository ?? (own?.here ? await originOf(own.path) : null))?.toLowerCase();
-  if (!ownRepository && !registered.length) return null;
   const current = task?.branch_name ? null : own?.branch ?? (own?.here ? await run('git', ['branch', '--show-current'], own.path) : null);
   let branch = task?.branch_name ?? (current || null);
   const mine = (repository, head) => (repository === ownRepository && head === branch) || namedWorkBranch(id, head)
@@ -462,7 +506,7 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
   const reviewRepositories = new Set([ownRepository, ...registered.map(r => r.repository), ...requested, ...repositories]
     .filter(Boolean).map(r => r.toLowerCase()));
   const answered = answeredChanges(board, id);
-  const stacked = [];
+  const stacked = [], workRepositories = new Set();
   const groups = await readTogether(repositoriesToRead, async repository => {
     const prs = [];
     const hasWorkBranches = repository === ownRepository || registered.some(r => r.repository === repository);
@@ -485,6 +529,8 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
     // Include excluded drafts/other bases in the fresh scope: becoming ready
     // must not let a sibling source escape the complete-set check.
     if (list.items.some(pr => mine(repository, pr.headRefName))) reviewRepositories.add(repository);
+    // A repository holding the arc's own work branch is the arc's: a declared PR there is in scope.
+    if (list.items.some(pr => !pr.isCrossRepository && mine(repository, pr.headRefName))) workRepositories.add(repository);
     // The repository's default branch is not a work branch, declared or checked out (a card working in a `dir` on main).
     if (repository === ownRepository && branch) {
       if (branch === list.defaultBranch) branch = null;
@@ -516,14 +562,29 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
     return prs;
   });
   const prs = groups.flat();
-  // A source declaration (an implementer's or manager's card comment, engine.comment) adds merged or moved PRs that
-  // discovery cannot see; it never hides what discovery found. Only repositories the card's workspace, its declared
-  // sources or its tasks' registered branches name count, and each declared PR is followed at its current head (GitHub's), never pinned to the
-  // declared one, so a push after the declaration is reviewed instead of failing every tick.
-  const declaration = board.db.prepare("SELECT payload FROM task_events WHERE task_id=? AND kind='commented' AND json_type(payload,'$.sources')='array' ORDER BY id DESC LIMIT 1").get(id);
-  const declaredRepositories = new Set([ownRepository, ...registered.map((r) => r.repository)].filter(Boolean).map((r) => r.toLowerCase()));
-  const sources = (declaration ? JSON.parse(declaration.payload).sources : []).filter(source => declaredRepositories.has(repositoryOf(source.url).toLowerCase()) && !prs.some(known => known.url === source.url));
-  for (const pr of await readTogether(sources, source => fresh ? readPullRequest(source.url) : discoverPullRequest(source.url))) {
+  // Each declared PR discovery did not find is read and followed at its current head (GitHub's), never pinned to the
+  // declared one, so a push after the declaration is reviewed instead of failing every tick; one from a fork, closed, or
+  // an open draft is left out. One outside the arc's repositories is in scope only when it is itself on the arc's work
+  // branch in its own repository. One GitHub says is absent or denied (404, 403, 410) stays outside and is refused
+  // with the rest, unless another declared PR brings its repository into scope, where its read error is thrown as it
+  // is. Any other read failure (5xx, reset, timeout) is thrown as a transient failure, never refused as undeclared.
+  const inScope = new Set([...arcScope, ...workRepositories]);
+  const sources = declared.filter(source => !prs.some(known => known.url === source.url));
+  const read = await readTogether(sources, async source => {
+    const reading = fresh ? readPullRequest(source.url) : discoverPullRequest(source.url);
+    if (inScope.has(repositoryOf(source.url).toLowerCase())) return reading;
+    try { return await reading; } catch (error) {
+      if (error?.deferred || ![403, 404, 410].includes(error?.status)) throw error;
+      return { unread: error };
+    }
+  });
+  read.forEach((pr, i) => { if (!pr.unread && !pr.isCrossRepository && mine(repositoryOf(sources[i].url).toLowerCase(), pr.headRefName)) inScope.add(repositoryOf(sources[i].url).toLowerCase()); });
+  const outside = outsideArcRepositories(sources.map(source => source.url), inScope);
+  if (outside.length) throw undeclared(outside);
+  // Every source left unread is now in scope: its own read error is the answer.
+  const unread = read.find(pr => pr.unread);
+  if (unread) throw unread.unread;
+  for (const pr of read) {
     if (pr.isCrossRepository || !['OPEN', 'MERGED'].includes(pr.state) || (pr.state === 'OPEN' && pr.isDraft)) continue;
     if (!prs.some((known) => known.url === pr.url)) prs.push({ url: pr.url, head: pr.headRefOid, observed: pr });
   }

package/board/cli.mjs

@@ -116,7 +116,7 @@ The board's verbs, with their flags:
   set <id> <assignee|machine|model|every|reviewer> <value|none> [--provider] [--ids ...]   assign <id> <profile|none>   set-model <id> [model] [--provider]   set-goal <id>... [--goal-max-turns N] [--off]
   reassign <id> --agent AGENT [--role implementer]   (moves a card role's assignment to another agent; sessions keep their identity)
   claim <id> [--ttl]   reclaim <id> [--reason]   heartbeat <id> [--note] [--until <time|30m>]   link|unlink <parent> <child>
-  comment <id> (<text> | --file PATH|-) [--author] [--max-len] [(--pr URL --pr-head SHA)...] [--source owner/repo:branch]...   attach <id> <path> [--name] [--content-type]   attachments <id>   attach-rm <n>
+  comment <id> (<text> | --file PATH|-) [--author] [--max-len] [(--pr URL --pr-head SHA)... | --pr none] [--source owner/repo:branch]...   attach <id> <path> [--name] [--content-type]   attachments <id>   attach-rm <n>
   attachment-read <id> <attachment-id> [--offset N --length N --version V]   bounded base64/metadata JSON, including through --at
   complete <id>... [--result] [--summary] [--metadata JSON] [--commit SHA]   edit <id> --result [--summary] [--metadata]
   finish <id> --result TEXT   (when declared: end your completed attempt; the board selects review)
@@ -164,7 +164,7 @@ And:
 
   specify <id> --workspace dir:<repository> --branch NAME: the manager retargets a stopped card without replacing its history.
   specify <id> --workspace … --machine M: declares the workspace on M and moves the card there, never asking the machine it leaves.
-  comment <id> TEXT (--pr URL --pr-head SHA)...: the card's implementer or the manager adds PRs (including merged ones) to the arc's discovered source set, in the arc's repositories (its workspace, its declared sources, its tasks'), each followed at its current head; the latest declaration replaces the previous one. This records evidence; only the board starts its review.
+  comment <id> TEXT (--pr URL --pr-head SHA)...: the card's implementer or the manager adds PRs (including merged ones) to the arc's discovered source set, in the arc's repositories (its workspace, its declared sources, its tasks'), each followed at its current head; the latest declaration replaces the previous one, and --pr none alone replaces it with none. This records evidence; only the board starts its review.
   comment <arc> TEXT --source owner/repo:branch...: the arc's implementer or the manager declares every repository and branch the arc changes, on the arc itself; its review discovers PRs from them and accepts --pr declarations in them, with no task registered there. The latest declaration is the complete set.
   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.
@@ -1962,6 +1962,7 @@ export async function serveBoardGeneration(root, args = {}, argv = ['serve', '--
           say('activation: registered with the machine daemon; the first clean round follows');
           // The loop's next admitted round supplies the serving receipt, also for a resumed predecessor.
           generationServingDue = true;
+          tellOwner({ type: 'routable', pid: process.pid, boards: listBoards(root) });
           wakeGeneration();
         }
       }
@@ -2124,6 +2125,9 @@ async function serve(root, args = {}) {
   await registerOwner();
   onLocalReopen(registerOwner);
   activationSaid('registered with the machine daemon');
+  // Its writer epoch taken, work admitted and the home registered, this generation answers verbs: its owner routes
+  // public requests to it now, and its first clean round below gates the activation, never the routing.
+  if (inBoardGeneration && generationServingDue) tellOwner({ type: 'routable', pid: process.pid, boards: listBoards(root) });
   let listenerRecords = {}, listenerReloading = null, listenerReloadDue = false, listenerReading = null;
   const listenerErrors = new Set();
   const listenerLog = text => { if (!listenerErrors.has(text)) { if (listenerErrors.size >= 128) listenerErrors.clear(); listenerErrors.add(text); log(text); } };

package/board/dispatch.mjs

@@ -52,11 +52,11 @@ import { basename, dirname, join } from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { view, boardCopyOf, boardKey, boardPath, cardHandleOf, readableIdOf, briefPath, claimer, claimHolds, copyRefusal, event, json, listBoards, logsDir, newClaim, now, NOTICE_RUN_IDS, openBoard, openBoardSnapshot, pendingLaunches, sessionBound, setActor, storageFault, tx } from './store.mjs';
-import { doors, fire, loadWorkflow, resumeOf, runSpec, runWorkingSeconds, requestSessionClose, retireSupersededRuns, refreshCardInputs, refreshRelationAnswers, transitionsFor, scopeOf, statusOf, projectStatus, storedStatus, templateValue, workflowFor } from './workflow.mjs';
+import { doors, fire, loadWorkflow, resumeOf, runSpec, runWorkingSeconds, requestSessionClose, retireSupersededRuns, refreshCardInputs, refreshRelationAnswers, unrelayedStateAnswers, transitionsFor, scopeOf, statusOf, projectStatus, storedStatus, templateValue, workflowFor } from './workflow.mjs';
 import { checkWorkspace, assertWorkspaceOwner, notePresence, resolveWorkspace } from './workspace.mjs';
 import { capacity, dispatched, executionHost, harnessDefaults, holdings } from './capacity.mjs';
 import { evaluate, holds, render } from './expr.mjs';
-import { identifyNotice, numbered } from './notices.mjs';
+import { cardNumber, identifyNotice, numbered } from './notices.mjs';
 import { noticeReceiptsInTurns, noticeKey, requireNoticeBasis, noticeWriterBasis } from './notice-receipts.mjs';
 import { pendingRequestMail } from './request-mail.mjs';
 import {
@@ -1939,8 +1939,10 @@ 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 (view(board, db => detachedSession(db, session))) return true;
-    const address = addressOf(session);
+    // an effect may name its recipient (a state request's requester, settleStateRequestAnswers); otherwise it is the
+    // run's actor. A recipient in a person's custody is filed nothing, as the run's own detached session is not.
+    if (view(board, db => e.address ? Boolean(personCustody(db, e.address)) || (addressOf(session) === e.address && detachedSession(db, session)) : detachedSession(db, session))) return true;
+    const address = e.address ?? addressOf(session);
     if (!address) throw new Error('actor session identity unavailable');
     // filed in the actor's mailbox, which delivers it
     const card = view(board, (db) => getTask(db, e.id));
@@ -3171,6 +3173,55 @@ function ensureSubscriptions(board, entry) {
   });
 }
 
+/**
+ * Whether the session at `address` is known to have ended: one of card `taskId`'s runs carried it, and no run (of any
+ * card) carrying it is unended or keeps it open after its run (retain_after_run, not since closed or handed on). One
+ * session carries many runs and a kept session goes on asking after its run ends, so an ended run alone says nothing.
+ */
+function sessionEnded(db, taskId, address) {
+  const runs = db.prepare("SELECT task_id, ended_at, metadata FROM task_runs WHERE json_extract(metadata, '$.supercode.address') = ? OR json_extract(metadata, '$.supercode.session_id') = ?")
+    .all(address, address.split(':').at(-1)).map((r) => ({ ...r, session: json(r.metadata, {})?.supercode })).filter((r) => addressOf(r.session) === address);
+  return runs.some((r) => r.task_id === taskId) && !runs.some((r) => r.ended_at == null
+    || (r.session.retain_after_run && !r.session.close_requested && !r.session.closed_at && !r.session.close_transferred_to));
+}
+
+/**
+ * The manager's answer to a state request (its reply to the board's "State requests" question), granted or denied,
+ * reaches the session that asked and stays on the card. A denial changes no card state, so before this the answer was
+ * read from the mailbox only into the stall guard (card.state_request) and the requester went on reading its request
+ * as pending. Each answer is recorded once as a `state_request_answered` event (the request, the answering message,
+ * who sent it, its text and the state act the card took after the request, if any) and told to the requester, or the
+ * card's live session (its current, unended run) when the request names none or the requester's session is known to
+ * have ended (sessionEnded: run N asked and died, and the board relaunched the card as N+1), as an actor notice
+ * through the effect queue (sessionEffect files it in that mailbox under a fixed key), queued in the transaction that
+ * records it so neither lands without the other. A closed card with no live session gets the record alone. An answer
+ * older than the workflow's notice_max_age_seconds, or whose age is unknown (no limit set, no reply time read), is
+ * recorded, not mailed.
+ */
+function settleStateRequestAnswers(board, entry, report) {
+  const maxAge = Number(entry?.params?.notice_max_age_seconds) || null;
+  const self = boardAddress(board.label);
+  tx(board, (db) => {
+    for (const a of unrelayedStateAnswers(db, entry?.params?.notice_max_age_seconds)) {
+      const outcome = a.act ? `the card took ${a.act} after the request` : 'the card\'s state is unchanged';
+      const id = event(db, a.task_id, 'state_request_answered', { request_event: a.request_event, state: a.state, requester: a.requester,
+        question: a.question, answer: a.answer, answered_by: a.answered_by, act: a.act, outcome, decision: String(a.text ?? '').slice(0, 4000) }, a.run_id);
+      (report.state_answers ??= []).push([a.task_id, a.answer]);
+      if (!maxAge || !Number(a.answered_at_ms) || Date.now() - Number(a.answered_at_ms) > maxAge * 1000) continue;
+      const run = a.run_id ? db.prepare('SELECT ended_at, metadata FROM task_runs WHERE id = ?').get(a.run_id) : null;
+      const live = run && run.ended_at == null ? addressOf(json(run.metadata, {})?.supercode) : null;
+      const requester = String(a.requester ?? '').startsWith('sc:') ? a.requester : null;
+      const to = requester && (requester === live || !sessionEnded(db, a.task_id, requester)) ? requester : live;
+      if (!to || to === self || to === a.answered_by) continue;
+      const text = `${a.task_id}: your request-state ${a.state ?? ''} (${a.question}) was answered by ${a.answered_by ?? 'the manager'} in ${a.answer}; ${outcome}.\n${String(a.text ?? '').trim()}\nRead the card: supercode workflow show ${a.task_id} --root ${board.root}`;
+      const effect = { kind: 'send_to_actor', id: a.task_id, runId: a.run_id, address: to, sourceEvent: id, verb: 'state_request_answered',
+        messageKey: `board-state-answer-${a.task_id}-${id}`,
+        text: identifyNotice({ id, kind: 'state_request_answered', run_id: a.run_id, created_at: now() }, numbered(boardKey(board.root, board.slug), cardNumber(db, a.task_id), text)) };
+      db.prepare('INSERT INTO supercode_effects (effect) VALUES (?)').run(JSON.stringify(effect));
+    }
+  });
+}
+
 /** The event kinds an audience hears (the workflow's notify). */
 const heardBy = (entry, audience) => Object.keys(entry.workflow.notify?.[audience] ?? {});
 
@@ -4040,7 +4091,7 @@ export async function tick({ root, lanes, settings, only = null, slugs = null, d
       const phase = (name) => { const t = Date.now(); report.ms[name] = t - mark; mark = t; };
 
       await readMailbox(board, boardAddress(board.label), report); phase('mailbox');
-      await refreshRelationAnswers(board); phase('answers');
+      await refreshRelationAnswers(board); settleStateRequestAnswers(board, entry, report); phase('answers');
       const effects = [];
       await completeAdoptions(board, fleet, settings, report, lanes); await reconnectContinuedSessions(board, fleet, entry, report); await reconcileLaunches(board, fleet, report, entry, effects, settings, lanes); await recordBounces(board, fleet, entry, report); await supervise(board, fleet, settings, report, entry, effects); queueEffects(board, effects.splice(0)); await closeRequested(board, report, { ttl: settings.ttl, fleet }); phase('supervise');
       report.unsettled = [];

package/board/engine.mjs

@@ -19,7 +19,7 @@ import { checkWorkspace, assertWorkspaceOwner, declareWorkspace, isLocalWorkspac
 import { DatabaseSync } from 'node:sqlite';
 import { CARD_VISIBILITY_SQL } from './visibility.mjs';
 import { view, actorOf, principalOf, boardKey, cardBranch, cardHandle, CARD_NUMBERS, claimer, contention, event, json, newTaskId, now, retryContention, tx } from './store.mjs';
-import { assertSourceReceipt, completionPhase, inspectCompletionEvidence, observeCompletionEvidence, withCompletionEvidence } from './ci.mjs';
+import { arcRepositories, arcSources, assertSourceReceipt, completionPhase, outsideArcRepositories, inspectCompletionEvidence, observeCompletionEvidence, recordedArcRepositories, withCompletionEvidence } from './ci.mjs';
 import { addDependency, retireSupersededRuns, refreshCardInputs, requestSessionClose, reviewerOf, eventTo, fire, validateEvent, loadWorkflow, setStatus, settle, startNew, statusOf, runEvent, workflowFor } from './workflow.mjs';
 import { refuseCredentialDump, withheldIfDump } from './credential-guard.mjs';
 import { AGENT_KIND_LIST, compactCardAgentEvents } from './published.mjs';
@@ -803,14 +803,31 @@ export async function comment(board, id, author, body, { roles, pr = null, pr_he
   }
   if (pr != null || pr_head != null) {
     const urls = [].concat(pr ?? []), heads = [].concat(pr_head ?? []);
-    if (!urls.length || urls.length !== heads.length) throw new Error('Record every PR with --pr URL --pr-head SHA, one full head per URL.');
+    // `--pr none` alone declares no PR: the arc's declaration becomes the empty set (a stored declaration no longer in
+    // the arc's repositories is cleared this way when no PR in them remains to declare in its place).
+    const none = urls.length === 1 && urls[0] === 'none' && !heads.length;
+    if (!none && (!urls.length || urls.length !== heads.length)) throw new Error('Record every PR with --pr URL --pr-head SHA, one full head per URL, or declare none with --pr none alone.');
     if (new Set(urls).size !== urls.length) throw new Error('Record each PR once.');
-    sources = urls.map((url, i) => {
+    sources = none ? [] : urls.map((url, i) => {
       if (!/^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/[1-9][0-9]*\/?$/.test(url) || !/^[a-f0-9]{40}$/.test(heads[i])) throw new Error('A source declaration needs a GitHub PR URL and its full head SHA.');
       return { url: url.replace(/\/$/, ''), head: heads[i] };
     });
     // Only the card's own implementer or the board's manager declares its sources; the author text is not identity.
     if (!(roles ?? callerRoles(board.db, id)).some((role) => role === 'implementer' || role === 'manager')) throw new Error(`Only ${id}'s implementer or the manager records its PR sources.`);
+    // A declared PR is in one of the arc's repositories (its workspace, its declared sources, its tasks'; a `--source`
+    // in this same comment replaces the arc's declared sources): the review reads no other, so one outside them is
+    // refused here and nothing is stored, never kept to be dropped from every review request (t_ef2aa6ce). The board's
+    // own records are read first; the workspace is resolved (its daemon, its machine, git) only for a URL still outside.
+    const declaredSources = branches ?? arcSources(board.db, id);
+    const urlsOf = (list) => list.map((s) => s.url);
+    let outside = outsideArcRepositories(urlsOf(sources), recordedArcRepositories(board, id, declaredSources));
+    if (outside.length) {
+      let repositories;
+      try { ({ repositories } = await arcRepositories(board, id, declaredSources)); }
+      catch (error) { throw new Error(`${id}'s workspace could not be read to check the repository of ${outside.map((o) => o.url).join(', ')} (a --pr declaration is checked against the arc's repositories): ${error.message}. Nothing was recorded.`); }
+      outside = outsideArcRepositories(urlsOf(outside), repositories);
+    }
+    if (outside.length) throw new Error(outside.map(({ url, repository }) => `${url} is in ${repository}, which is not one of ${id}'s repositories (its workspace, its declared sources, its tasks'): declare ${repository} first with comment ${id} "<why>" --source ${repository}:<branch> (with every other source the arc changes), then record its PRs. Nothing was recorded.`).join(' '));
   }
   const result = await act(board, id, 'comment', { roles, payload: { author: author.trim(), body, ...(sources ? { sources } : {}), ...(branches ? { branches } : {}) } });
   return result.commentId;

package/board/generation-owner.mjs

@@ -128,13 +128,26 @@ export async function serveBoardOwner(root, args) {
     const timer = setTimeout(() => generation.process.kill('SIGKILL'), 2000);
     try { await generation.exited; } finally { clearTimeout(timer); }
   };
+  // Whether every request already sent to a generation was answered (or the generation ended) within the bound.
+  // New requests are held at the door meanwhile, so nothing more is sent to it.
+  const drained = (generation, ms = 8000) => {
+    let timer;
+    return Promise.race([new Promise(done => {
+      const inspect = () => { if (!generation.calls.size || generation.ended) done(true); else waiting.add(inspect); }; inspect();
+    }), new Promise(done => { timer = setTimeout(() => done(false), ms); })]).finally(() => clearTimeout(timer));
+  };
   const activate = async generation => {
     if (stopping || generation.ended) throw new Error('cannot activate an ended board generation');
     record(generation);
-    generation.events.delete('serving');
+    generation.events.delete('routable'); generation.events.delete('serving');
     generation.tell({ type: 'activate' });
     log(`generation ${generation.id} (pid ${generation.process.pid}) activates`);
-    const serving = await generation.wait('serving');
+    // Public requests are routed once the successor holds its writer and answers its inventory and stats. Its first
+    // clean round, a full tick that reads other machines' doors, gates this activation's answer (and so the
+    // transaction's commit), never the routing. A generation that never says it is routable is routed when it serves.
+    const routable = generation.wait('routable'), served = generation.wait('serving');
+    routable.catch(() => {}); served.catch(() => {});
+    const serving = await Promise.any([routable, served]).catch(error => { throw error.errors?.at(-1) ?? error; });
     const read = async argv => {
       const proof = await generation.ask(JSON.stringify({ v: 1, argv, cwd: root,
         facts: { SUPERCODE_CONTEXT: process.env.SUPERCODE_CONTEXT || 'local' } }), 8000);
@@ -154,6 +167,19 @@ export async function serveBoardOwner(root, args) {
     if (generation.health) holdOwnerHealth(generation.health.boards, generation.health.round);
     for (const [at, value] of generation.workflows) holdWorkflow(at, value);
     changed();
+    log(`generation ${generation.id} routed (pid ${generation.process.pid})`);
+    // A first round that is not clean ends this activation. Requests are held from here, and those already sent to the
+    // child are answered by it, within the predecessor's drain bound, before the caller's rollback ends it.
+    try { await served; }
+    catch (error) {
+      if (routing === generation) {
+        routing = null; changed();
+        const owed = generation.calls.size;
+        if (!await drained(generation)) log(`generation ${generation.id}: ${generation.calls.size} of ${owed} routed request(s) unanswered 8 s after its first round failed; their outcome is unknown`);
+        else log(`generation ${generation.id}: first round not clean; requests held, and ${owed} routed request(s) in flight answered before it is ended`);
+      }
+      throw error;
+    }
     log(`generation ${generation.id} serves (pid ${generation.process.pid})`);
     return generation;
   };
@@ -205,11 +231,7 @@ export async function serveBoardOwner(root, args) {
       };
       requireCandidate();
       routing = null;
-      let drainTimer;
-      try { await Promise.race([new Promise(done => {
-        const inspect = () => { if (!held.predecessor.calls.size || held.predecessor.ended) done(); else waiting.add(inspect); }; inspect();
-      }), new Promise((_, reject) => { drainTimer = setTimeout(() => reject(new Error('board requests did not drain; predecessor retained')), 8000); })]); }
-      finally { clearTimeout(drainTimer); }
+      if (!await drained(held.predecessor)) throw new Error('board requests did not drain; predecessor retained');
       requireCandidate();
       held.phase = 'parking';
       held.predecessor.events.delete('parked'); held.predecessor.tell({ type: 'park' });

package/board/github-rest.mjs

@@ -82,7 +82,7 @@ export async function githubDiscovery(identity, ttl, read, { fresh = false, ttlO
       retain(JSON.stringify(value), null, ttlOf(value));
       return value;
     } catch (error) {
-      if (!fresh && cacheErrors) retain(null, JSON.stringify({ message: String(error.message).slice(0, 1000), code: error.code, deferred: error.deferred, retry_at: error.retry_at }));
+      if (!fresh && cacheErrors) retain(null, JSON.stringify({ message: String(error.message).slice(0, 1000), code: error.code, status: error.status, deferred: error.deferred, retry_at: error.retry_at }));
       throw error;
     } finally {
       db.prepare('UPDATE github_discovery SET claim=NULL,claim_until=0 WHERE key=? AND claim=?').run(key, claim);

package/board/workflow.mjs

@@ -342,11 +342,15 @@ export async function refreshRelationAnswers(board) {
   for (const row of board.db.prepare("SELECT e.payload FROM task_events e JOIN (SELECT task_id, MAX(id) id FROM task_events WHERE kind IN ('blocked','unblocked') GROUP BY task_id) last ON e.id=last.id JOIN tasks t ON t.id=e.task_id WHERE e.kind='blocked' AND t.status='blocked'").all()) {
     const id = json(row.payload, {})?.waiting_on; if (id) ids.add(id);
   }
-  // State requests stay live while the card runs, independently of a blocker.
-  // Read their exact question ids through the same mailbox receipt door.
-  for (const row of board.db.prepare("SELECT id FROM tasks WHERE current_run_id IS NOT NULL AND status NOT IN ('done','cancelled','archived')").all()) {
-    const request = stateRequestOf(board.db, row.id);
+  // State requests stay live while the card runs, independently of a blocker, and a card's latest request is read
+  // until its answer has been relayed (granted or denied, settleStateRequestAnswers), on a closed card too while the
+  // request is recent (stateRequestCards). Read the ids the questions were mailed under through the same mailbox
+  // receipt door.
+  for (const row of stateRequestCards(board.db, entry?.params?.notice_max_age_seconds)) {
+    const request = row.current_run_id != null && !row.closed ? stateRequestOf(board.db, row.id) : null;
     if (request?.message_id) ids.add(request.message_id);
+    const latest = latestStateRequest(board.db, row.id);
+    if (latest?.question && !latest.relayed) ids.add(latest.question);
   }
   const list = [...ids];
   if (!list.length) return;
@@ -356,8 +360,9 @@ export async function refreshRelationAnswers(board) {
     if (!Array.isArray(rows)) throw new Error('the mail door returned no message list');
     for (const id of list) {
       const row = rows.find((item) => item?.id === id);
+      const reply = row?.replies?.[0] ?? null;
       mailboxAnswers.set(id, row?.found === true
-        ? { answer: row.replies?.[0]?.id ?? null, askedOf: row.session ?? null }
+        ? { answer: reply?.id ?? null, askedOf: row.session ?? null, by: reply?.from ?? null, at_ms: reply?.created_at_ms ?? null, text: reply?.body ?? null }
         : { error: `the mailbox did not find question ${id}; its answer is unknown` });
     }
   } catch (error) { for (const id of list) mailboxAnswers.set(id, { error: `the answer to ${id} could not be read: ${String(error.message).slice(0, 200)}` }); }
@@ -370,16 +375,66 @@ function answerTo(id) {
 
 // A manager's state act settles the request; a mailbox reply answers it without
 // changing the card. Unknown mailbox reads never assert an unanswered question.
-function stateRequestOf(db, id) {
+const STATE_ACTS = "('paused','resumed','blocked','unblocked','completed','cancelled','review_pass','reopened')";
+// A card's latest state request and the id its question was mailed under. Requests asked within one batch window are
+// mailed as one message under the batch's first id (request-mail.mjs), so a later member's own id was never sent and
+// its answer lands under the batch's: board_message_sent records which (`request_id` the member's, `message_id` the
+// sent one). `relayed` once its answer is on the card (state_request_answered).
+function latestStateRequest(db, id) {
   const row = one(db, "SELECT id,payload,created_at FROM task_events WHERE task_id=? AND kind='state_requested' ORDER BY id DESC LIMIT 1", id);
-  if (!row || one(db, "SELECT 1 FROM task_events WHERE task_id=? AND id>? AND kind IN ('paused','resumed','blocked','unblocked','completed','cancelled','review_pass','reopened') LIMIT 1", id, row.id)) return null;
+  if (!row) return null;
   const payload = json(row.payload, {}) ?? {};
-  const question = payload.message_id ?? json(one(db, "SELECT payload FROM task_events WHERE task_id=? AND id<? AND kind='board_message' AND json_extract(payload,'$.batch') IS NOT NULL ORDER BY id DESC LIMIT 1", id, row.id)?.payload, {})?.message_id;
+  const asked = payload.message_id ?? json(one(db, "SELECT payload FROM task_events WHERE task_id=? AND id<? AND kind='board_message' AND json_extract(payload,'$.batch') IS NOT NULL ORDER BY id DESC LIMIT 1", id, row.id)?.payload, {})?.message_id;
+  const sent = asked ? one(db, "SELECT json_extract(payload,'$.message_id') AS id FROM task_events WHERE task_id=? AND id>? AND kind='board_message_sent' AND json_extract(payload,'$.request_id')=? ORDER BY id DESC LIMIT 1", id, row.id, asked)?.id : null;
+  const relayed = Boolean(one(db, "SELECT 1 FROM task_events WHERE task_id=? AND id>? AND kind='state_request_answered' AND json_extract(payload,'$.request_event')=? LIMIT 1", id, row.id, row.id));
+  return { row, payload, question: sent ?? asked ?? null, relayed };
+}
+function stateRequestOf(db, id) {
+  const latest = latestStateRequest(db, id);
+  if (!latest || one(db, `SELECT 1 FROM task_events WHERE task_id=? AND id>? AND kind IN ${STATE_ACTS} LIMIT 1`, id, latest.row.id)) return null;
+  const { row, payload, question } = latest;
   const receipt = question ? mailboxAnswers.get(question) : null;
-  return { id: row.id, created_at: row.created_at, state: payload.state, reason: payload.reason, message_id: question ?? null,
+  return { id: row.id, created_at: row.created_at, state: payload.state, reason: payload.reason, message_id: question,
     answer_known: Boolean(receipt && !receipt.error), answer: receipt?.answer ?? null, error: receipt?.error ?? null };
 }
 
+/**
+ * The cards whose latest state request is still read: every open card, and a closed card (done, cancelled or archived:
+ * the manager may close it before a round reads the reply) whose latest request is younger than the workflow's
+ * notice_max_age_seconds, or STATE_ANSWER_WINDOW_SECONDS when it sets none, until its answer is recorded. A closed
+ * card's request older than that is no longer read, so an unanswered one is not read every round forever.
+ */
+const STATE_ANSWER_WINDOW_SECONDS = 3600;
+function stateRequestCards(db, maxAgeSeconds) {
+  const since = now() - (Number(maxAgeSeconds) || STATE_ANSWER_WINDOW_SECONDS);
+  return all(db, `SELECT t.id, t.current_run_id, t.status IN ('done','cancelled','archived') AS closed FROM tasks t
+    LEFT JOIN (SELECT task_id, MAX(id) id, MAX(created_at) at FROM task_events WHERE kind = 'state_requested' GROUP BY task_id) r ON r.task_id = t.id
+    WHERE t.status NOT IN ('done','cancelled','archived')
+      OR (r.id IS NOT NULL AND r.at >= ?
+        AND NOT EXISTS (SELECT 1 FROM task_events a WHERE a.task_id = t.id AND a.id > r.id AND a.kind = 'state_request_answered' AND json_extract(a.payload,'$.request_event') = r.id))`, since);
+}
+
+/**
+ * Each card's latest state request (stateRequestCards) whose answer the mailbox has read and the card does not yet
+ * record: the manager's reply to the board's question, granted or denied, with who sent it, its text and the state
+ * act (if any) the card took after the request. The dispatcher records it and tells the requester (dispatch.mjs
+ * settleStateRequestAnswers); a denial changes no card state, so this reply is the only trace it leaves.
+ */
+export function unrelayedStateAnswers(db, maxAgeSeconds) {
+  const out = [];
+  for (const task of stateRequestCards(db, maxAgeSeconds)) {
+    const latest = latestStateRequest(db, task.id);
+    if (!latest?.question || latest.relayed) continue;
+    const receipt = mailboxAnswers.get(latest.question);
+    if (!receipt?.answer) continue;
+    const act = one(db, `SELECT kind FROM task_events WHERE task_id=? AND id>? AND kind IN ${STATE_ACTS} ORDER BY id LIMIT 1`, task.id, latest.row.id)?.kind ?? null;
+    out.push({ task_id: task.id, run_id: task.current_run_id ?? null, request_event: latest.row.id,
+      state: latest.payload.state ?? null, requester: latest.payload.requester ?? null, question: latest.question,
+      answer: receipt.answer, answered_by: receipt.by ?? null, answered_at_ms: receipt.at_ms ?? null, text: receipt.text ?? null, act });
+  }
+  return out;
+}
+
 const OPEN_OUTCOME = /^(\s*[-*] )\[ \] (.+)$/;
 const TICKED_OUTCOME = /^\s*[-*] \[[xX]\] .+$/;
 /** Card bodies use Markdown headings and standalone labels such as `Acceptance:` and `Tasks:`. Every label ends

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.218",
+  "version": "0.5.220",
   "type": "module",
   "description": "The orchestrator runtime over the Volter Harness ontology: one typed operational model whose folder is its serialization, read and written through the harness orchestration doors (docs/ORCHESTRATOR-IR.md)",
   "exports": {
@@ -36,10 +36,10 @@
     "check-types": "node scripts/generate-types.mjs --check"
   },
   "dependencies": {
-    "@volter/supercode-teams": "^0.3.365",
+    "@volter/supercode-teams": "^0.3.376",
     "@volter/supercode-terminal": "^0.3.12",
     "@volter/supercode-harness-sdk": "^0.3.106",
-    "@volter/teams": "0.2.103",
+    "@volter/teams": "0.2.104",
     "@volter/ztrack": "^2.4.23",
     "yaml": "^2.9.0"
   },