@volter/supercode-orchestrator 0.5.211 → 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/bin/orchestrator.mjs

@@ -53,6 +53,11 @@ if (process.argv[2] === 'workflow') {
   const {disconnectWorkplace}=await import('../connection.mjs');
   try{const {values}=parseArgs({args:process.argv.slice(3),options:{root:{type:'string'},connection:{type:'string'}}});process.stdout.write(JSON.stringify(await disconnectWorkplace(values),null,2)+'\n');}
   catch(error){process.stderr.write(`disconnect: ${error.message}\n`);process.exitCode=1;}
+} else if (process.argv[2] === 'mcp-server') {
+  // a session's orchestrator tools on stdio, bound by its environment (mcp/mount.mjs mounts this through the stable
+  // supercode)
+  const {serveStdio,bindingFromEnv}=await import('../mcp/server.mjs');
+  serveStdio(bindingFromEnv());
 } else if (process.argv[2] === 'agent-channel') {
   await import('./agent-channel.mjs');
 } else {

package/board/attachment-write.mjs

@@ -0,0 +1,68 @@
+// Upload staging belongs to the board, beneath the authorized card, and to one caller.
+// No attachment record exists until all bytes and their digest have been verified.
+import { closeSync, fstatSync, linkSync, mkdirSync, openSync, readFileSync, readSync, rmSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { basename, join } from 'node:path';
+
+const CHUNK = 1024 * 1024;
+const safeName = name => basename(String(name)).replace(/[^A-Za-z0-9._ -]/g, '_').replace(/^\.+$/, '') || 'attachment';
+
+export function receiveAttachment({ directory, upload, caller, input, add }) {
+  if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(upload) || !caller)
+    throw new Error('attachment upload needs its identifier and an admitted caller');
+  let body;
+  try { body = JSON.parse(input); } catch { throw new Error('attachment upload needs JSON input'); }
+  const staging = join(directory, '.uploads', upload), metadata = join(staging, 'upload.json'), path = join(staging, 'bytes');
+  if (body?.action === 'begin') {
+    if (!Number.isSafeInteger(body.size) || body.size < 0 || typeof body.name !== 'string') throw new Error('invalid attachment extent or name');
+    mkdirSync(join(directory, '.uploads'), { recursive: true });
+    mkdirSync(staging, { mode: 0o700 });
+    try {
+      writeFileSync(path, '', { flag: 'wx', mode: 0o600 });
+      writeFileSync(metadata, JSON.stringify({ caller, size: body.size, name: safeName(body.name) }), { flag: 'wx', mode: 0o600 });
+    } catch (error) { rmSync(staging, { recursive: true, force: true }); throw error; }
+    return { ok: true, upload, received: 0 };
+  }
+  const held = JSON.parse(readFileSync(metadata, 'utf8'));
+  if (held.caller !== caller) throw new Error('attachment upload belongs to another caller');
+  if (body?.action === 'abort') { rmSync(staging, { recursive: true }); return { ok: true, upload, aborted: true }; }
+  if (body?.action === 'append') {
+    const bytes = typeof body.bytes === 'string' && body.bytes.length <= Math.ceil(CHUNK / 3) * 4 ? Buffer.from(body.bytes, 'base64') : null;
+    if (!bytes?.length || bytes.length > CHUNK || bytes.toString('base64') !== body.bytes
+      || !Number.isSafeInteger(body.offset) || body.offset < 0 || body.offset + bytes.length > held.size)
+      throw new Error('invalid attachment chunk');
+    const file = openSync(path, 'r+');
+    try {
+      if (fstatSync(file).size !== body.offset) throw new Error('attachment chunk is not at its next offset');
+      for (let written = 0; written < bytes.length;) {
+        const count = writeSync(file, bytes, written, bytes.length - written, body.offset + written);
+        if (count <= 0) throw new Error('attachment chunk write stopped');
+        written += count;
+      }
+    } finally { closeSync(file); }
+    return { ok: true, upload, received: body.offset + bytes.length };
+  }
+  if (body?.action !== 'commit' || !/^[a-f0-9]{64}$/.test(body.sha256)) throw new Error('invalid attachment upload action or digest');
+  const file = openSync(path, 'r'), hash = createHash('sha256'), buffer = Buffer.alloc(CHUNK);
+  try {
+    if (fstatSync(file).size !== held.size) throw new Error('attachment upload is incomplete');
+    for (let offset = 0; offset < held.size;) {
+      const count = readSync(file, buffer, 0, Math.min(CHUNK, held.size - offset), offset);
+      if (count <= 0) throw new Error('attachment upload ended before its extent');
+      hash.update(buffer.subarray(0, count)); offset += count;
+    }
+    if (hash.digest('hex') !== body.sha256) throw new Error('attachment upload digest does not match the source');
+  } finally { closeSync(file); }
+  let target;
+  for (let n = 0;; n++) {
+    target = join(directory, n ? `${n}-${held.name}` : held.name);
+    try { linkSync(path, target); break; } catch (error) { if (error.code !== 'EEXIST') throw error; }
+  }
+  let id;
+  try { id = add({ path: target, size: held.size }, held.name); }
+  catch (error) { unlinkSync(target); throw error; }
+  // The committed record is authoritative; failed staging cleanup must not turn success into an ambiguous retry.
+  let cleanup = null;
+  try { rmSync(staging, { recursive: true }); } catch { cleanup = staging; }
+  return { ok: true, id, path: target, size: held.size, sha256: body.sha256, name: held.name, ...(cleanup ? { cleanup } : {}) };
+}

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

@@ -15,6 +15,7 @@ import { detachSession } from './custody.mjs';
 import { taskStatusOf } from './published.mjs';
 import { executionOf } from './session-work.mjs';
 import { attachmentRecord, readAttachment } from './attachment-read.mjs';
+import { receiveAttachment } from './attachment-write.mjs';
 import { listCardsInTurns, READ_BY_OWNER, writeCardList } from './listing.mjs';
 import { redactGuardText as redactText, withCredentialGuard } from './credential-guard.mjs';
 import { openOwnerDoor } from './owner-door.mjs';
@@ -69,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';
@@ -112,13 +113,14 @@ The board's verbs, with their flags:
   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>
   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)
   block <id> [reason] (--on <card> | --waiting-on <message id>) [--ids ...]   schedule <id> [reason] [--ids ...]
   pause <id> --reason <why>   resume <id>   cancel <id> --reason <why>
   request-state <id> --state block|pause|done|cancelled --reason <why> [--on <card>|--waiting-on <message>] [--evidence <pointers>]
   unblock <id>... --on <blocker> --reason <what arrived>   request-review <id> (--pr URL --pr-head SHA)... [--summary] [--reviewer] [--force] [--commit SHA]   request-changes <id> <reason> [--finding <finding>]...   reopen-review <id>...   reopen <id>... [--reason]
   promote <id> [reason] [--ids ...] [--force] [--dry-run]   archive <id>... --reason <why> [--rm <id>...]
   specify <id> [--readable-id ID] [--title --body | --body-file PATH|-] [--workspace scratch|worktree:<repository>|dir:<repository>] [--branch NAME] [--machine M|none] [--all]
-  decompose <id> [--child "<title>[@<profile>]"]... [--all]
+  decompose <id> [--child "<title>[@<profile>]"]... [--all]  file the card's subtasks atomically, if its workflow allows
   diagnostics [--task] [--severity]   stats   assignees   log <id> [--tail N]   tail <id>   watch [--assignee] [--kinds]
   github-usage [--since 1h]          local REST attempts by caller/endpoint; no GitHub read
   notify-subscribe <id> --platform P --chat-id C [--thread-id]   notify-list [<id>]   notify-unsubscribe <id> --platform P --chat-id C
@@ -142,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.
@@ -662,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(', ') || '-'}`);
@@ -833,6 +844,15 @@ export async function runVerb(argv) {
     }
     case 'attach': {
       need(2, 'a card id and a file');
+      if (args.upload !== undefined) {
+        if (rest[1] !== '-') throw new Error('attachment upload reads its carried stdin');
+        withBoard(b => { if (!engine.getTask(b.db, id)) throw new Error(`no card ${id}`); });
+        const directory = join(slug === DEFAULT_BOARD ? join(root, 'kanban', 'attachments') : join(boardDir(root, slug), 'attachments'), id);
+        const result = receiveAttachment({ directory, upload: args.upload, caller: callerAddress() ?? actorOf(), input: current().stdin,
+          add: (file, name) => withBoard(b => engine.addAttachment(b, id, { file, name, contentType: args['content-type'] ?? null, author: args.author ?? callerName() })) });
+        say(args, result.id ? `Attached ${result.name} to ${id} (#${result.id}, sha256 ${result.sha256})` : `Upload ${args.upload}: ${result.received ?? 'aborted'}`, result);
+        return 0;
+      }
       const source = callerPath(rest[1]);
       if (!existsSync(source) || !statSync(source).isFile()) throw new Error(`no file ${rest[1]}`);
       const name = basename(args.name ?? source).replace(/[^A-Za-z0-9._ -]/g, '_') || 'attachment';
@@ -1252,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.'); });