@volter/supercode-orchestrator 0.5.215 → 0.5.216

package/board/ci.mjs

@@ -101,6 +101,27 @@ async function mapGithubSources(items, work) {
   return out;
 }
 const readTogether = mapGithubSources;
+/** A review refusal only the arc's own act clears (a PR's base, draft or state; its checkout's head, commits or push; a
+ *  PR on no branch the arc declares): `kind` and `url` name it for the dispatcher, which tells it as a review wait instead
+ *  of only logging it each round, keyed by its kinds and PRs alone so a changing detail (a count, a path) is not a new wait. */
+const refused = (kind, url, message) => Object.assign(new Error(message), { code: 'review_refused', refusals: [{ kind, url }] });
+/** One refusal naming every refused PR, in a fixed order whatever order the reads finished in. */
+const refusalOf = (errors) => {
+  const sorted = [...errors].sort((a, b) => a.refusals[0].kind.localeCompare(b.refusals[0].kind) || a.refusals[0].url.localeCompare(b.refusals[0].url));
+  const refusals = sorted.flatMap((e) => e.refusals).filter((r, i, all) => all.findIndex((o) => o.kind === r.kind && o.url === r.url) === i);
+  return Object.assign(new Error(sorted.map((e) => e.message).join(' ')), { code: 'review_refused', refusals });
+};
+/** `readTogether` that runs `check` on every item and collects every refusal instead of the first to reject; any other
+ *  failure is thrown as before. Answers the checks' results. */
+async function refuseTogether(items, check) {
+  const refusals = [];
+  const out = await readTogether(items, async (item, index) => {
+    try { return await check(item, index); }
+    catch (error) { if (error?.code !== 'review_refused') throw error; refusals.push(error); return null; }
+  });
+  if (refusals.length) throw refusalOf(refusals);
+  return out;
+}
 /** One GitHub REST read (`all`: every page of a list). The token is the environment's, else gh's stored login: a failed
  *  read of the login is not kept, and a login token GitHub refuses (401, rotated or revoked) is read again once. */
 const actionReads = new AsyncLocalStorage();
@@ -181,7 +202,7 @@ const discoveryIdentity = async key => `${githubBase()}\0${createHash('sha256').
 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.
+// still uses readPullRequest and the fresh source checks in inspectCompletionEvidence, which bypass this cache and reads its current head.
 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' })),
@@ -408,17 +429,17 @@ 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, repositories = [] } = {}) {
-  if (!fresh) return discoverReviewSources(board, id, { checkWorkspaces, repositories });
+export async function openReviewPullRequests(board, id, { fresh = false, checkWorkspaces = false, refuseStacked = false, repositories = [] } = {}) {
+  if (!fresh) return discoverReviewSources(board, id, { checkWorkspaces, refuseStacked, 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] });
+  return discoverReviewSources(board, id, { fresh: true, checkWorkspaces, refuseStacked, repositories: [...scope] });
 }
 
-async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces = false, repositories = [], strict = false } = {}, scope = null) {
+async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces = false, refuseStacked = false, repositories = [], strict = false } = {}, scope = null) {
   const own = await repositoryWorkspace(board, id);
   const registered = registeredBranches(board, id).map(r => ({ ...r, repository: r.repository.toLowerCase() }));
   if (!own && !registered.length) return null;
@@ -441,6 +462,7 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
   const reviewRepositories = new Set([ownRepository, ...registered.map(r => r.repository), ...requested, ...repositories]
     .filter(Boolean).map(r => r.toLowerCase()));
   const answered = answeredChanges(board, id);
+  const stacked = [];
   const groups = await readTogether(repositoriesToRead, async repository => {
     const prs = [];
     const hasWorkBranches = repository === ownRepository || registered.some(r => r.repository === repository);
@@ -469,6 +491,10 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
     }
     // a draft is not handed over yet: its review starts when it is marked ready; a PR to another base (main→prod) is a release, not the arc's work
     for (const pr of list.items) if (!pr.isCrossRepository && !pr.isDraft && pr.baseRefName === pr.defaultBranch && mine(repository, pr.headRefName)) prs.push({ url: pr.url, head: pr.headRefOid, observed: pr });
+    // A ready PR on one of the arc's branches proposed to any branch but the default (stacked on another PR, or a wrong
+    // base) would leave the arc's one review set without a word: it is kept as stacked, and a review request refuses
+    // and tells it until it is retargeted to the default branch. A PR from the default branch itself is a release.
+    for (const pr of list.items) if (!pr.isCrossRepository && !pr.isDraft && pr.defaultBranch && pr.headRefName !== pr.defaultBranch && pr.baseRefName !== pr.defaultBranch && mine(repository, pr.headRefName)) stacked.push(pr);
     // A manual review and merge during a dispatcher outage may predate any
     // board request. The source-review door already accepts merged heads; make
     // them discoverable so the ordinary independent verdict can be retained.
@@ -504,16 +530,22 @@ async function discoverReviewSources(board, id, { fresh = false, checkWorkspaces
   // 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);
+  stacked.sort((a, b) => a.url.localeCompare(b.url));
+  // Advisory discovery can be up to five minutes old: the dispatcher tells a stacked refusal only once a fresh read
+  // (refuseStacked) confirms it.
+  if (stacked.length && (checkWorkspaces || refuseStacked)) throw refusalOf(stacked.map((pr) => refused('base', pr.url, `${pr.url} proposes ${pr.headRefName} to ${pr.baseRefName}, not ${pr.defaultBranch}: retarget it to ${pr.defaultBranch} so the arc's one review includes it.`)));
+  if (!prs.length && stacked.length) return { pr: [], pr_head: [], branch, review_repositories: [...reviewRepositories].sort(), stacked: stacked.map((pr) => pr.url) };
   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. 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.
+  // inspectCompletionEvidence repeats both, in the same order, against fresh metadata and the pushed head. Each
+  // collects every PR's refusal, so the same state always refuses with the same set.
   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));
+    await refuseTogether(prs, pr => requireReviewPullRequestProperties(pr.url, pr.head, pr.observed));
+    await refuseTogether(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() };
+  return { pr: prs.map((p) => p.url), pr_head: prs.map((p) => p.head), branch, review_repositories: [...reviewRepositories].sort(), stacked: stacked.map((pr) => pr.url) };
 }
 
 /** An arc that changed no code (a disposition, such as closing a PR with its reason): its work branch holds no commit
@@ -582,8 +614,7 @@ async function knownRepositories({ strict = false } = {}) {
  *  joins with a head committed before the verdict is not: the next run is the implementer's until it answers. After a
  *  pass nothing is owed by the implementer, so any new head of a PR it judged is due (acceptance needs the verdict on
  *  the current heads), and a PR that verdict's request did not name is due at whatever head it has: one that was a draft
- *  or stacked on another PR's branch when the request was made, and became the arc's once that PR merged (t_bbbd2086's
- *  #1355, committed 2 h before the pass that named only #1353). */
+ *  when the request was made. */
 export async function reviewDue(board, id, prs) {
   if (prs.length && answeredChanges(board, id)) return true;
   const unjudged = prs.filter((p) => !judgedHead(board, id, p.head));
@@ -719,8 +750,8 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
     if (!own && !mergedOnly) {
       const registered = registeredBranches(board, id);
       const declared = (pr) => namedWorkBranch(id, pr.headRefName) || registered.some((r) => r.branch === pr.headRefName && r.repository.toLowerCase() === repositoryOf(pr.url).toLowerCase());
-      const stray = read.find((pr) => pr.state !== 'MERGED' && !declared(pr));
-      if (stray) throw new Error(`An unmerged PR candidate needs a repository workspace: ${stray.url} (${stray.headRefName}) is on no branch the card or its tasks declare; declare it on the arc: comment ${id} "<why>" --source ${repositoryOf(stray.url)}:${stray.headRefName} (with every other source the arc changes)`);
+      const strays = read.filter((pr) => pr.state !== 'MERGED' && !declared(pr));
+      if (strays.length) throw refusalOf(strays.map((stray) => refused('undeclared', stray.url, `An unmerged PR candidate needs a repository workspace: ${stray.url} (${stray.headRefName}) is on no branch the card or its tasks declare; declare it on the arc: comment ${id} "<why>" --source ${repositoryOf(stray.url)}:${stray.headRefName} (with every other source the arc changes)`)));
     }
     // A verdict with no requested PR (a scratch arc) keeps its own contract. An arc's review
     // always names every opened PR it changed, independent of deployment.
@@ -732,7 +763,10 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
       : payload.pr_head ?? payload.commit ?? payload.metadata?.pr_head ?? payload.metadata?.commit ?? []).filter(Boolean);
     if (stage === 'request_review' && named.length !== urls.length) throw new Error('Name each PR head with --pr-head, one for each --pr, in the same order.');
     if (stage === 'review_verdict' && !named.length) throw new Error('Name every reviewed PR head with --reviewed-sha.');
-    const prs = await mapGithubSources(urls, (url, index) => verifyPullRequest(board, id, entry, own, url, stage === 'request_review' ? named[index] : null, stage, read[index]));
+    // Every PR's properties, then (for a review request) every PR's checkout at its pushed head, as the advisory pass
+    // checks them; each collects every refusal (refuseTogether).
+    const prs = await refuseTogether(urls, (url, index) => requireReviewPullRequestProperties(url, stage === 'request_review' ? named[index] : null, read[index]));
+    if (stage === 'request_review') await refuseTogether(prs, (source, index) => requireReviewWorkspaceHead(board, id, own, read[index], source.commit, { pushed: true }));
     if (stage === 'request_review') {
       // A review is asked for only while some PR has a head no verdict has judged.
       if (!await reviewDue(board, id, prs.map((p) => ({ url: p.pr.url, head: p.commit })))) throw new Error('Every PR head has a verdict, carries the source tree its verdict judged, or predates it: push a commit that changes the source, or close the tasks that own the last verdict\'s findings, before requesting review.');
@@ -748,6 +782,7 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
   } catch (error) {
     Object.assign(state, { required: true, ready: false, reason: String(error?.message ?? error) });
     if (error?.code) Object.assign(state, { code: error.code, retryable: error.code === 'GITHUB_BUDGET' });
+    if (error?.refusals) state.refusals = error.refusals;
     if (['GITHUB_BUDGET', 'github_rate_limited', 'github_metadata_capacity', 'github_read_admission_full'].includes(error?.code))
       Object.assign(state, { deferred: true, deferred_code: error.code, retry_at: error.retry_at ?? null });
   }
@@ -763,12 +798,12 @@ async function requireReviewWorkspaceHead(board, id, own, observed, head, { push
   const path = observed.state === 'MERGED' || (own && !own.here) ? null : !own ? await branchCheckout(board, id, repository, observed.headRefName) : await originOf(own.path) === repository && await run('git', ['branch', '--show-current'], own.path) === observed.headRefName ? own.path : await branchCheckout(board, id, repository, observed.headRefName);
   if (!path) return;
   await run('git', ['check-ref-format', '--branch', branch], path);
-  if (await run('git', ['rev-parse', 'HEAD'], path) !== head) throw new Error(`The head named for ${url} must be its worktree head.`);
+  if (await run('git', ['rev-parse', 'HEAD'], path) !== head) throw refused('head', url, `The head named for ${url} must be its worktree head.`);
   const uncommitted = (await run('git', ['status', '--porcelain', '--untracked-files=normal'], path)).split('\n').filter(Boolean);
-  if (uncommitted.length) throw new Error(`Commit the work in ${path} before requesting review: ${uncommitted.length} uncommitted path(s): ${uncommitted.slice(0, 5).map((l) => l.replace(/^\s*\S+\s+/, '')).join(', ')}${uncommitted.length > 5 ? ', …' : ''}`);
+  if (uncommitted.length) throw refused('uncommitted', url, `Commit the work in ${path} before requesting review: ${uncommitted.length} uncommitted path(s): ${uncommitted.slice(0, 5).map((l) => l.replace(/^\s*\S+\s+/, '')).join(', ')}${uncommitted.length > 5 ? ', …' : ''}`);
   if (pushed) {
     const remote = (await run('git', ['ls-remote', '--heads', 'origin', `refs/heads/${branch}`], path)).split(/\s+/)[0];
-    if (remote !== head) throw new Error(`Push the exact head of ${url} before requesting review.`);
+    if (remote !== head) throw refused('unpushed', url, `Push the exact head of ${url} before requesting review.`);
   }
 }
 
@@ -779,26 +814,18 @@ function requireReviewPullRequestProperties(url, supplied, observed) {
   // A PR merged before its review (an outage fix landed first) is still reviewed: its head is fixed for good, so the
   // verdict is recorded on that head, and nothing about a worktree or its base can move under it any more.
   const merged = observed.state === 'MERGED';
-  if ((observed.state !== 'OPEN' && !merged) || observed.isCrossRepository) throw new Error(`Source review needs an open or merged PR from its repository (${url}).`);
-  if (!merged && observed.isDraft) throw new Error(`${url} is a draft; its review starts when it is marked ready for review.`);
+  if ((observed.state !== 'OPEN' && !merged) || observed.isCrossRepository) throw refused('state', url, `Source review needs an open or merged PR from its repository (${url}).`);
+  if (!merged && observed.isDraft) throw refused('draft', url, `${url} is a draft; its review starts when it is marked ready for review.`);
   const head = supplied ?? observed.headRefOid;
   if (!/^[a-f0-9]{40}$/.test(head)) throw new Error('Name the full PR head commit with --pr-head (reviewer: --reviewed-sha).');
   if (observed.headRefOid !== head) throw new Error(`The head of ${url} changed to ${observed.headRefOid}; request review of that head before recording a verdict.`);
   const branch = observed.headRefName;
   const mainBranch = 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 (branch === mainBranch || (!merged && observed.baseRefName !== mainBranch)) throw refused('base', url, `${url} must propose its worktree branch to the repository main branch.`);
   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

@@ -1,8 +1,8 @@
 // `supercode workflow <verb>` (docs/architecture/orchestrator.md §2.9): supercode's own board, in Hermes Kanban's
 // format, and its dispatcher. Every verb of `hermes kanban` is here under its own name, with its own flags and its own
 // output lines, so a caller of Hermes's CLI calls this one unchanged; supercode's own verbs (`set`, `adopt`, `detach`, `close`,
-// `serve`, `--at`) are added beside them. The Rust CLI hands every verb but `load` to `bin/orchestrator.mjs workflow`,
-// which lands here. The home is `--root`, else `SUPERCODE_ORCHESTRATOR_HOME`; the board is
+// `serve`, `--at`) are added beside them. The npm Node front door dispatches operator verbs here.
+// The home is `--root`, else `SUPERCODE_ORCHESTRATOR_HOME`; the board is
 // `--board <slug>`, else `HERMES_KANBAN_BOARD`, else the home's current board (`kanban/current`), else `default`.
 import { machineCall, closeDoors, onLocalReopen } from './doors.mjs';
 import { createHash } from 'node:crypto';
@@ -13,18 +13,20 @@ import { current, isCallersCall, ownCall, within } from './call.mjs';
 import { cardState, holdDescription } from './card-state.mjs';
 import { detachSession } from './custody.mjs';
 import { taskStatusOf } from './published.mjs';
-import { executionOf } from './session-work.mjs';
+import { executionOf, readingContext } 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';
+import { inBoardGeneration, generationWork, admitGeneration, grantGenerationWriter, parkGeneration, stopGeneration, tellOwner } from './generation.mjs';
 import { existsSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, copyFileSync, readFileSync, appendFileSync, writeFileSync } from 'node:fs';
 import { notRuntime, ownHome } from './owner-files.mjs';
 import { execFile, spawnSync } from 'node:child_process';
+import { supercodeInvocation } from '@volter/supercode-harness-sdk/supercode-program';
 import { holdLock } from './lock-holder.mjs';
 import { takeEpoch } from './fence.mjs';
-import { dispatcherNotice, holdOwnerHealth, holdRound, holdSwitch } from './owner-health.mjs';
+import { dispatcherNotice, holdOwnerHealth, holdRound, holdSwitch, watchOwnerHealth } from './owner-health.mjs';
 import { boardTool } from './tools.mjs';
 import { arcSources, assertSourceReceipt } from './ci.mjs';
 import { noteStep, recordSlow, takeSteps } from '@volter/supercode-harness-sdk/slow-log';
@@ -41,7 +43,10 @@ import { recordCardAgentChanges } from './agent-declarations.mjs';
 
 // A mailbox read through the mailbox's own command, awaited (never a wait that holds the event loop). Gap A31: a
 // helper process until the daemon owns mail (order 3 PR 4).
-const mailRead = (verb) => new Promise((resolve) => execFile(supercodeBin(), ['message', verb, '--json'], { encoding: 'utf8', env: commandEnv(), timeout: 15_000, maxBuffer: 64 * 1024 * 1024 }, (_, stdout) => resolve(stdout ?? '')));
+const mailRead = (verb) => new Promise((resolve) => {
+  const env = commandEnv(), selected = supercodeInvocation(supercodeBin(), ['message', verb, '--json'], env);
+  execFile(selected.program, selected.arguments, { encoding: 'utf8', env, timeout: 15_000, maxBuffer: 64 * 1024 * 1024 }, (_, stdout) => resolve(stdout ?? ''));
+});
 
 /** The messages on this machine the mailbox still has to deliver (`supercode message waiting`), by message id. */
 async function mailWaiting() {
@@ -70,7 +75,7 @@ async function boardPublishing(root) {
   const board = listed?.boards?.find((b) => b.root === here);
   return board ? { ...board, refused: listed.refused ?? null } : null;
 }
-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 { answerQuestion, dispatchingOf, knowLocalMachine, requestAdoption, alertManagers, boardAddress, boardLabel, boardSettings, boardCaller, callerSession, commandEnv, reconcileCallerLaunch, closeRequested, lanesOf, localMachine, observeFleet, paused, plan, startCard, stopDispatching, resumeDispatching, 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';
@@ -78,7 +83,7 @@ import { FleetListenerRouter, fleetListenerStatus } from './fleet-listeners.mjs'
 import { enrichFleetEvent, observeRoleFleet } from './fleet-observer.mjs';
 import { fileFleetNotice } from './dispatch.mjs';
 import { streamBoardPublications } from './event-stream.mjs';
-import { completionOwnerOf, followHome, isLatestReviewer, loadWorkflow, readHome, requestSessionClose, scopeOf, statusOf, timeOf, useWorkflow, workflowEntry, workflowFor } from './workflow.mjs';
+import { completionOwnerOf, followHome, isLatestReviewer, loadWorkflow, readHome, requestSessionClose, scopeOf, statusOf, timeOf, useWorkflow, workflowEntry, workflowFor, watchWorkflows } from './workflow.mjs';
 import { evaluate } from './expr.mjs';
 import { agentDoor,agentScope,activeAgentAssignments,reassignAgent,agentUsage,localAgentRecord,agentRunForSession } from '../agents.mjs';
 
@@ -99,6 +104,7 @@ A card is named by its id (t_4406c88a) or by its number, keyed or bare (VO-42, v
 gave it when it was made, read with the board's key, the first letters of the board's name.
 
 The board's verbs, with their flags:
+  declaration [--json]   read the serving board declaration
   init [--backing sqlite|files|ztrack] [--document <arcs.md>] [--commit] [--manager <address>] [--dispatching on|off] [--archive-max-lines N] [--archive-period month]
   migrate --backing ztrack --document <arcs.md> --status-map <json>
   boards list|create|rm|switch|show|rename|set-default-workdir|export|import
@@ -144,6 +150,7 @@ 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
+  handover --entry <orchestrator.mjs> --supercode <native>   prepare a board generation, retain its predecessor
   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]
@@ -334,7 +341,7 @@ const ts = (t) => {
   return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
 };
 // a card's status is the workflow's (triaging, reviewing, …); kanban.db stores the Hermes status it maps to
-const line = (key) => (t) => `${ICONS[t.status] ?? '?'} ${engine.cardLabel(key, t.number, t.id, t.readable_id).padEnd(18)}  ${(['paused','blocked'].includes(t.status) ? t.status : t.stage ?? t.status).padEnd(8)}${holdDescription(t) ? ` [${holdDescription(t)}]` : t.detached ? ` [session belongs to ${t.detached.person}]` : ['running','review'].includes(t.status) ? ` [session ${t.execution?.state ?? 'unknown'}]` : ''}  ${(t.assignee || '(unassigned)').padEnd(20)}${t.tenant ? ` [${t.tenant}]` : ''}  ${t.title}${t.machine ? `  @${t.machine}` : ''}`;
+const line = (key) => (t) => `${ICONS[t.status] ?? '?'} ${engine.cardLabel(key, t.number, t.id, t.readable_id).padEnd(18)}  ${(['paused','blocked'].includes(t.status) ? t.status : t.stage ?? t.status).padEnd(8)}${holdDescription(t) ? ` [${holdDescription(t)}]` : t.detached ? ` [session belongs to ${t.detached.person}]` : ['running','review'].includes(t.status) ? ` [session ${t.execution?.state ?? 'unknown'}${t.execution?.reason ? ` — ${t.execution.reason}` : ''}]` : ''}  ${(t.assignee || '(unassigned)').padEnd(20)}${t.tenant ? ` [${t.tenant}]` : ''}  ${t.title}${t.machine ? `  @${t.machine}` : ''}`;
 // `key` is the card's board's (store.mjs boardKey); `ref` the card as a person names it (`VO-856`)
 const stateOptions = root => ({ nativeHolds: Boolean(workflowFor(root).workflow.flags?.paused) });
 const cardDict = (raw, key, options) => { const t = cardState(raw, options); return ({
@@ -427,6 +434,12 @@ export async function runVerb(argv) {
   // C4: one task store per Org. A named board without a store of its own is a saved view over it: its tag selects
   // the cards it shows, and a card filed through it carries that tag.
   const named = boardOf(root, args);
+  if (verb === 'declaration') {
+    const slug = isView(root, named) ? DEFAULT_BOARD : named, backing = backingOf(root, slug);
+    const declared = backing === 'ztrack' ? JSON.parse(readFileSync(backingPaths(root, slug).ztrack, 'utf8')) : null;
+    say(args, JSON.stringify({ board: slug, backing, declared }), { board: slug, backing, declared });
+    return 0;
+  }
   const viewTag = isView(root, named) ? named : null;
   const slug = viewTag ? DEFAULT_BOARD : named;
   const open = (create = false) => { const b = openBoard(root, slug, { create, document: args.document ?? null, backing: create ? args.backing ?? null : null }); b.label = boardLabel(root, slug); return b; };
@@ -640,7 +653,7 @@ export async function runVerb(argv) {
       const card = withBoard((b) => {
         const got = engine.showCard(b.db, id, stateOptions(root));
         got.runs = engine.runs(b.db, id, { stateType: args['state-type'] ?? null, stateName: args['state-name'] ?? null });
-        got.task.execution = executionOf(engine.currentRun(b.db, id));
+        got.task.execution = executionOf(engine.currentRun(b.db, id), readingContext(b.db, got.task.id, got.task.current_run_id));
         got.runs = got.runs.map(run => ({ ...run, execution: executionOf(run) }));
         got.diagnostics = engine.diagnose(b.db, got.task, { ...stateOptions(root), failureLimit: settings.failureLimit, launchWindowSeconds: settings.launchWindow });
         got.stage = statusOf(b.db, got.task);
@@ -666,6 +679,8 @@ 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)`);
+      // what the card's session is doing as the board last read it, beside the lane (ADR 0024)
+      else if (['running', 'review'].includes(t.status)) out.push(`  session:   ${card.task.execution?.state ?? 'unknown'}${card.task.execution?.reason ? ` — ${card.task.execution.reason}` : ''}`);
       // 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) {
@@ -1757,6 +1772,14 @@ function setDispatching(root, slug, on, reason) {
  */
 async function answerVerbs(root, log) {
   const home = boardHome(root);
+  if (inBoardGeneration) {
+    ownHome(home);
+    const epoch = takeEpoch(root, () => listBoards(root).map(slug => openBoard(root, slug)));
+    holdOwnerHealth(listBoards(root).map(slug => [slug, dispatchingOf(root, slug)]), null);
+    log(`generation writer epoch ${epoch}; the stable owner holds the public door`);
+    admitGeneration();
+    return () => {};
+  }
   const lockPath = join(home, 'board.lock');
   // The lock is held by a process of its own (lock-holder.mjs), so nothing this process reads can drop it; a verb
   // naming the lock or socket as its input is refused (owner-files.mjs)
@@ -1784,6 +1807,11 @@ async function answerVerbs(root, log) {
  * Show/list/comment/create also retain receipts below the slow-log threshold;
  * absence from a slow-only log cannot prove those calls met the time bound. */
 export async function answerOne(root, line, { readOnly = false } = {}) {
+  if (inBoardGeneration && !readOnly) return generationWork(() => answerOneAdmitted(root, line));
+  return answerOneAdmitted(root, line, { readOnly });
+}
+
+async function answerOneAdmitted(root, line, { readOnly = false } = {}) {
   const scoped = typeof slowLog.withStepScope === 'function';
   // The owner's receipt includes asynchronous custody preparation too: it is part of the caller's wait.
   const began = performance.now(), before = slowLog.processCounters?.() ?? null;
@@ -1866,6 +1894,74 @@ async function answerRequest(root, line, naming, { readOnly = false } = {}) {
   }
 }
 
+// Prepared children import and read their declarations without writer authority. Activation and parking are ordered
+// on one control chain, so a late park acknowledgement can never park a generation after rollback resumed it.
+export async function serveBoardGeneration(root, args = {}, argv = ['serve', '--root', root]) {
+  if (!inBoardGeneration) throw new Error('a board generation requires its stable owner IPC connection');
+  // The direct parent has already resolved the machine identity. An unavailable daemon must not consume a second
+  // fifteen-second lookup before this child can report preparation through its eight-second owner door.
+  await knowLocalMachine(process.env.SUPERCODE_BOARD_GENERATION_MACHINE);
+  // readHome owns an SDK transport startup and one orchestration.load, each with its existing 30-second bound.
+  tellOwner({ type: 'startup-step', step: 'reading the home through its orchestration door', budget_ms: 65000 });
+  await readHome(root);
+  tellOwner({ type: 'startup-step', step: 'reading board storage without writer authority', budget_ms: 8000 });
+  await within({ cwd: root, readOnly: true, out: () => {}, err: () => {} }, async () => {
+    for (const slug of listBoards(root)) {
+      let board;
+      try { board = openBoard(root, slug); board.db.prepare('SELECT 1').get(); }
+      catch (error) { if (error?.code !== READ_BY_OWNER) throw error; }
+      finally { board?.close(); }
+    }
+  });
+  let begin, started = false, controls = Promise.resolve();
+  const activation = new Promise(done => { begin = done; });
+  const unwatchHealth = watchOwnerHealth(value => tellOwner({ type: 'health', ...value }));
+  const unwatchWorkflow = watchWorkflows((at, { workflow, params, profiles }) => tellOwner({ type: 'workflow', root: at, entry: { workflow, params, profiles } }));
+  const receive = frame => {
+    if (frame?.type === 'request') {
+      answerOne(root, frame.line).catch(error => ({ code: 1, stdout: '', stderr: `${error.message}\n` }))
+        .then(answer => tellOwner({ type: 'answer', id: frame.id, answer }));
+      return;
+    }
+    if (!['activate', 'park'].includes(frame?.type)) return;
+    controls = controls.then(async () => {
+      if (frame.type === 'park') {
+        stopDispatching();
+        await parkGeneration(async () => { const { settleDocuments } = await import('./git-document.mjs'); await settleDocuments(); });
+        retireHeldBoards();
+        tellOwner({ type: 'parked' });
+      } else {
+        grantGenerationWriter();
+        if (!started) {
+          tellOwner({ type: 'startup-step', phase: 'serving', step: 'starting the native board dispatcher', budget_ms: 65000 });
+          started = true; begin();
+        }
+        else {
+          takeEpoch(root, () => listBoards(root).map(slug => openBoard(root, slug)));
+          await registerGenerationOwner();
+          resumeDispatching();
+          admitGeneration();
+          // The loop's next admitted round supplies the serving receipt, also for a resumed predecessor.
+          generationServingDue = true;
+          wakeGeneration();
+        }
+      }
+    }).catch(error => { process.stderr.write(`board generation control: ${error.message}\n`); process.exit(1); });
+  };
+  const disconnected = () => { stopDispatching(); process.exit(1); };
+  process.on('message', receive); process.once('disconnect', disconnected);
+  // A transition cannot restore database files over committed card writes. Refuse a storage-code change
+  // until a compatible migration has its own protocol; retained generations must use the same storage contract.
+  const storage = createHash('sha256');
+  for (const file of ['store.mjs', 'files.mjs', 'ztrack.mjs', 'published.mjs']) storage.update(file).update(readFileSync(new URL(file, import.meta.url)));
+  tellOwner({ type: 'prepared', storage: storage.digest('hex') });
+  try { await activation; return await runVerb(argv); }
+  finally { process.off('message', receive); process.off('disconnect', disconnected); unwatchHealth(); unwatchWorkflow(); }
+}
+
+let generationServingDue = true;
+let wakeGeneration = () => {};
+let registerGenerationOwner = async () => {};
 async function serve(root, args = {}) {
   // Hermes's daemon flags: --interval seconds, --max starts per tick, --failure-limit, --pidfile, --verbose
   const override = Number(args.interval) > 0 ? { interval: Number(args.interval) } : {};
@@ -1876,7 +1972,7 @@ async function serve(root, args = {}) {
   let events;
   let fleetListeners = null, reloadListeners = () => {}, listenerRevision = 0, listenerBootstrapped = false;
   // a signal ends the round in progress with nothing new started (dispatch.mjs stopDispatching) and no round after it
-  const stop = () => { stopped = true; stopDispatching(); events?.close(); fleetListeners?.suspend(); };
+  const stop = () => { stopped = true; stopDispatching(); if (inBoardGeneration) stopGeneration(); events?.close(); fleetListeners?.suspend(); };
   for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(signal, stop);
   // what the serve says is kept in the home too (logs/workflow-serve.log), so why it stopped outlives its pane
   const kept = join(root, 'logs', 'workflow-serve.log');
@@ -1977,6 +2073,7 @@ async function serve(root, args = {}) {
     if (watched !== undefined && board) heldDocumentsWatched(board, id ?? key, watched);
     else if (uncertain && !board) heldDocumentsChanged();
   } });
+  wakeGeneration = () => events?.wake('generation-activated');
   // a machine's panes changing in its record (a session came up under its pane, a pane or its session ended) is what a
   // round binds a launch, verifies an adoption and reads a session's end from: the next round is due then
   const unfollowPanes = onPanesChanged(() => events?.wake('machine-record'));
@@ -1992,13 +2089,14 @@ async function serve(root, args = {}) {
   // panes the board launched (a close refused as "not started by this command").
   const registerOwner = async () => {
     let named = null, refusal = null;
-    try { named = await machineCall(null, 'harness.v1.boards.register', { root, claim: { pid: process.pid, ppid: process.ppid } }, { timeoutMs: 30_000 }); } catch (error) { refusal = error.message; }
+    try { named = await machineCall(null, 'harness.v1.boards.register', { root, claim: { pid: process.pid, ppid: process.ppid } }, { timeoutMs: inBoardGeneration ? 2000 : 30_000 }); } catch (error) { refusal = error.message; }
     const refused = named?.refused ?? null;
     log(refusal ? `board events: not published; the machine daemon did not take this home: ${refusal}`
       : refused ? `board events: registered, but the team refused this machine's credential (${refused.status}); nothing is published until it is re-enrolled`
       : named?.published === false ? `board ownership: registered locally; this machine has no team connector to publish events`
       : `board events: this home is published by the machine's connector`);
   };
+  registerGenerationOwner = registerOwner;
   await registerOwner();
   onLocalReopen(registerOwner);
   let listenerRecords = {}, listenerReloading = null, listenerReloadDue = false, listenerReading = null;
@@ -2060,6 +2158,7 @@ async function serve(root, args = {}) {
     })().finally(() => { listenerReloading = null; });
     return listenerReloading;
   };
+  if (inBoardGeneration && generationServingDue) tellOwner({ type: 'startup-step', phase: 'serving', step: 'reading the listener configuration through its orchestration door', budget_ms: 65000 });
   await reloadListeners();
   // Retry a failed home decode without waiting for a dispatch sweep. Reading the held stream also enforces its
   // heartbeat deadline and reconnects after local caller loss, even when every board's dispatching is off.
@@ -2082,11 +2181,12 @@ async function serve(root, args = {}) {
       // A serve never ticks on code older than the installed orchestrator: after its round it stops, and its keeper
       // starts the new one. Nothing waits for an installation; a second round, old or new, is harmless.
       const replaced = (() => { const now = installed(); return running && now && now !== running ? now : null; })();
-      if (replaced) { log(`orchestrator ${replaced} is installed (this serve runs ${running}); stopping, for its keeper to start the new one`); break; }
+      if (replaced && !inBoardGeneration) { log(`orchestrator ${replaced} is installed (this serve runs ${running}); stopping, for its keeper to start the new one`); break; }
       pausedSaid = Boolean(paused(root)) && pausedSaid;
       let interval = 60;
       let nextMailAt = Infinity;
       const began = Date.now();
+      if (inBoardGeneration && generationServingDue) tellOwner({ type: 'startup-step', phase: 'serving', step: 'completing the first native board round', budget_ms: 65000 });
       if (wakeReason) log(`dispatch wake ${wakeReason.sources.join(', ')}; event age ${began - wakeReason.at}ms`);
       wakeReason = null;
       const loopStep = async (name, fn) => { const at = performance.now(); try { return await fn(); } finally { noteStep(`owner loop: ${name}`, performance.now() - at); } };
@@ -2101,6 +2201,10 @@ async function serve(root, args = {}) {
         // Dispatching is a controller over the boards whose own state says it is on; the owner answers verbs either way.
         const dispatching = listBoards(root).filter((slug) => dispatchingOf(root, slug).on);
         const reports = dispatching.length ? await ownCall(() => tick({ root, lanes: state.lanes, settings, params, slugs: dispatching, deploymentReceipt: true })) : [];
+        if (inBoardGeneration && generationServingDue && reports.every(report => !report.error)) {
+          generationServingDue = false;
+          tellOwner({ type: 'serving', pid: process.pid, boards: listBoards(root) });
+        }
         // with dispatching off on every board the owner only answers verbs: no round, no delivery, nothing told
         if (dispatching.length) {
           round += 1;
@@ -2144,7 +2248,7 @@ async function serve(root, args = {}) {
         if (remaining > 0 && !stopped) await new Promise(done => setTimeout(done, remaining));
         moved = newer();
       }
-      if (moved) { log(`orchestrator ${moved} is installed (this serve runs ${running}); stopping, for its keeper to start the new one`); break; }
+      if (moved && !inBoardGeneration) { log(`orchestrator ${moved} is installed (this serve runs ${running}); stopping, for its keeper to start the new one`); break; }
     }
   } finally {
     fleetListeners.suspend(); clearInterval(listenerTimer); unfollowRecords(); unfollowPanes();

package/board/client.mjs

@@ -30,6 +30,15 @@ export async function runWorkflow(argv) {
   }
   const help = !verb || verb === 'help' || args.help;
   const root = help ? null : homeOf(args);
+  if (!help && verb === 'handover') return sendToOwner(root, argv, args);
+  if (!help && ['serve', 'daemon'].includes(verb)) {
+    const { inBoardGeneration } = await import('./generation.mjs');
+    if (inBoardGeneration) {
+      process.send({ type: 'startup-step', step: 'loading the board dispatcher', budget_ms: 8000 });
+      return (await import('./cli.mjs')).serveBoardGeneration(root, args, argv);
+    }
+    return (await import('./generation-owner.mjs')).serveBoardOwner(root, args);
+  }
   if (help || BOARD_OPERATION_VERBS.has(verb)) {
     // The board has one writer. An operation that writes the boards (exclusive, below) takes the home's lock itself
     // and so is that writer, refusing while an owner holds it. The rest only read, or are the owner itself (serve), and