@volter/supercode-orchestrator 0.5.212 → 0.5.213

package/README.md

@@ -124,7 +124,10 @@ range under the same worker scope. The maximum `length` is 1,048,576 bytes.
 `XDG_CONFIG_HOME`). It needs neither a running board nor a GitHub request. It
 groups retained wire attempts by caller and endpoint, includes their purposes
 and outcomes, and shows the latest 32 response-header receipts. Unknown transport
-completion remains counted. Tokens and response bodies are not retained.
+completion remains counted. Tokens and raw response bodies are not retained in
+the attempts ledger. Budget refusals have separate local receipts, exposed as
+`refusals`; `refusals_since` and `refusals_complete` say whether collection covers
+the requested window. An older ledger cannot prove the absence of refusals.
 
 Board actions check their local role, guard and validator rules before GitHub.
 Fresh source observations are reused only within that action, with at most eight
@@ -132,15 +135,38 @@ concurrent REST operations per process. Owner receipts retain the return code an
 redacted refusal even when a failed call is fast. See
 [acceptance latency readings](../../docs/evidence/board-acceptance-latency-2026-10-14.md).
 
-Board discovery caches advisory reads while waiting. Review requests, verdicts
-and acceptance refresh the complete source set, including previously draft or
-closed declared sources, and validate its current heads. An unread set defers
+Board discovery persists advisory projections in this same private SQLite file:
+one open-PR list per API origin, credential digest and repository for five minutes,
+independent of which card declares that repository. Default-branch metadata has
+its own entry; acquiring it never repeats the list. Branch histories last fifteen
+minutes, merged PR observations an hour and other PR observations a minute.
+Failures remain failures for the entry's interval. In-process readers share a
+pending result; another process defers on its durable claim instead of duplicating
+the request. A claim expires after six minutes if its process disappears.
+Successful fresh validation refreshes advisory discovery, including after restart.
+
+Review requests, verdicts
+and acceptance refresh the complete source set in the arc's repositories,
+including previously draft or closed declared sources, and validate its current
+heads. That scope includes its workspace, registered branches, declared sources,
+previous candidate and discovered sibling work, and is retained in the source
+receipt. Broad known-repository discovery remains advisory; unrelated checkouts
+spend no validation calls. Every fresh source entry first acquires that advisory
+scope, even for old receipts and sibling checkouts now on main; an unread scope
+refuses authorization. A round with every head judged stops at advisory
+eligibility, and the review evidence door refuses a redundant proposed head set
+before a fresh scan. An unread set defers
 the action. Before the dispatcher spends those validation reads, it checks the
-advisory candidate against its local worktrees. A mismatched HEAD or uncommitted
-work refuses that attempt locally. Each later round rechecks the checkout, so
+advisory candidate's PR properties and local worktrees. An invalid PR state,
+draft, head or base refuses before the full validation scan, including a declared
+PR on the wrong base. Discovery refreshes changes to those properties. A mismatched
+HEAD or uncommitted work also refuses locally. Each later round rechecks the checkout, so
 a repair wakes it; a successful preflight still needs the fresh complete-source,
 local and pushed-head checks before review is recorded. Unread commit dates also defer eligibility and are never cached as
-old work. Merge validation still reads the current head. Every request page, retry, redirect and merge PUT
+old work. An arc that already named a PR for review cannot become a no-code
+disposition merely because it merged; it skips the repeated no-code history
+validation. Advisory no-code and commit eligibility use discovery's allowance.
+Merge validation still reads the current head. Every request page, retry, redirect and merge PUT
 reserves its own attempt. All processes and credentials sharing this supercode
 home share a rolling-hour ceiling of 1,200 attempts, including at most 600
 discovery attempts. Endpoint exhaustion/Retry-After also defers subsequent work.

package/board/ci.mjs

@@ -7,7 +7,7 @@ import { createHash } from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { branchCheckouts, checkoutOf, isLocalWorkspace, resolveWorkspace, plainWorkspace } from './workspace.mjs';
 import { noteStep } from '@volter/supercode-harness-sdk/slow-log';
-import { githubFetch } from './github-rest.mjs';
+import { githubFetch, githubDiscovery } from './github-rest.mjs';
 import { cardHandleOf } from './store.mjs';
 
 // GitHub is read through its REST API with Node's own fetch, in this process and awaited (never a child the caller
@@ -177,22 +177,15 @@ const numberOf = (url) => Number(new URL(url).pathname.split('/')[4]);
 /** A PR as the board reads it (gh's field names). */
 const pullRequest = (repository, p) => ({ url: p.html_url, number: p.number, state: p.merged_at ? 'MERGED' : String(p.state).toUpperCase(), headRefOid: p.head.sha,
   headRefName: p.head.ref, baseRefName: p.base.ref, defaultBranch: p.base.repo?.default_branch ?? null, isCrossRepository: p.head.repo?.full_name?.toLowerCase() !== repository.toLowerCase(), isDraft: Boolean(p.draft) });
-const readPullRequest = async (url) => pullRequest(repositoryOf(url), await github(`/repos/${repositoryOf(url)}/pulls/${numberOf(url)}`));
+const discoveryIdentity = async key => `${githubBase()}\0${createHash('sha256').update(await githubToken() ?? '').digest('hex')}\0${key}`;
+const discoveryRead = async (key, ttl, read, options) => githubDiscovery(await discoveryIdentity(key), ttl, read, options);
+const readPullRequest = async (url) => discoverPullRequest(url, { fresh: true });
 // Discovery is advisory. Already-merged sources are retained for an hour, others for a minute. Every transition
 // still uses readPullRequest/verifyPullRequest above/below, which bypass this cache and reads its current head.
-const discoveredPullRequests = new Map();
-export async function discoverPullRequest(url) {
-  const key = `${githubBase()}\0${createHash('sha256').update(await githubToken() ?? '').digest('hex')}\0${url}`;
-  let held = discoveredPullRequests.get(key);
-  if (held && Date.now() < held.until) return held.pending;
-  if (discoveredPullRequests.size >= 4096 && !held) discoveredPullRequests.delete(discoveredPullRequests.keys().next().value);
-  held = { until: Date.now() + 60_000 };
-  held.pending = github(`/repos/${repositoryOf(url)}/pulls/${numberOf(url)}`, false, { purpose: 'discovery' })
-    .then(body => { const pr = pullRequest(repositoryOf(url), body); held.until = Date.now() + (pr.state === 'MERGED' ? 3600_000 : 60_000); return pr; });
-  // Failed reads stay failed for a minute; no cached empty source or invented successful head.
-  void held.pending.catch(() => {});
-  discoveredPullRequests.set(key, held);
-  return held.pending;
+export async function discoverPullRequest(url, { fresh = false } = {}) {
+  return discoveryRead(`pr:${repositoryOf(url).toLowerCase()}:${numberOf(url)}`, 60_000, async () => pullRequest(repositoryOf(url),
+    await github(`/repos/${repositoryOf(url)}/pulls/${numberOf(url)}`, false, { purpose: fresh ? 'validation' : 'discovery' })),
+  { fresh, ttlOf: pr => pr.state === 'MERGED' ? 3600_000 : 60_000 });
 }
 
 /**
@@ -339,31 +332,16 @@ async function recreatedWorktree(workspace, resolved) {
   try { const made = await resolveWorkspace(workspace, true); return made.path === resolved.path && checkoutPresent(made.path); } catch { return false; }
 }
 
-const pullRequestLists = new Map();
-const mergedPullRequestLists = new Map();
-// Keep in-flight and failed list reads too, with room for the registered branch set. History changes rarely;
-// ordinary open work is discovered by the repository's open-PR listing.
-async function discoveryList(cache, key, ttl, read) {
-  key = `${githubBase()}\0${createHash('sha256').update(await githubToken() ?? '').digest('hex')}\0${key}`;
-  let held = cache.get(key);
-  if (held && Date.now() < held.until) return held.pending;
-  if (cache.size >= 4096 && !held) cache.delete(cache.keys().next().value);
-  held = { until: Date.now() + ttl };
-  held.pending = Promise.resolve().then(read).catch(error => { held.until = Date.now() + 60_000; throw error; });
-  void held.pending.catch(() => {}); cache.set(key, held);
-  return held.pending;
-}
-
 /** Historical work can already be merged when an outage prevented the board's
  * review request. Read only the arc's declared branch, never all closed PRs. */
 async function mergedBranchPullRequests(repository, branch, { fresh = false } = {}) {
-  const key = `${repository}:${branch}`;
+  const key = `${repository.toLowerCase()}:${branch}`;
   const read = async () => {
     const head = encodeURIComponent(`${repository.split('/')[0]}:${branch}`);
     return (await github(`/repos/${repository}/pulls?state=closed&head=${head}&per_page=100`, true, { purpose: fresh ? 'validation' : 'discovery' }))
       .filter(p => p.merged_at).map(p => pullRequest(repository, p));
   };
-  return fresh ? read() : discoveryList(mergedPullRequestLists, key, 900_000, read);
+  return discoveryRead(`history:${key}`, 900_000, read, { fresh });
 }
 
 async function branchCheckout(board, id, repository, branch) {
@@ -430,18 +408,38 @@ export function declaredWorkBranches(db, id) {
  *  of, or a sibling checkout the arc registered (`registeredBranches`). The repository's default branch, declared or
  *  checked out (or no branch), is not a work branch: such a card's PRs are only its `wt/<card>` and registered ones, and with none it
  *  answers `{ waits }` saying so. One review covers them all; the caller decides the transition. */
-export async function openReviewPullRequests(board, id, { fresh = false, checkWorkspaces = false } = {}) {
+export async function openReviewPullRequests(board, id, { fresh = false, checkWorkspaces = false, repositories = [] } = {}) {
+  if (!fresh) return discoverReviewSources(board, id, { checkWorkspaces, repositories });
+  // Every authorization entry acquires the broad advisory scope, not only
+  // dispatch. An older receipt and a checkout now on main still have to see
+  // implicit wt/<card> PRs. Discovery failures leave that scope unknown.
+  const scope = new Set(repositories);
+  await discoverReviewSources(board, id, { repositories, strict: true }, scope);
+  return discoverReviewSources(board, id, { fresh: true, checkWorkspaces, repositories: [...scope] });
+}
+
+async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces = false, repositories = [], strict = false } = {}, scope = null) {
   const own = await repositoryWorkspace(board, id);
-  const registered = registeredBranches(board, id);
+  const registered = registeredBranches(board, id).map(r => ({ ...r, repository: r.repository.toLowerCase() }));
   if (!own && !registered.length) 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);
+  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)
     || registered.some((r) => r.repository === repository && r.branch === head);
-  const repositoriesToRead = [...new Set([ownRepository, ...registered.map((r) => r.repository), ...(await knownRepositories({ fresh }))].filter(Boolean))];
+  // Broad discovery finds wt/<card> work in sibling repositories. Authorization
+  // refreshes only this arc's repositories, including siblings already found or
+  // requested; an unrelated checkout is never a validation-purpose PR scan.
+  const previous = reviewCandidate(board, id);
+  const requested = [...candidatePullRequests(previous).map(p => p.repository ?? repositoryOf(p.pr.url)),
+    ...(previous?.review_repositories ?? [])];
+  const siblings = fresh ? [] : await knownRepositories({ strict });
+  const repositoriesToRead = [...new Set([ownRepository, ...registered.map(r => r.repository), ...requested,
+    ...repositories, ...siblings].filter(Boolean).map(r => r.toLowerCase()))];
+  const reviewRepositories = new Set([ownRepository, ...registered.map(r => r.repository), ...requested, ...repositories]
+    .filter(Boolean).map(r => r.toLowerCase()));
   const answered = answeredChanges(board, id);
   const groups = await readTogether(repositoriesToRead, async repository => {
     const prs = [];
@@ -449,22 +447,22 @@ export async function openReviewPullRequests(board, id, { fresh = false, checkWo
     // Advisory discovery is shared. Before a move, refresh the full set, including previously excluded PRs.
     let list;
     try {
-      const read = async () => {
-        const items = (await github(`/repos/${repository}/pulls?state=open&per_page=100`, true, { purpose: fresh ? 'validation' : 'discovery' })).map((p) => pullRequest(repository, p));
-        // An empty unrelated repository has neither candidates nor branch history to filter. Its default
-        // branch cannot affect this set; only the card's own or registered repositories need that metadata.
-        const needsDefault = items.length > 0 || hasWorkBranches;
-        const defaultBranch = items.find(pr => pr.defaultBranch)?.defaultBranch
-          ?? (needsDefault ? (await github(`/repos/${repository}`, false, { purpose: fresh ? 'validation' : 'discovery' })).default_branch : null);
-        return { items, defaultBranch };
-      };
-      // An empty named-only observation cannot supply branch metadata when a later card registers this repo.
-      const listKey = `${repository}:${hasWorkBranches ? 'work' : 'named'}`;
-      list = fresh ? await read() : await discoveryList(pullRequestLists, listKey, 300_000, read);
+      const items = await discoveryRead(`open:${repository.toLowerCase()}`, 300_000, async () =>
+        (await github(`/repos/${repository}/pulls?state=open&per_page=100`, true, { purpose: fresh ? 'validation' : 'discovery' })).map(p => pullRequest(repository, p)), { fresh });
+      // Empty unrelated repositories need no default metadata. Keep that lookup separate from the shared list,
+      // so a card declaring the repository can acquire it without listing the same open PRs again.
+      const needsDefault = items.length > 0 || hasWorkBranches;
+      const defaultBranch = items.find(pr => pr.defaultBranch)?.defaultBranch
+        ?? (needsDefault ? await discoveryRead(`default:${repository.toLowerCase()}`, 300_000, async () =>
+          (await github(`/repos/${repository}`, false, { purpose: fresh ? 'validation' : 'discovery' })).default_branch, { fresh }) : null);
+      list = { items, defaultBranch };
     } catch (error) {
-      if (fresh || repository === ownRepository || registered.some(r => r.repository === repository)) throw error;
+      if (fresh || strict || repository === ownRepository || registered.some(r => r.repository === repository)) throw error;
       return []; // An unread sibling stays unread: do not cache an empty successful result.
     }
+    // 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);
     // 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;
@@ -497,24 +495,34 @@ export async function openReviewPullRequests(board, id, { fresh = false, checkWo
   // 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 repositories = new Set([ownRepository, ...registered.map((r) => r.repository)].filter(Boolean).map((r) => r.toLowerCase()));
-  const sources = (declaration ? JSON.parse(declaration.payload).sources : []).filter(source => repositories.has(repositoryOf(source.url).toLowerCase()) && !prs.some(known => known.url === source.url));
+  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))) {
     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 });
   }
+  // Retain scope even when all matching PRs are excluded drafts/other bases,
+  // or judged merged sources, so a fresh scan cannot inherit that exclusion.
+  if (scope) for (const repository of reviewRepositories) scope.add(repository);
   if (!prs.length) return branch || !ownRepository ? null : { waits: `the card has no work branch (${task?.branch_name ? `it declares ${task.branch_name}, its repository's default` : current ? `its checkout ${own.path} is on ${current}, its repository's default` : `its checkout ${own.path} is on no branch`}): give it one with --branch, or open its PR from a wt/${id} branch` };
-  // Advisory facts can refuse an attempt before its authoritative REST scan. Recheck the local checkout each
-  // round, so a repaired HEAD or clean worktree wakes it without caching the refusal. This is never evidence
-  // for a transition: verifyPullRequest repeats the checks against fresh metadata and the pushed head below.
-  if (checkWorkspaces) await readTogether(prs, pr => requireReviewWorkspaceHead(board, id, own, pr.observed, pr.head));
-  return { pr: prs.map((p) => p.url), pr_head: prs.map((p) => p.head), branch };
+  // Advisory facts can refuse an attempt before its authoritative REST scan. Check every PR's properties before
+  // doing checkout work: a wrong base cannot be repaired by revalidating the whole arc every round. Discovery
+  // refreshes changed heads/bases/states; local readiness is read each round. Neither check authorizes a move:
+  // verifyPullRequest repeats both against fresh metadata and the pushed head below.
+  if (checkWorkspaces) {
+    for (const pr of prs) requireReviewPullRequestProperties(pr.url, pr.head, pr.observed);
+    await readTogether(prs, pr => requireReviewWorkspaceHead(board, id, own, pr.observed, pr.head));
+  }
+  return { pr: prs.map((p) => p.url), pr_head: prs.map((p) => p.head), branch, review_repositories: [...reviewRepositories].sort() };
 }
 
 /** An arc that changed no code (a disposition, such as closing a PR with its reason): its work branch holds no commit
  *  beyond its repository's default branch, locally or on origin, its checkout holds no uncommitted work, no PR was
  *  ever opened from it, and it registered no other branch. Answers what its review reads instead of a diff, or null when the arc carries (or may carry) code. */
-export async function noCodeChange(board, id) {
+export async function noCodeChange(board, id, { fresh = false } = {}) {
+  // Once this arc has named code for a review, an empty open set after merging is not a no-code disposition.
+  // In particular, do not revalidate the same merged branch's PR history on every advisory round.
+  if (candidatePullRequests(reviewCandidate(board, id)).length) return null;
   const taskRow = board.db.prepare('SELECT workspace_kind FROM tasks WHERE id=?').get(id);
   if (taskRow?.workspace_kind === 'scratch') {
     if (board.db.prepare("SELECT 1 FROM tasks t JOIN supercode_cards c ON c.task_id=t.id WHERE c.subtask_of=? AND t.workspace_kind!='scratch' AND t.status!='cancelled' LIMIT 1").get(id)) return null;
@@ -542,16 +550,22 @@ export async function noCodeChange(board, id) {
     const remote = (await run('git', ['ls-remote', 'origin', `refs/heads/${branch}`], own)).split(/\s+/)[0];
     if (remote) await run('git', ['merge-base', '--is-ancestor', remote, base], own);
     const owner = repository.split('/')[0];
-    // An empty PR history can authorize a no-code review; keep this validation fresh too.
-    if ((await github(`/repos/${repository}/pulls?state=all&head=${encodeURIComponent(`${owner}:${branch}`)}&per_page=1`)).length) return null;
+    // Advisory eligibility never spends validation's reserve. The committed disposition repeats this read fresh.
+    const path = `/repos/${repository}/pulls?state=all&head=${encodeURIComponent(`${owner}:${branch}`)}&per_page=1`;
+    const history = await discoveryRead(`no-code:${repository.toLowerCase()}:${branch}`, 900_000, () =>
+      github(path, false, { purpose: fresh ? 'validation' : 'discovery' }), { fresh });
+    if (history.length) return null;
     return { pr: [], pr_head: [], branch, no_code: { repository, branch, base, branch_head: remote || null } };
   } catch (error) { if (error.code === 'GITHUB_BUDGET') throw error; return null; }
 }
 
 /** The repositories this machine keeps a checkout of. */
-async function knownRepositories({ fresh = false } = {}) {
-  try { return [...new Set((await branchCheckouts(null, '*')).map((row) => row.repository))]; }
-  catch (error) { if (fresh) throw error; return []; }
+async function knownRepositories({ strict = false } = {}) {
+  try {
+    const checkouts = await branchCheckouts(null, '*');
+    return [...new Set(checkouts.map(row => row.repository))];
+  }
+  catch (error) { if (strict) throw error; return []; }
 }
 
 /** Whether the arc's open PRs (`[{ url, head }]`) call for its review: its last verdict's findings are answered, or
@@ -612,28 +626,27 @@ export function answeredChanges(board, id) {
   return owned.length > 0 && owned.every((t) => ['done', 'cancelled', 'archived'].includes(t.status));
 }
 
-const commitReads = new Map();
 /** A commit's date and source tree, read once: both are immutable. Only a successful read is cached; an unread commit
  *  is unknown, never evidence of old work or of a changed tree. */
 async function commitRead({ url, head }) {
-  const key = `${githubBase()}\0${repositoryOf(url)}\0${head}`;
-  if (commitReads.has(key)) return commitReads.get(key);
-  const commit = (await github(`/repos/${repositoryOf(url)}/commits/${head}`)).commit;
-  const at = Math.floor(Date.parse(commit?.committer?.date) / 1000), tree = commit?.tree?.sha;
-  if (!Number.isFinite(at) || typeof tree !== 'string' || !tree) throw new Error(`GitHub commit ${head} of ${url} is unreadable; review eligibility is unknown`);
-  const read = { at, tree };
-  commitReads.set(key, read);
-  return read;
+  return discoveryRead(`commit:${repositoryOf(url).toLowerCase()}:${head}`, 3600_000, async () => {
+    const commit = (await github(`/repos/${repositoryOf(url)}/commits/${head}`, false, { purpose: actionReads.getStore() ? 'validation' : 'discovery' })).commit;
+    const at = Math.floor(Date.parse(commit?.committer?.date) / 1000), tree = commit?.tree?.sha;
+    if (!Number.isFinite(at) || typeof tree !== 'string' || !tree) throw new Error(`GitHub commit ${head} of ${url} is unreadable; review eligibility is unknown`);
+    return { at, tree };
+  }, { cacheErrors: false });
 }
 const commitTime = async (p) => (await commitRead(p)).at;
 /** Whether the PR's head carries the same source tree as `commit` of the same PR. */
 const sameTree = async (p, commit) => (await commitRead(p)).tree === (await commitRead({ url: p.url, head: commit })).tree;
 
 /** A cached exclusion must never hide a newly ready/reopened source from a committed review or acceptance. */
-async function requireCurrentReviewSet(board, id, urls) {
-  const current = await openReviewPullRequests(board, id, { fresh: true });
+async function requireCurrentReviewSet(board, id, urls, repositories = []) {
+  const current = await openReviewPullRequests(board, id, { fresh: true,
+    repositories: [...repositories, ...urls.map(repositoryOf)] });
   const omitted = (current?.pr ?? []).filter(url => !urls.includes(url));
   if (omitted.length) throw new Error(`The current review source set also includes ${omitted.join(', ')}; refresh the complete candidate before requesting review, recording its verdict or accepting it`);
+  return current?.review_repositories ?? repositories;
 }
 
 /** The verdict already recorded on `head` of the card's PR: a changes-requested or pass that answered
@@ -682,9 +695,16 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
     }
     const asked = stage === 'review_verdict' ? reviewCandidate(board, id) : null;
     const urls = [].concat(payload.pr ?? payload.metadata?.pr ?? candidatePullRequests(asked).map((c) => c.pr.url)).filter(Boolean);
-    if (stage === 'request_review' || stage === 'review_verdict') await requireCurrentReviewSet(board, id, urls);
-    if (!urls.length && asked?.no_code) return { ...state, no_code: asked.no_code };
     if (urls.some(url => typeof url !== 'string' || !/^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/[1-9][0-9]*\/?$/.test(url))) throw new Error('Name each GitHub PR URL with --pr.');
+    // Advisory heads can refuse a redundant request, never authorize one. Do
+    // this before a fresh source scan, including for callers outside dispatch.
+    const proposed = [].concat(payload.pr_head ?? payload.commit ?? payload.metadata?.pr_head ?? payload.metadata?.commit ?? []).filter(Boolean);
+    if (stage === 'request_review' && urls.length && proposed.length === urls.length && proposed.every(head => typeof head === 'string' && /^[a-f0-9]{40}$/.test(head))
+      && !await reviewDue(board, id, urls.map((url, i) => ({ url, head: proposed[i] })))) {
+      throw new Error('Every proposed PR head already has a verdict or carries no new source; no review is due.');
+    }
+    if (stage === 'request_review' || stage === 'review_verdict') state.review_repositories = await requireCurrentReviewSet(board, id, urls, payload.review_repositories ?? []);
+    if (!urls.length && asked?.no_code) return { ...state, no_code: asked.no_code };
     // Merged source is immutable and needs no surviving workspace. Resolve an
     // unmerged candidate's checkout as before; a broken legacy path never
     // prevents a verdict on already merged commits.
@@ -752,8 +772,8 @@ async function requireReviewWorkspaceHead(board, id, own, observed, head, { push
   }
 }
 
-/** One PR of an arc review, read from GitHub and, for a review request, from the card branch's checkout. */
-async function verifyPullRequest(board, id, entry, own, url, supplied, stage, observed) {
+/** PR-only readiness, shared by advisory refusals and fresh source validation. */
+function requireReviewPullRequestProperties(url, supplied, observed) {
   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('/');
   // A PR merged before its review (an outage fix landed first) is still reviewed: its head is fixed for good, so the
@@ -768,10 +788,17 @@ async function verifyPullRequest(board, id, entry, own, url, supplied, stage, ob
   const mainBranch = observed.defaultBranch ?? 'main';
   // A merged hotfix may have landed on another base (prod); a PR from the main branch itself is a release, never arc work.
   if (branch === mainBranch || (!merged && observed.baseRefName !== mainBranch)) throw new Error(`${url} must propose its worktree branch to the repository main branch.`);
-  if (stage === 'request_review') await requireReviewWorkspaceHead(board, id, own, observed, head, { pushed: true });
   return { repository, branch, commit: head, source_sha: head, pr: { url: observed.url, number: observed.number, head, branch, base: observed.baseRefName } };
 }
 
+/** One PR of an arc review, read from GitHub and, for a review request, from the card branch's checkout. */
+async function verifyPullRequest(board, id, entry, own, url, supplied, stage, observed) {
+  const source = requireReviewPullRequestProperties(url, supplied, observed);
+  const head = source.commit;
+  if (stage === 'request_review') await requireReviewWorkspaceHead(board, id, own, observed, head, { pushed: true });
+  return source;
+}
+
 const digest = bytes => createHash('sha256').update(bytes).digest('hex');
 /** Read the tracked workflow revision the next serve tick will load. */
 export async function workflowRevision(root) {

package/board/cli.mjs

@@ -70,7 +70,7 @@ async function boardPublishing(root) {
   const board = listed?.boards?.find((b) => b.root === here);
   return board ? { ...board, refused: listed.refused ?? null } : null;
 }
-import { dispatchingOf, knowLocalMachine, requestAdoption, alertManagers, boardAddress, boardLabel, boardSettings, boardCaller, callerSession, commandEnv, reconcileCallerLaunch, closeRequested, lanesOf, localMachine, observeFleet, paused, plan, startCard, stopDispatching, supercodeBin, tick, deliver, startDelivery } from './dispatch.mjs';
+import { answerQuestion, dispatchingOf, knowLocalMachine, requestAdoption, alertManagers, boardAddress, boardLabel, boardSettings, boardCaller, callerSession, commandEnv, reconcileCallerLaunch, closeRequested, lanesOf, localMachine, observeFleet, paused, plan, startCard, stopDispatching, supercodeBin, tick, deliver, startDelivery } from './dispatch.mjs';
 import { watchBoard } from './wake.mjs';
 import { attachSideSession, releaseSideSession, sideArcs, sideSessions } from './side-sessions.mjs';
 import { onPanesChanged, onRecordsChanged, readFleetRecords, fleetRecordsCurrent } from './machine-fleet.mjs';
@@ -144,6 +144,8 @@ And:
       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.
   adopt <id> <session> [--assignee P] [--role ROLE]   adopt <arc> <session> --side · release <arc> <session>   detach <id> [--to person:ID]   close <id>   serve (= daemon)   list --machine M
+  answer <id> <option>   choose an option (its number or label) of the question the card's session shows on its pane: the
+      card's manager, its creator or a signed-in person; recorded on the card as question_answered with who answered
   notify-subscribe <id> --address sc:<machine>:<harness>:<id> [--role creator|worker|dependency]
   notify-subscribe <dependency> --for-card <your-arc>: subscribe only your arc's session to dependency notices.
   notify-unsubscribe <dependency> --for-card <your-arc>: remove that arc's subscription only.
@@ -664,6 +666,13 @@ export async function runVerb(argv) {
       if (t.machine) out.push(`  machine:   ${t.machine}`);
       if (t.reviewer) out.push(`  reviewer:  ${t.reviewer} (card override)`);
       if (t.detached) out.push(`  session:   ${t.detached.session.address} belongs to ${t.detached.person} (detached ${ts(t.detached.at)}; dispatcher does not own it)`);
+      // the question the card's session shows on its pane, while it shows (VO-3395), with the door that answers it
+      const asked = card.runs.find((r) => r.id === t.current_run_id)?.metadata?.supercode?.question;
+      if (asked?.options?.length) {
+        out.push(`  question:  its session asks on pane ${asked.pane ?? '?'}${asked.machine ? ` on ${asked.machine}` : ''} (since ${ts(asked.since)}): ${asked.question || '(no words above its options)'}`);
+        for (const option of asked.options) out.push(`             ${String(option.number).padStart(2)}. ${option.label}${option.detail ? ` (${option.detail})` : ''}`);
+        out.push(`             answer: supercode workflow answer ${t.id} <number>`);
+      }
       // where the card's time went: each role's runs, and the rest waiting
       const mins = (sec) => `${Math.round(sec / 60)}m`;
       out.push(`  time:      ${Object.entries(card.time).filter(([, v]) => v > 0).map(([k, v]) => `${k} ${mins(v)}`).join(', ') || '-'}`);
@@ -1263,6 +1272,22 @@ export async function runVerb(argv) {
       say(args, `${id}: ${detached.session.address} belongs to ${detached.person}; the dispatcher no longer owns it`, { ok: true, detached });
       return 0;
     }
+    case 'answer': {
+      // the question the card's session shows on its pane, answered through its machine's panes.answer door as this
+      // board (VO-3395); the card's manager, its creator or a signed-in person answers, and is recorded as having answered
+      need(2, 'a card id and the option to choose (its number or its label)');
+      withBoard(b => {
+        const roles = rolesFor(b.db, id, sid, workflowFor(root).params);
+        if (!roles.includes('manager') && !roles.includes('creator') && !(!sid && principalOf()?.startsWith('person:')))
+          throw new Error(`Only ${id}'s manager, its creator or a signed-in person answers its session's question. Nothing was typed.`);
+      });
+      const by = sid ? callerAddress() ?? actorOf() : principalOf() ?? actorOf();
+      const answered = await withBoardAsync((b) => answerQuestion(b, id, rest.slice(1).join(' '), { by }));
+      const choice = answered.choice ? `${answered.choice.number}. ${answered.choice.label}` : rest.slice(1).join(' ');
+      say(args, answered.answered ? `${id}: answered "${choice}" on pane ${answered.pane} (recorded as question_answered, by ${by})`
+        : `${id}: chose "${choice}" on pane ${answered.pane}, but ${answered.reason ?? 'the pane did not show it taken'}`, { ok: answered.answered === true, answer: answered });
+      return answered.answered ? 0 : 1;
+    }
     case 'adopt': {
       need(2, 'a card id and a session');
       withBoard(b => { if (!rolesFor(b.db, id, sid, workflowFor(root).params).includes('manager')) throw new Error('Only the manager adopts an existing session.'); });

package/board/dispatch.mjs

@@ -25,7 +25,7 @@ import { noteStep } from '@volter/supercode-harness-sdk/slow-log';
 import { monitorsRuns, recoversRuns, retainRecovery, failedObservation, surfaceIncident, auditEndedRuns, originOf } from './incidents.mjs';
 import { readMachineFleet } from './machine-fleet.mjs';
 import { homeFleetMachines } from './fleet-targets.mjs';
-import { delegatedWork, idleInterval } from './session-work.mjs';
+import { delegatedWork, idleInterval, questionText } from './session-work.mjs';
 import { localSessionDelegations } from '../agents.mjs';
 import { cardSectionHeading, creatorOf, sessionProgress } from './workflow.mjs';
 import { boardLabel, boardName } from '@volter/teams/board-name';
@@ -813,6 +813,40 @@ async function stopOwnedSession(board, session) {
   }
 }
 
+/**
+ * Answer the question card `id`'s session shows on its pane (VO-3395): the option `choice` names (its number or its
+ * label), chosen through the pane machine's `panes.answer` door, as this board, for `by` (who asked the board to answer,
+ * recorded as said). The card records `question_answered` with who answered, what was chosen and whether the pane
+ * showed the answer taken; a door that refused or could not be reached records nothing and throws.
+ */
+export async function answerQuestion(board, id, choice, { by }) {
+  const run = view(board, (db) => { const task = getTask(db, id); return task?.current_run_id ? currentRun(db, id) : null; });
+  if (!run) throw new Error(`${id} has no active run, so no session of it is asking anything`);
+  const session = run.metadata?.supercode ?? {};
+  if (!session.pane) throw new Error(`${id}'s session runs in no pane a machine keeps (${session.surface ?? 'unknown surface'}); its question has no pane door`);
+  const asked = session.question ?? null;
+  const machine = normalMachine(session.machine ?? localMachine()) === localMachine() ? null : session.machine;
+  const r = await runtimeDoor(machine, 'harness.v1.panes.answer', {
+    // the board has held the asker to the card's manager, creator or a person: on its own machine it says so as
+    // --foreign does, since a Windows daemon takes no local caller as established (#1245) and would refuse the board
+    pane: session.pane, choice: String(choice), answerer: by ?? null, foreign: true,
+    ...(asked?.question ? { question: asked.question } : {}), ...(session.launch_key ? { launch: session.launch_key } : {}),
+  }, { timeout: 30_000, as: boardAddress(board.label) });
+  if (r.code !== 0) {
+    const failure = json(r.stderr.trim(), null);
+    throw new Error(`${id}: pane ${session.pane} on ${session.machine ?? localMachine()} was not answered: ${failure?.message ?? (r.stderr || r.stdout).trim().slice(-500)}`);
+  }
+  const answer = json(r.stdout.trim(), {});
+  tx(board, (db) => {
+    const current = currentRun(db, id);
+    event(db, id, 'question_answered', { by: by ?? null, through: boardAddress(board.label), pane: session.pane, machine: session.machine ?? null,
+      question: answer.question ?? asked?.question ?? null, choice: answer.choice ?? null, keys: answer.keys ?? null, answered: answer.answered === true,
+      ...(answer.reason ? { reason: answer.reason } : {}) }, current?.id === run.id ? run.id : null);
+    if (answer.answered === true && current?.id === run.id) setRunSession(db, run.id, { question: null });
+  });
+  return answer;
+}
+
 // ------------------------------------------------------------------ starting, as the workflow's dispatch says
 
 /** The command form a card's session uses to reach its board: `--root` on the board's machine, `--at` elsewhere. */
@@ -1740,23 +1774,35 @@ async function observeIdle(board, fleet, settings, report, entry, effects) {
       }
       // a reading that shows the session no longer waiting ends the prompt; a round that did not read it does not
       if (session.held_notice && live && !asked) setRunSession(db, runRow.id, { held_notice: null });
+      if (session.question && live && !(asked && live.question)) setRunSession(db, runRow.id, { question: null });
       if (asked) {
         if (session.idle_since != null || session.idle_notice) setRunSession(db, runRow.id, { idle_since: null, idle_notice: null });
-        // One prompt is one notice: the same wait (what it waits for, since when its harness says) on the same
-        // session, whichever of its cards a round reads first and however long it stands.
-        const key = [address, live.waiting_for ?? '', live.turn_since_ms ?? ''].join('|');
+        // The question its pane shows, with its options, is the card's to carry while it shows (VO-3395): kept on the
+        // run, said in its event and its manager's notice with the door that answers it.
+        const question = live.question && Array.isArray(live.question.options) && live.question.options.length ? {
+          question: String(live.question.question ?? '').slice(0, 1000),
+          options: live.question.options.slice(0, 20).map((option) => ({ number: Number(option.number), label: String(option.label ?? '').slice(0, 300), ...(option.detail ? { detail: String(option.detail).slice(0, 300) } : {}) })),
+        } : null;
+        const asking = question ? JSON.stringify([question.question, question.options.map((option) => option.label)]) : '';
+        if (question && JSON.stringify([session.question?.question, session.question?.options?.map((option) => option.label)]) !== asking)
+          setRunSession(db, runRow.id, { question: { ...question, address, pane: session.pane ?? null, machine: session.machine ?? null, since: observedAt } });
+        // One prompt is one notice: the same wait (what it waits for, since when its harness says, the question its
+        // pane shows) on the same session, whichever of its cards a round reads first and however long it stands.
+        const key = [address, live.waiting_for ?? '', live.turn_since_ms ?? '', asking].join('|');
         if (session.held_notice?.key === key) return;
         // every run a card works under: an ended run can still be its card's current one
         const told = db.prepare(`SELECT r.metadata FROM task_runs r WHERE r.id != ? AND r.id IN (${ACTIVE_RUN_IDS})`).all(runRow.id).some((r) => json(r.metadata, {})?.supercode?.held_notice?.key === key);
         setRunSession(db, runRow.id, { held_notice: { key, at: observedAt } });
         if (told) return;
-        const observation = retain('waiting_on_user', { waiting_for: live.waiting_for ?? null, since_ms: live.turn_since_ms ?? null });
+        const observation = retain('waiting_on_user', { waiting_for: live.waiting_for ?? null, since_ms: live.turn_since_ms ?? null, ...(question ? { question } : {}) });
         const others = (cardsOf.get(address) ?? []).filter((card) => card !== id);
-        const what = live.turn_source === 'pane_prompt' ? 'shows a prompt on its pane that waits for an answer'
+        const what = question ? `asks on its pane: ${questionText(question)}`
+          : live.turn_source === 'pane_prompt' ? 'shows a prompt on its pane that waits for an answer'
           : `reports that it is waiting on its user${live.waiting_for ? ` (${live.waiting_for})` : ''}${live.turn_since_ms ? ` since ${new Date(Number(live.turn_since_ms)).toISOString().slice(0, 19)}Z` : ''}`;
         event(db, id, 'session_held', observation, runRow.id);
         const to = managers[0] ?? null;
-        if (to) event(db, id, 'board_message', { to, text: `${id}: its session ${address} ${what}.${others.length ? ` It is also on ${others.join(', ')}.` : ''}` }, null);
+        const door = question ? ` Answer it with: supercode workflow answer ${id} <option number> ${whereOf(board, task)}.` : '';
+        if (to) event(db, id, 'board_message', { to, text: `${id}: its session ${address} ${what}.${door}${others.length ? ` It is also on ${others.join(', ')}.` : ''}` }, null);
         (report.held ??= []).push([id, 'waiting_on_user', address]);
         return;
       }
@@ -2457,20 +2503,7 @@ async function launchPane(board, task, runId, lane, fleet, { input = null, slot
       // the session is kept; the heartbeat's count belongs to the run that ended, so the new run starts it again
       const { missing_since: _m, goal_turns: _t, goal_nudged_at: _n, idle_since: _is, idle_notice: _in, unknown_since: _us, unknown_notice: _un, work_progress: _wp, idle_observation: _io, idle_below_threshold: _ib, idle_eligible: _ie, close_requested: _q, closed_at: _c, close_confirmed_at: _cc, close_error: _ce, close_attempts: _ca, close_attempted_at: _ct, close_failed_at: _cf, close_unread: _cu, close_claim: _cl, monitor_held: _mh, released: _rl, review_held: _rh, retain_after_run: _rr, ...kept } = prev;
       session = { ...kept, mode: 'adopt', launched_at: now(), seen_at: now() };
-      // a kept session is told what this run is for (its card came back to it, with what happened since), only while
-      // this run is still the card's current one (its pane and native reads were awaited)
-      tx(board, (db) => {
-        if (!runCurrent(db, task.id, runId)) throw Object.assign(new Error(`run ${runId} of ${task.id} ended or was replaced while its session was read; nothing was told to it`), { launchSuperseded: true });
-        setRunSession(db, runId, { ...session, ...meta });
-        transferRetainedSession(db, task.id, runId, session);
-        // an earlier run's close of this pane is this run's now: the pane is the kept session's, not a close to retry
-        if (prev.pane) for (const r of db.prepare('SELECT id, metadata FROM task_runs WHERE task_id = ? AND id != ?').all(task.id, runId)) {
-          const s = json(r.metadata, {})?.supercode;
-          if (s?.pane === prev.pane && s.machine === prev.machine && !s.close_confirmed_at && !s.close_transferred_to) setRunSession(db, r.id, { ...s, close_transferred_to: runId, close_requested: null });
-        }
-      });
-      // filed in its mailbox, which delivers it
-      if (input) { assertRunCurrent(board, task.id, runId); await fileMail(board, addressOf(prev), input, `board-run-${task.id}-r${runId}`); }
+      // The common binding below transfers ownership and subscriptions before filing the continuation prompt.
     } else if (prev.resumable !== false && await nativeAbsent(prev)) {
       // nothing to resume and no context to keep: the slot's next session starts fresh
       replaced = { session_id: prev.session_id, why: `${prev.machine} holds no ${prev.harness ?? 'claude-code'} session of that id (it never took a first turn)`, letGo: true };
@@ -2543,6 +2576,10 @@ async function launchPane(board, task, runId, lane, fleet, { input = null, slot
     return true;
   });
   if (!recorded) return { ...session, mode: 'finished_during_launch' };
+  if (session.mode === 'adopt' && input) {
+    assertRunCurrent(board, task.id, runId);
+    await fileMail(board, session.address, input, `board-run-${task.id}-r${runId}`);
+  }
   return session;
 }
 
@@ -2815,7 +2852,19 @@ async function adoptSession(board, id, who, { request = null, open = request, pr
   const beforeRun = view(board, (db) => currentRun(db, id));
   const beforeCustody = view(board, db => JSON.stringify(detachedCard(db, id)));
   const beforeSession = beforeRun?.metadata?.supercode;
-  if (beforeRun && beforeSession?.session_id !== sessionId) throw new Error(`${id} has another active run/session; end it before adopting a different identity`);
+  const entry0 = workflowFor(board.root), card0 = view(board, (db) => getTask(db, id));
+  const adoptionSlot = beforeSession?.slot ?? view(board, db => {
+    const scope = scopeOf(db, board, card0, { params: entry0.params });
+    return String(templateValue(runSpec(entry0, statusOf(db, card0), card0)?.session ?? 'worker', scope));
+  });
+  const predecessor = view(board, db => lastSession(db, id, adoptionSlot));
+  const sameIdentity = session => addressOf(session) === found.address;
+  // A deferred run has issued no different identity. Bind its own slot's live predecessor, or the session
+  // discovered in its keyed pane, without ending the run or opening another process.
+  const unissued = !beforeSession?.session_id && !beforeSession?.pane && !beforeSession?.launch_key && !beforeSession?.pid && !beforeSession?.launch_pending;
+  const keyedPane = !beforeSession?.session_id && found.pane && beforeSession?.pane === found.pane
+    && beforeSession?.machine === host && beforeSession?.harness === harness;
+  if (beforeRun && !sameIdentity(beforeSession) && !keyedPane && !(unissued && sameIdentity(predecessor))) throw new Error(`${id} has another active run/session; end it before adopting a different identity`);
   if (beforeSession?.pane && beforeSession.pane !== found.pane && await panePresent(beforeSession.machine, beforeSession.pane)) throw new Error(`${id} still has live pane ${beforeSession.pane}; close the extra pane before rebinding ${sessionId}`);
 
   // the session's own working directory, as discovery records it (where `--resume` finds it), else its pane's
@@ -2829,7 +2878,6 @@ async function adoptSession(board, id, who, { request = null, open = request, pr
   }
   // Rule 2: a session working a card role is that role's agent, however it started; adopted, it joins the agent as a
   // launch does, and its recorded profile is compared with the role's intent (rule 4).
-  const entry0 = workflowFor(board.root), card0 = view(board, (db) => getTask(db, id));
   const agentRole = view(board, (db) => adoptedRole(db, board, entry0, card0, beforeRun)) ?? 'implementer';
   const laneName = view(board, (db) => evaluate(entry0.workflow.roles?.[agentRole] ?? 'card.assignee', scopeOf(db, board, card0, { params: entry0.params }))) ?? assignee ?? card0?.assignee;
   const lane = laneName ? lanes?.[laneName] : null, context = current().facts.SUPERCODE_CONTEXT, team = agentScope(context);
@@ -2839,6 +2887,8 @@ async function adoptSession(board, id, who, { request = null, open = request, pr
   const stale = (db) => {
     if (request !== null && !adoptionOpenTo(db, id, request, open)) return Object.assign(new Error(`${id}'s adoption request was answered or claimed meanwhile`), { superseded: true });
     if ((getTask(db, id)?.current_run_id ?? null) !== (beforeRun?.id ?? null)) return new Error(`${id} changed runs during adoption; retry against its current run`);
+    const binding = currentRun(db, id)?.metadata?.supercode;
+    if (['session_id', 'pane', 'launch_key', 'launch_pending', 'launch_deferred'].some(key => (binding?.[key] ?? null) !== (beforeSession?.[key] ?? null))) return new Error(`${id}'s session binding changed during adoption; retry against its current session`);
     if (JSON.stringify(detachedCard(db, id)) !== beforeCustody) return new Error(`${id} changed session custody during adoption; request adoption again`);
     return null;
   };
@@ -2857,7 +2907,6 @@ async function adoptSession(board, id, who, { request = null, open = request, pr
   if (owner && owner.agent_id !== agent.identity.id) throw new Error(`${found.address} already works for agent ${owner.agent_id} (run ${owner.run_id}); it cannot be adopted as ${agent.identity.id}`);
   // Each role owns its own slot. A retained worker does not prevent binding the independent reviewer; only this
   // adoption's slot can conflict with the incoming identity. Independence still reads worker history below.
-  const adoptionSlot = beforeSession?.slot ?? runSpec(entry0, view(board, db => statusOf(db, card0)), card0)?.session ?? 'worker';
   await readBefore(fleet, view(board, (db) => lastSession(db, id, adoptionSlot)));
   const adopted = tx(board, (db) => {
     const task = getTask(db, id);
@@ -2870,7 +2919,7 @@ async function adoptSession(board, id, who, { request = null, open = request, pr
     const was = lastSession(db, id, adoptionSlot);
     // a session whose close the board confirmed is not live, whatever a fleet reading still lists (a released one was
     // left running, and is read)
-    if (was && was.session_id !== sessionId && !(was.close_confirmed_at && !was.released) && sessionAlive(fleet, was)) throw new Error(`${id} already has a live session, ${was.address}`);
+    if (was && !sameIdentity(was) && !(was.close_confirmed_at && !was.released) && sessionAlive(fleet, was)) throw new Error(`${id} already has a live session, ${was.address}`);
     if (!task.machine) db.prepare('INSERT INTO supercode_cards (task_id, machine) VALUES (?, ?) ON CONFLICT(task_id) DO UPDATE SET machine = excluded.machine').run(id, host);
     // the lane that resumes it if it is lost, set in the same transaction (assigning first would let a tick start another)
     if (assignee && assignee !== task.assignee) { db.prepare('UPDATE tasks SET assignee = ? WHERE id = ?').run(assignee, id); event(db, id, 'assigned', { assignee }); }
@@ -2904,7 +2953,13 @@ async function adoptSession(board, id, who, { request = null, open = request, pr
       ...(agent ? { agent_id: agent.identity.id, agent_org: team.org, agent_context: context ?? null,
         agent_profile_intent: { ...structuredClone(agent.intended.resolved), worker: { ...agent.intended.resolved?.worker, harness: lane.harness, model: lane.model ?? null, cwd: dir ?? task.workspace_path ?? null } } } : {}) };
     // a deferred launch was never issued: the adopted session is the run's, and no later round launches another
-    setRunSession(db, runId, { ...(currentRun(db, id)?.metadata?.supercode ?? {}), ...session, detached_at: null, detached_to: null, launch_deferred: false, slot: currentRun(db, id)?.metadata?.supercode?.slot ?? beforeSession?.slot ?? expected?.session ?? 'worker', close_requested: null, closed_at: null, close_confirmed_at: null, close_error: null, missing_since: null });
+    const owned = [beforeSession, was].find(s => s && s.pane === session.pane && (sameIdentity(s) || s === beforeSession && keyedPane));
+    setRunSession(db, runId, { ...(currentRun(db, id)?.metadata?.supercode ?? {}), ...session,
+      detached_at: null, detached_to: null, launch_key: owned?.launch_key ?? null, launch_pending: false, launch_error: null,
+      launch_deferred: false, launch_deferred_error: null, slot: adoptionSlot, retain_after_run: false,
+      close_requested: null, closed_at: null, close_confirmed_at: null, close_error: null, close_failed_at: null, close_claim: null,
+      released: false, forgotten: false, monitor_held: false, missing_since: null });
+    transferRetainedSession(db, id, runId, session);
     event(db, id, 'session_adopted', { session_id: sessionId, machine: host, pane: session.pane, address: found.address, mode: 'adopt', role: currentRun(db, id)?.metadata?.supercode?.role }, runId);
     replaceWorkerSubscriptions(db, id, found.address);
     for (const p of db.prepare('SELECT parent_id FROM task_links WHERE child_id = ?').all(id)) subscribeIn(db, p.parent_id, found.address, 'dependency');
@@ -3660,7 +3715,8 @@ function reviewDueKey(board, id, payload) {
   return `${source}|${closed ?? ''}`;
 }
 
-async function activatePullRequestReviews(board, entry, report, effects, { only = null, dry = false, fleet = null } = {}) {
+/** Review selection shared by rounds and read-only inspection (`dry: true`). */
+export async function activatePullRequestReviews(board, entry, report, effects, { only = null, dry = false, fleet = 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 c.every IS NULL
     ${only ? 'AND t.id=?' : ''}`).all(...(only ? [only] : [])));
@@ -3715,14 +3771,14 @@ async function activatePullRequestReviews(board, entry, report, effects, { only
         report.queued.push([id, `review waits: ${inTurn.why}`]);
         continue;
       }
-      // A stable local refusal (wrong HEAD or uncommitted work) must not spend a full fresh REST scan every
-      // round. Advisory discovery is sufficient to refuse, never to authorize; the scan below still owns that.
+      // A stable PR-property or local refusal must not spend a full fresh REST scan every round. Advisory
+      // discovery is sufficient to refuse, never to authorize; the scan below still owns that.
       if (!payload.no_code) await openReviewPullRequests(board, id, { checkWorkspaces: true });
       if (!dry) await refreshCardInputs(board, id, { commits: true });
       // Cached draft/closed exclusions are useful while waiting, but cannot define a committed review's set.
       const observed = await withFreshReviewReads(async () => {
-        const candidate = await openReviewPullRequests(board, id, { fresh: true })
-          ?? (noCodeReviewDue(board, id) ? await noCodeChange(board, id) : null);
+        const candidate = await openReviewPullRequests(board, id, { fresh: true, repositories: payload.review_repositories ?? [] })
+          ?? (noCodeReviewDue(board, id) ? await noCodeChange(board, id, { fresh: true }) : null);
         const evidence = !candidate || candidate.waits ? null : candidate.no_code
           ? { required: false, ready: true, reason: null, phase: 'source', no_code: candidate.no_code }
           : await inspectCompletionEvidence(board, id, entry, candidate, 'request_review');

package/board/engine.mjs

@@ -131,7 +131,7 @@ export function setRunSession(db, runId, session) {
   const before = whole.supercode;
   whole.supercode = { ...before, ...session };
   const task = one(db, 'SELECT task_id FROM task_runs WHERE id = ?', runId);
-  if (task && session.session_id && session.pane && (before?.session_id !== session.session_id || before?.pane !== session.pane)) retireSupersededRuns(db, task.task_id, runId, whole.supercode);
+  if (task && session.session_id && (before?.session_id !== session.session_id || before?.pane !== session.pane)) retireSupersededRuns(db, task.task_id, runId, whole.supercode);
   run(db, 'UPDATE task_runs SET metadata = ? WHERE id = ?', JSON.stringify(whole), runId);
   return whole;
 }

package/board/github-rest.mjs

@@ -26,10 +26,77 @@ function connection() {
       resource TEXT, used INTEGER, remaining INTEGER, reset_at INTEGER, retry_after INTEGER);
     CREATE INDEX IF NOT EXISTS github_attempts_window ON github_attempts(credential,started_at,purpose);
     CREATE INDEX IF NOT EXISTS github_attempts_home_window ON github_attempts(started_at,purpose);
-    CREATE TABLE IF NOT EXISTS github_cooldown (credential TEXT PRIMARY KEY, until_at INTEGER NOT NULL, reason TEXT NOT NULL);`);
+    CREATE TABLE IF NOT EXISTS github_cooldown (credential TEXT PRIMARY KEY, until_at INTEGER NOT NULL, reason TEXT NOT NULL);
+    CREATE TABLE IF NOT EXISTS github_discovery (
+      key TEXT PRIMARY KEY, observed_at INTEGER NOT NULL, until_at INTEGER NOT NULL,
+      value TEXT, error TEXT, claim TEXT, claim_until INTEGER NOT NULL DEFAULT 0);
+    CREATE TABLE IF NOT EXISTS github_refusals (
+      id TEXT PRIMARY KEY, started_at INTEGER NOT NULL, credential TEXT NOT NULL, machine TEXT NOT NULL,
+      pid INTEGER NOT NULL, caller TEXT NOT NULL, purpose TEXT NOT NULL, method TEXT NOT NULL,
+      endpoint TEXT NOT NULL, code TEXT NOT NULL, reason TEXT NOT NULL);
+    CREATE INDEX IF NOT EXISTS github_refusals_window ON github_refusals(started_at,purpose);
+    CREATE TABLE IF NOT EXISTS github_observation_meta (key TEXT PRIMARY KEY, value INTEGER NOT NULL);`);
+  db.prepare("INSERT OR IGNORE INTO github_observation_meta(key,value) VALUES('refusals_since',?)").run(Date.now());
   connections.set(path, db);
   return db;
 }
+
+const discoveryReads = new Map();
+const discoveryPending = () => Object.assign(new Error('GitHub discovery is already being read by another process; no duplicate read was started'), { code: 'github_discovery_pending', deferred: true });
+/** Advisory observations survive command/owner restarts. Fresh transition reads never consume a cached value,
+ * but publish their successful observation for discovery. A short transaction claims each advisory read; no
+ * transaction spans I/O and a different process defers rather than waiting or duplicating its wire attempts. */
+export async function githubDiscovery(identity, ttl, read, { fresh = false, ttlOf = () => ttl, cacheErrors = true } = {}) {
+  const key = createHash('sha256').update(identity).digest('hex');
+  const localKey = `${pathOf()}\0${key}`;
+  if (!fresh && discoveryReads.has(localKey)) return discoveryReads.get(localKey);
+  const work = async () => {
+    const db = connection(), began = Date.now(), claim = randomUUID();
+    if (!fresh) {
+      let cached = null;
+      db.exec('BEGIN IMMEDIATE');
+      try {
+        const held = db.prepare('SELECT * FROM github_discovery WHERE key=?').get(key);
+        if (held && held.until_at > began && (held.value != null || held.error != null)) {
+          cached = held;
+        } else {
+          if (held?.claim_until > began) throw discoveryPending();
+          db.prepare(`INSERT INTO github_discovery(key,observed_at,until_at,claim,claim_until) VALUES(?,0,0,?,?)
+            ON CONFLICT(key) DO UPDATE SET claim=excluded.claim,claim_until=excluded.claim_until`).run(key, claim, began + 360_000);
+        }
+        db.exec('COMMIT');
+      } catch (error) { db.exec('ROLLBACK'); throw error; }
+      if (cached) {
+        if (cached.error) { const failure = JSON.parse(cached.error); throw Object.assign(new Error(failure.message), failure); }
+        return JSON.parse(cached.value);
+      }
+    }
+    const retain = (value, error, duration = ttl) => {
+      db.prepare(`INSERT INTO github_discovery(key,observed_at,until_at,value,error) VALUES(?,?,?,?,?)
+        ON CONFLICT(key) DO UPDATE SET observed_at=excluded.observed_at,until_at=excluded.until_at,
+          value=excluded.value,error=excluded.error,claim=NULL,claim_until=0
+        WHERE github_discovery.observed_at<=excluded.observed_at`).run(key, began, Date.now() + duration, value, error);
+    };
+    try {
+      const value = await read();
+      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 }));
+      throw error;
+    } finally {
+      db.prepare('UPDATE github_discovery SET claim=NULL,claim_until=0 WHERE key=? AND claim=?').run(key, claim);
+      // Retain only live observations/claims. Expired advisory data has no evidentiary role.
+      db.prepare('DELETE FROM github_discovery WHERE until_at<=? AND claim_until<=?').run(Date.now(), Date.now());
+    }
+  };
+  const pending = work();
+  if (!fresh) {
+    discoveryReads.set(localKey, pending);
+    try { return await pending; } finally { if (discoveryReads.get(localKey) === pending) discoveryReads.delete(localKey); }
+  }
+  return pending;
+}
 const refusal = (message) => Object.assign(new Error(message), { code: 'GITHUB_BUDGET' });
 const integer = (value) => value != null && /^\d+$/.test(value) && Number.isSafeInteger(Number(value)) ? Number(value) : null;
 function endpointOf(url) {
@@ -63,7 +130,15 @@ async function issue(url, options, { purpose }) {
     db.prepare('INSERT INTO github_attempts(id,credential,started_at,machine,pid,caller,purpose,method,endpoint) VALUES(?,?,?,?,?,?,?,?,?)')
       .run(id, credential, at, hostname(), process.pid, caller, purpose, method, endpoint);
     db.exec('COMMIT');
-  } catch (error) { db.exec('ROLLBACK'); throw error; }
+  } catch (error) {
+    db.exec('ROLLBACK');
+    // A refused action made no wire attempt. Keep its receipt separately so a full-hour qualification can read
+    // actual budget refusals as well as usage, without inflating the allowance or inferring success from silence.
+    if (error.code === 'GITHUB_BUDGET') db.prepare(`INSERT INTO github_refusals
+      (id,started_at,credential,machine,pid,caller,purpose,method,endpoint,code,reason) VALUES(?,?,?,?,?,?,?,?,?,?,?)`)
+      .run(id, at, credential, hostname(), process.pid, caller, purpose, method, endpoint, error.code, error.message);
+    throw error;
+  }
   let response, outcome = 'unknown';
   try { response = await fetch(url, { ...options, redirect: 'manual' }); outcome = response.ok ? 'ok' : `HTTP_${response.status}`; return response; }
   catch (error) { outcome = error.code ?? error.name ?? 'transport_error'; throw error; }
@@ -109,7 +184,14 @@ export function githubUsage({ since = Date.now() - HOUR } = {}) {
   if (!existsSync(path)) return { path, recorded: false, callers: [], endpoints: [] };
   const db = new DatabaseSync(path, { readOnly: true });
   try {
+    const hasRefusals = Boolean(db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='github_refusals'").get());
+    const hasMeta = Boolean(db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='github_observation_meta'").get());
+    const refusalsSince = hasMeta ? db.prepare("SELECT value FROM github_observation_meta WHERE key='refusals_since'").get()?.value ?? null : null;
     return { path, recorded: true, since, limits: { hourly: GITHUB_HOURLY_ATTEMPTS, discovery: GITHUB_DISCOVERY_ATTEMPTS },
+      refusals_recorded: hasRefusals, refusals_since: refusalsSince, refusals_complete: refusalsSince != null && refusalsSince <= since,
+      refusals: hasRefusals ? db.prepare(`SELECT credential,machine,pid,caller,purpose,method,endpoint,code,COUNT(*) refusals,
+        MIN(started_at) first_at,MAX(started_at) last_at FROM github_refusals WHERE started_at>=?
+        GROUP BY credential,machine,pid,caller,purpose,method,endpoint,code`).all(since).map(r => ({ ...r, caller: JSON.parse(r.caller) })) : [],
       callers: db.prepare(`SELECT credential,machine,pid,caller,purpose,COUNT(*) attempts,SUM(status IS NULL) unanswered
         FROM github_attempts WHERE started_at>=? GROUP BY credential,machine,pid,caller,purpose`).all(since).map(r => ({ ...r, caller: JSON.parse(r.caller) })),
       endpoints: db.prepare(`SELECT credential,machine,pid,caller,purpose,method,endpoint,status,COUNT(*) attempts

package/board/incidents.mjs

@@ -126,6 +126,7 @@ export function auditEndedRuns(db, board, entry) {
     if (decided) continue; // its manager or creator ended it by an explicit act
     const audited = db.prepare("SELECT 1 FROM task_events WHERE task_id=? AND run_id=? AND kind='audited'").get(task.id,task.run_id);
     if (audited) continue; // Every explicitly schedules the next successful audit
+    if (session?.retain_after_run && task.outcome === 'completed') continue; // an explicit finish hands work to review
     if (['blocked','paused','reconfigured','review_passed','review','review_requested','audited'].includes(task.outcome)) continue;
     surfaceIncident(db, board, entry, task.id, 'run_ended', { error: task.error, outcome: task.outcome }, task.run_id);
   }

package/board/machine-fleet.mjs

@@ -112,7 +112,9 @@ export async function readMachineFleet(machines, local) {
         // what a session that needs input says it waits for, what started its open turn (Codex: `goal` for a thread
         // goal's continuation) and since when, where its harness publishes them
         waiting_for: activity.evidence?.waiting_for ?? null, turn_source: activity.evidence?.source ?? null, turn_since_ms: activity.evidence?.native_state_since_ms ?? null,
-        turn_trigger: activity.evidence?.turn_trigger ?? null });
+        turn_trigger: activity.evidence?.turn_trigger ?? null,
+        // the question its pane shows and its options, where its machine read one off the screen (VO-3395)
+        question: activity.evidence?.question ?? null });
     }
   }
   const ok = online.has(local);

package/board/session-work.mjs

@@ -50,3 +50,10 @@ export function idleInterval(session, live, observedAt) {
   const since = Math.min(observedAt, Math.max(read, Number(session.watch_since ?? 0)));
   return { since, quiet: Math.max(0, observedAt - since) };
 }
+
+/** A question a run's session shows on its pane (VO-3395), as one line: its words and each option, numbered. */
+export function questionText(question) {
+  if (!question) return '';
+  const options = (question.options ?? []).map((option) => `[${option.number}] ${option.label}`).join(' ');
+  return `${question.question ? `${question.question} ` : ''}${options}`.trim();
+}

package/board/workflow.mjs

@@ -1256,16 +1256,25 @@ const ACTIONS = {
 /** Binding a newer run transfers ownership; stale run references cannot veto its later stop. */
 export function retireSupersededRuns(db, id, runId, session) {
   if (!session?.session_id && !session?.pane) return;
-  for (const old of all(db, `SELECT id,task_id,metadata FROM task_runs WHERE id IN (
-    SELECT id FROM task_runs WHERE id<? AND ended_at IS NULL AND json_extract(metadata, '$.supercode.machine') IS ?
+  for (const old of all(db, `SELECT id,task_id,ended_at,metadata FROM task_runs WHERE id IN (
+    SELECT id FROM task_runs WHERE id<? AND json_extract(metadata, '$.supercode.machine') IS ?
       AND json_extract(metadata, '$.supercode.session_id')=?
-    UNION SELECT id FROM task_runs WHERE id<? AND ended_at IS NULL AND json_extract(metadata, '$.supercode.machine') IS ?
+    UNION SELECT id FROM task_runs WHERE id<? AND json_extract(metadata, '$.supercode.machine') IS ?
       AND json_extract(metadata, '$.supercode.pane')=?)`,
     runId, session.machine ?? null, session.session_id ?? null, runId, session.machine ?? null, session.pane ?? null)) {
     const whole = json(old.metadata, {}) ?? {}, s = whole.supercode;
     if (!s || detachedSession(db, s) || s.machine !== session.machine || !((session.session_id && s.session_id === session.session_id) || (session.pane && s.pane === session.pane))) continue;
     if (old.task_id !== id && one(db, 'SELECT 1 FROM tasks WHERE current_run_id = ?', old.id)) throw new Error(`session is still owned by active run ${old.id} of ${old.task_id}`);
-    if (s.pane && s.pane === session.pane) whole.supercode = { ...s, close_transferred_to: runId, close_requested: null };
+    const transferred = (s.pane && s.pane === session.pane) || (!s.pane && !session.pane && s.session_id === session.session_id);
+    if (old.ended_at) {
+      if (transferred && s.close_transferred_to !== runId) {
+        whole.supercode = { ...s, close_transferred_to: runId, close_requested: null };
+        run(db, 'UPDATE task_runs SET metadata=? WHERE id=?', JSON.stringify(whole), old.id);
+        record(db, old.task_id, 'session_transferred', { successor: runId, session_id: s.session_id, pane: s.pane ?? null }, old.id);
+      }
+      continue;
+    }
+    if (transferred) whole.supercode = { ...s, close_transferred_to: runId, close_requested: null };
     run(db, "UPDATE task_runs SET status='superseded', outcome='superseded', ended_at=?, claim_lock=NULL, claim_expires=NULL, worker_pid=NULL, metadata=? WHERE id=?", now(), JSON.stringify(whole), old.id);
     record(db, old.task_id, 'run_superseded', { successor: runId, session_id: s.session_id, pane: s.pane }, old.id);
   }

package/connection.mjs

@@ -38,6 +38,10 @@ export async function connectionCall(record, side, method, path, body, token) {
   if(!response.ok)throw Object.assign(new Error(`${side} ${method} ${path}: ${payload.error?.code??response.status}`),{code:payload.error?.code,status:response.status});
   return payload;
 }
+/** A registration that trusts a Workplace as its issuer trusts this connection's Workplace and organization, never the
+ * one its committed manifest names (agents.teams-app.json names production's): otherwise every connection's agents app
+ * trusted production's tokens, and its own Workplace's notices and views were decided as the issuer app instead. */
+export function trustedIssuer(manifest,record){return manifest.issuer===undefined?{}:{issuer:record.issuer,issuer_organization:record.organization};}
 export function connectionPath(root,id){return join(root,'apps','connections',id,'connection.json');}
 export function generateModuleConfig(root, record, grant) {
   if(SERVICE_APPS.includes(grant.name))return generateServiceConfig(root,record,grant);
@@ -172,7 +176,7 @@ export async function connectWorkplace(flags) {
       grant.rh2=exchanged.data;privateJson(path,record);
     }
     if(selected.teamsManifest&&!grant.teams){
-      if(!grant.registration){grant.stagedSecret??=`sca_${randomBytes(32).toString('base64url')}`;privateJson(path,record);grant.registration=(await connectionCall(record,'teams','POST',`/api/v1/teams/${encodeURIComponent(teams.team)}/apps`,{...selected.teamsManifest,name:`${selected.teamsManifest.name} (${id.slice(0,8)})`,secret:grant.stagedSecret},owner)).data;privateJson(path,record);}
+      if(!grant.registration){grant.stagedSecret??=`sca_${randomBytes(32).toString('base64url')}`;privateJson(path,record);grant.registration=(await connectionCall(record,'teams','POST',`/api/v1/teams/${encodeURIComponent(teams.team)}/apps`,{...selected.teamsManifest,...trustedIssuer(selected.teamsManifest,record),name:`${selected.teamsManifest.name} (${id.slice(0,8)})`,secret:grant.stagedSecret},owner)).data;privateJson(path,record);}
       grant.registration.secret=grant.stagedSecret;
       if(!grant.consent){grant.stagedCode??=`sci_${randomBytes(32).toString('base64url')}`;privateJson(path,record);grant.consent=(await connectionCall(record,'teams','POST',`/api/v1/teams/${encodeURIComponent(teams.team)}/apps/${grant.registration.id}/installations`,{redirect_url:selected.teamsManifest.redirect_urls[0],state:id,actions:selected.teamsManifest.actions,code:grant.stagedCode},owner)).data;privateJson(path,record);}
       grant.consent.code=grant.stagedCode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.212",
+  "version": "0.5.213",
   "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": {
@@ -32,7 +32,7 @@
     "check-types": "node scripts/generate-types.mjs --check"
   },
   "dependencies": {
-    "@volter/supercode-teams": "^0.3.347",
+    "@volter/supercode-teams": "^0.3.344",
     "@volter/supercode-terminal": "^0.3.10",
     "@volter/supercode-harness-sdk": "^0.3.104",
     "@volter/teams": "0.2.99",
@@ -61,5 +61,6 @@
     "board",
     "apply",
     "README.md"
-  ]
+  ],
+  "gitHead": "d017029f1b1d9293e295839a496be94a641b1ac0"
 }