@volter/supercode-orchestrator 0.5.211 → 0.5.213

package/board/dispatch.mjs

@@ -25,9 +25,9 @@ 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 { creatorOf, sessionProgress } from './workflow.mjs';
+import { cardSectionHeading, creatorOf, sessionProgress } from './workflow.mjs';
 import { boardLabel, boardName } from '@volter/teams/board-name';
 let fleetRoot = null;
 import { inspectCompletionEvidence, noCodeChange, openReviewPullRequests, reviewDue, withCompletionEvidence, withFreshReviewReads, reviewCandidate, workflowRevision, retainWorkflowTick } from './ci.mjs';
@@ -51,7 +51,7 @@ import { homedir, hostname, tmpdir, totalmem } from 'node:os';
 import { basename, dirname, join } from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
-import { view, boardCopyOf, boardKey, boardPath, cardHandleOf, readableIdOf, briefPath, claimer, claimHolds, copyRefusal, event, json, listBoards, logsDir, newClaim, now, NOTICE_RUN_IDS, openBoard, pendingLaunches, sessionBound, setActor, storageFault, tx } from './store.mjs';
+import { view, boardCopyOf, boardKey, boardPath, cardHandleOf, readableIdOf, briefPath, claimer, claimHolds, copyRefusal, event, json, listBoards, logsDir, newClaim, now, NOTICE_RUN_IDS, openBoard, openBoardSnapshot, pendingLaunches, sessionBound, setActor, storageFault, tx } from './store.mjs';
 import { doors, fire, loadWorkflow, resumeOf, runSpec, runWorkingSeconds, requestSessionClose, retireSupersededRuns, refreshCardInputs, refreshRelationAnswers, transitionsFor, scopeOf, statusOf, projectStatus, storedStatus, templateValue, workflowFor } from './workflow.mjs';
 import { checkWorkspace, assertWorkspaceOwner, notePresence, resolveWorkspace } from './workspace.mjs';
 import { capacity, dispatched, executionHost, harnessDefaults, holdings } from './capacity.mjs';
@@ -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. */
@@ -830,7 +864,14 @@ async function homeHoldings(root, slugs, lanes, fleet, entry) {
   const out = [];
   for (const slug of slugs) {
     try {
-      const b = openBoard(root, slug);
+      // Capacity spans awaits. It needs its own committed snapshot, not the shared writer's total_changes counter:
+      // unrelated owner calls and delivery writes used to invalidate all three attempts at this read.
+      let b;
+      try { b = openBoardSnapshot(root, slug); }
+      catch (error) {
+        if (error.code !== 'board_read_by_owner') throw error;
+        b = openBoard(root, slug); // files/non-WAL backings retain their guarded optimistic read
+      }
       try {
         b.slug ??= slug; b.label ??= boardLabel(root, slug);
         // each run's session read before it is counted live or not (unknown stays unknown)
@@ -840,7 +881,7 @@ async function homeHoldings(root, slugs, lanes, fleet, entry) {
           runLaneOf: row => runLane(b.db, b, entry, getTask(b.db, row.id), lanes) }));
       }
       finally { b.close(); }
-    } catch (error) { if (error.capacityUnread) throw error; /* its own tick reports other board errors */ }
+    } catch (error) { error.capacityUnread = true; throw error; }
   }
   out.defaults = harnessDefaults(out);
   return out;
@@ -927,6 +968,9 @@ async function startCards(board, fleet, lanes, settings, report, entry, effects,
     if (task.subtask_of || task.current_run_id) continue;
     const state = scopeFor(task).card;
     if (state.archived || ['done', 'cancelled'].includes(state.status)) continue;
+    if (state.status === 'running' && completedWork(board.db, task.id)) {
+      waiting(task, 'work is complete; the board must select its independent review before another implementer run'); continue;
+    }
     if (state.detached) { waiting(task, `session belongs to ${state.detached.person}; verified adoption is required`); continue; }
     if (state.dispatch_hold) { waiting(task, 'dispatch held: an explicit start or verified adoption must release it'); continue; }
     if (workflow.run && state.paused) { waiting(task, `paused: ${state.paused.reason ?? 'manager pause'}`); continue; }
@@ -991,7 +1035,7 @@ async function startCards(board, fleet, lanes, settings, report, entry, effects,
         const refused = caps.admit(waitingEntries[i], scope, waitingEntries);
         if (refused) throw Object.assign(new Error(refused.why), { claimedElsewhere: true });
         assertWorkspaceOwner(db, task, checked);
-        if (checked) db.prepare('UPDATE supercode_cards SET workspace_root=? WHERE task_id=?').run(checked.mainRoot, task.id);
+        if (checked) db.prepare('UPDATE supercode_cards SET workspace_root=? WHERE task_id=?').run(checked.workspaceRoot, task.id);
         if (!task.assignee && plan.profile) {
           db.prepare('UPDATE tasks SET assignee = ? WHERE id = ?').run(plan.profile, task.id);
           event(db, task.id, 'assigned', { assignee: plan.profile, source: 'workflow role' });
@@ -1076,7 +1120,7 @@ async function launchAttempt(board, entry, id, lane, fleet, settings, runId) {
   const checked = await checkWorkspace(board, task);
   if (checked) runTx(board, id, runId, (db) => {
     assertWorkspaceOwner(db, task, checked);
-    db.prepare('UPDATE supercode_cards SET workspace_root=? WHERE task_id=?').run(checked.mainRoot, id);
+    db.prepare('UPDATE supercode_cards SET workspace_root=? WHERE task_id=?').run(checked.workspaceRoot, id);
   });
   const status = view(board, (db) => statusOf(db, task));
   const spec = runSpec(entry, status, task);
@@ -1209,7 +1253,7 @@ export async function startCard(board, id, { roles = ['manager'], lanes, setting
   const moved = tx(board, (db) => {
     if (detachedCard(db, id)) throw new Error(`${id} is detached to a person; request and verify adoption before starting it`);
     assertWorkspaceOwner(db, before, checked);
-    if (checked) db.prepare('UPDATE supercode_cards SET workspace_root=? WHERE task_id=?').run(checked.mainRoot, id);
+    if (checked) db.prepare('UPDATE supercode_cards SET workspace_root=? WHERE task_id=?').run(checked.workspaceRoot, id);
     if (!roles.some(role => ['manager', 'creator'].includes(role))) throw new Error('Only the manager or creator starts a held card; request its decision.');
     event(db, id, 'dispatch_released', { reason: 'explicit start' });
     requestSessionClose(db,id);
@@ -1450,7 +1494,7 @@ export async function closeRequested(board, report, { taskId = null, caller = nu
         continue;
       }
     }
-    if (session?.monitor_held && !session.close_requested) continue; // only an explicit close action ends this process
+    if ((session?.monitor_held || session?.retain_after_run) && !session.close_requested) continue; // only an explicit close action ends this process
     if ((!session?.pane && session?.surface !== 'native') || session.close_transferred_to || session.close_confirmed_at || (!row.ended_at && !session.close_requested)) continue;
     if (caller && session.session_id === caller) continue; // let the command that ended its own run return
     // The board closes only what it launched. An adopted session (a person's own thread, a hook session the card was
@@ -1617,7 +1661,18 @@ async function observeIdle(board, fleet, settings, report, entry, effects) {
     return Number(rows?.find((row) => row.locator?.session_id === session.session_id)?.updated_at_ms) || null;
   };
   const managers = [].concat(entry.params.managers ?? []).filter(Boolean);
-  const delegations = localSessionDelegations(board.root, localMachine());
+  const running = board.db.prepare(entry.workflow.run ? "SELECT id FROM tasks WHERE current_run_id IS NOT NULL" : "SELECT id FROM tasks WHERE status = 'running'").all();
+  const edges = localSessionDelegations(board.root, localMachine());
+  const reached = new Set(running.map(({ id }) => addressOf(currentRun(board.db, id)?.metadata?.supercode)).filter(Boolean));
+  const delegations = [];
+  const pending = [...reached];
+  const byStarter = new Map();
+  for (const edge of edges) { const children = byStarter.get(edge.starter) ?? []; children.push(edge); byStarter.set(edge.starter, children); }
+  while (pending.length) for (const edge of byStarter.get(pending.pop()) ?? []) {
+    delegations.push(edge);
+    if (!reached.has(edge.session)) { reached.add(edge.session); pending.push(edge.session); }
+  }
+  report.idle_delegations = { recorded: edges.length, reachable: delegations.length };
   const delegatedReadings = [...fleet.sessions];
   // Forks and concurrent sessions need not have a pane. Read only the exact
   // native identities this home's starter receipts name, before any write.
@@ -1633,7 +1688,6 @@ async function observeIdle(board, fleet, settings, report, entry, effects) {
       if (row?.activity) delegatedReadings.push({ address, state: row.activity.presence, turn: row.activity.turn });
     } catch { /* an unread child is never called working */ }
   }
-  const running = board.db.prepare(entry.workflow.run ? "SELECT id FROM tasks WHERE current_run_id IS NOT NULL" : "SELECT id FROM tasks WHERE status = 'running'").all();
   // every running card a session is on: a session waiting on its user is told once, naming them all
   const cardsOf = new Map();
   for (const { id } of running) {
@@ -1720,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;
       }
@@ -2284,6 +2350,10 @@ async function launchPane(board, task, runId, lane, fleet, { input = null, slot
   const pending = view(board, (db) => db.prepare('SELECT id, ended_at, metadata FROM task_runs WHERE task_id = ? AND id != ?').all(task.id, runId))
     .map((r) => ({ ...r, session: json(r.metadata, {})?.supercode }))
     .find((r) => (r.session?.pane || r.session?.launch_key || r.session?.surface === 'native') && !r.session.close_transferred_to && (r.session.slot ?? 'worker') === slot && (r.ended_at || r.session.close_requested) && !r.session.close_confirmed_at
+      // Deliberate retention owes no close. Only this slot's latest identity may reach the liveness/continuation
+      // checks below; an explicit close or another unresolved identity still holds the slot.
+      && !(r.session.retain_after_run && !r.session.close_requested && !r.session.forgotten && last?.session_id
+        && r.session.session_id === last.session_id && r.session.pane === last.pane && r.session.machine === machine && (r.session.harness ?? 'claude-code') === harness)
       && !(closeRefused(r.session) && last?.session_id && r.session.session_id === last.session_id));
   if (pending) throw unavailable(`slot ${slot} still owns pane ${pending.session.pane} from run ${pending.id}; closure must be confirmed before another session starts: ${pending.session.close_error ?? 'close pending'}`);
   let prev = view(board, (db) => lastSession(db, task.id, slot));
@@ -2431,21 +2501,9 @@ async function launchPane(board, task, runId, lane, fleet, { input = null, slot
     if (next === 'refuse') throw new Error(`session ${prev.session_id} still has live pane ${prev.pane}; cannot resume or replace it`);
     if (next === 'keep') {
       // 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, ...kept } = prev;
+      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 });
-        // 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 };
@@ -2506,6 +2564,7 @@ async function launchPane(board, task, runId, lane, fleet, { input = null, slot
     const saved = json(row?.metadata, {})?.supercode;
     if (saved?.address === session.address && !saved.launch_pending) return true;
     setRunSession(db, runId, session);
+    transferRetainedSession(db, task.id, runId, session);
     event(db, task.id, kind, { session_id: session.session_id, machine, pane: session.pane, address: session.address, mode: session.mode, ...(replaced ? { replaced } : {}) }, runId);
     // the working session hears updates to its card; the slot's previous session no longer does (a reviewer starting
     // leaves the implementer's, and a subtask's arc session's, subscription alone)
@@ -2517,9 +2576,26 @@ 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;
 }
 
+/** A continued role identity now belongs to its new attempt. Preserve the completed receipt, and keep an old
+ * retained reference from closing the same native process/pane later. Transfer only after a successful bind. */
+function transferRetainedSession(db, id, runId, session) {
+  if (!session?.session_id) return;
+  for (const row of db.prepare('SELECT id,metadata FROM task_runs WHERE task_id=? AND id<? AND ended_at IS NOT NULL').all(id, runId)) {
+    const old = json(row.metadata, {})?.supercode;
+    if (!old?.retain_after_run || old.close_requested || old.close_confirmed_at || old.close_transferred_to || old.forgotten
+      || old.session_id !== session.session_id || old.machine !== session.machine || (old.slot ?? 'worker') !== (session.slot ?? 'worker')) continue;
+    setRunSession(db, row.id, { close_transferred_to: runId });
+    event(db, id, 'session_transferred', { successor: runId, session_id: old.session_id, pane: old.pane ?? null }, row.id);
+  }
+}
+
 /** The agent a slot's last session belongs to, when it is not the agent this run's `meta` names: the agent store's
  *  owner of the session where it records one in this run's org, else the agent its own run ran as. Null when it is
  *  this run's agent, or no agent is known for it (a session from before card agents). */
@@ -2776,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
@@ -2790,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);
@@ -2800,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;
   };
@@ -2816,8 +2905,9 @@ async function adoptSession(board, id, who, { request = null, open = request, pr
   // agent store another, and every round after would trip on it.
   const owner = agent ? agentRunForSession(board.root, [`${harness}:${sessionId}`]) : null;
   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}`);
-  // the card's previous session is read before the bind decides whether it is still live
-  await readBefore(fleet, view(board, (db) => lastSession(db, 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.
+  await readBefore(fleet, view(board, (db) => lastSession(db, id, adoptionSlot)));
   const adopted = tx(board, (db) => {
     const task = getTask(db, id);
     if (!task) throw new Error(`no card ${id}`);
@@ -2826,10 +2916,10 @@ async function adoptSession(board, id, who, { request = null, open = request, pr
     if (changed) throw changed;
     if (beforeRun && assignee && assignee !== task.assignee) throw new Error('rebinding a session does not reassign its active run');
     if (task.machine && normalMachine(task.machine) !== host) throw new Error(`${id} runs on ${task.machine}, and ${found.address} is on ${host}; move the card first`);
-    const was = lastSession(db, id);
+    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 }); }
@@ -2863,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');
@@ -3526,14 +3622,37 @@ export async function plan({ root, lanes, settings, slugs = null, params = {} })
   return out;
 }
 
+/** An explicit completion of the latest attempt, after any previous review or reopening. A reclaimed or failed
+ * attempt is not a completed disposition, and a new attempt or returned verdict invalidates the old receipt. */
+function completedWork(db, id) {
+  const last = db.prepare(`SELECT id,kind,run_id FROM task_events WHERE task_id=?
+    AND kind IN ('work_completed','review_requested','changes_requested','review_pass','review_voided','reopened')
+    ORDER BY id DESC LIMIT 1`).get(id);
+  if (last?.kind !== 'work_completed') return null;
+  const attempt = db.prepare('SELECT id,outcome,ended_at FROM task_runs WHERE task_id=? ORDER BY id DESC LIMIT 1').get(id);
+  return attempt?.id === last.run_id && attempt.outcome === 'completed' && attempt.ended_at != null ? last : null;
+}
+
+/** Finish ends the attempt, not its caller's native turn. Keep observing that retained attempt until the board
+ * requests review; the receipt's lifecycle/latest-attempt fence prevents an older session holding later work. */
+function reviewTurnRun(db, id) {
+  const active = currentRun(db, id);
+  if (active) return active;
+  const completed = completedWork(db, id);
+  if (!completed || detachedCard(db, id)) return null;
+  const row = db.prepare('SELECT * FROM task_runs WHERE id=?').get(completed.run_id);
+  const metadata = json(row?.metadata, {}) ?? {}, session = metadata.supercode;
+  return row && session?.retain_after_run && !session.close_transferred_to && !detachedSession(db, session) ? { ...row, metadata } : null;
+}
+
 /** Whether an arc with no open PR may be one that changed no code and is due its review: it has done work, by filing
- *  tasks or by a run that ended with an Acceptance outcome ticked (a fresh arc with neither has not started), and no
+ *  tasks, an explicit completed-work receipt, or a completed run with an Acceptance outcome ticked, and no
  *  review of it is pending or passed (after changes are requested, closing the tasks that own the findings makes it
  *  due again). */
 function noCodeReviewDue(board, id) {
   return view(board, (db) => {
     const filed = db.prepare('SELECT 1 FROM supercode_cards WHERE subtask_of = ? LIMIT 1').get(id);
-    if (!filed && !(db.prepare('SELECT 1 FROM task_runs WHERE task_id = ? AND ended_at IS NOT NULL LIMIT 1').get(id) &&
+    if (!filed && !completedWork(db, id) && !(db.prepare("SELECT 1 FROM task_runs WHERE task_id = ? AND outcome = 'completed' AND ended_at IS NOT NULL LIMIT 1").get(id) &&
       outcomeTicked(db.prepare('SELECT body FROM tasks WHERE id = ?').get(id)?.body))) return false;
     const last = db.prepare("SELECT kind FROM task_events WHERE task_id = ? AND kind IN ('review_requested', 'changes_requested', 'review_pass','review_voided') ORDER BY id DESC LIMIT 1").get(id);
     return !last || ['changes_requested','review_voided'].includes(last.kind);
@@ -3549,8 +3668,8 @@ function passedReview(board, id) {
 function outcomeTicked(body) {
   let acceptance = false;
   return String(body ?? '').split('\n').some((line) => {
-    const heading = /^#{1,6}\s+(.+?)\s*$/.exec(line);
-    if (heading) acceptance = heading[1].toLowerCase() === 'acceptance';
+    const heading = cardSectionHeading(line);
+    if (heading !== null) acceptance = heading === 'acceptance';
     return acceptance && /^\s*[-*] \[[xX]\] \S/.test(line);
   });
 }
@@ -3571,7 +3690,7 @@ function outcomeTicked(body) {
  *  running a proof, still holds the review. */
 async function turnInFlight(board, id, fleet, heldSince = null) {
   if (!fleet?.ok) return null;
-  const session = currentRun(board.db, id)?.metadata?.supercode;
+  const session = reviewTurnRun(board.db, id)?.metadata?.supercode;
   if (!session?.session_id || session.surface === 'headless' || session.close_requested) return null;
   let live = fleet.sessions?.find((x) => x.address === addressOf(session)) ?? null;
   if (live?.turn == null && session.surface === 'native') try {
@@ -3596,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] : [])));
@@ -3643,22 +3763,22 @@ async function activatePullRequestReviews(board, entry, report, effects, { only
       }
       // A native turn holds the advisory proposal before authoritative source reads. Retain the proposal on the run
       // (`review_held`) so a goal turn can be told to have started after that work was first observed.
-      const heldRun = currentRun(board.db, id), dueKey = reviewDueKey(board, id, payload);
+      const heldRun = reviewTurnRun(board.db, id), dueKey = reviewDueKey(board, id, payload);
       const held = heldRun?.metadata?.supercode?.review_held?.key === dueKey ? heldRun.metadata.supercode.review_held : null;
       const inTurn = await turnInFlight(board, id, fleet, held ? Number(held.since) : null);
       if (inTurn) {
-        if (!held && !dry && heldRun) tx(board, (db) => { if (currentRun(db, id)?.id === heldRun.id) setRunSession(db, heldRun.id, { review_held: { key: dueKey, since: now() } }); });
+        if (!held && !dry && heldRun) tx(board, (db) => { if (reviewTurnRun(db, id)?.id === heldRun.id) setRunSession(db, heldRun.id, { review_held: { key: dueKey, since: now() } }); });
         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');
@@ -3902,7 +4022,7 @@ export async function tick({ root, lanes, settings, only = null, slugs = null, d
       if (dispatch && !only && !report.paused) await observeIdle(board, fleet, settings, report, entry, effects);
       // what the moves asked for is recorded with them; the delivery pass (`deliver`) carries it out, outside the round
       queueEffects(board, effects);
-      phase('goals');
+      phase('idle');
       ensureSubscriptions(board, entry);
       fireHooks(board, settings, report);
       if (String(board.db.prepare('PRAGMA journal_mode').get()?.journal_mode).toLowerCase() === 'wal') board.db.prepare('PRAGMA wal_checkpoint(PASSIVE)').get();

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;
 }
@@ -292,7 +292,7 @@ export function createCard(board, spec) {
     const handle = cardHandle(boardKey(board.root, board.slug), numberOf(db, id));
     if (namedBranch) run(db, 'UPDATE tasks SET branch_name = ? WHERE id = ?', handle ? namedBranch(handle) : `wt/${id}`, id);
     const machine = spec.machine ?? arc?.machine ?? null;
-    run(db, 'INSERT OR REPLACE INTO supercode_cards (task_id,machine,subtask_of,workspace_anchor,workspace_root,tags,requested_by_unverified) VALUES (?,?,?,?,?,?,?)', id, machine, arc?.id ?? null, declared.repository, checked?.mainRoot ?? null,
+    run(db, 'INSERT OR REPLACE INTO supercode_cards (task_id,machine,subtask_of,workspace_anchor,workspace_root,tags,requested_by_unverified) VALUES (?,?,?,?,?,?,?)', id, machine, arc?.id ?? null, declared.repository, checked?.workspaceRoot ?? null,
       tags.length ? JSON.stringify(tags) : null, spec.requestedByUnverified ? JSON.stringify(spec.requestedByUnverified) : null);
     for (const p of parents) addDependency(db, entry, id, p);
     // where it starts is the workflow's `initial` (Hermes: triage, blocked, todo behind open parents, else ready)
@@ -740,17 +740,26 @@ export const editResult = (board, id, { result, summary = null, metadata = undef
 export const heartbeat = (board, id, note = null, { roles, until = null } = {}) => act(board, id, 'heartbeat', { roles, payload: { note, until } });
 export const setGoal = (board, id, { on = true, maxTurns = null, roles } = {}) => act(board, id, 'set_goal', { roles, payload: { goal: Boolean(on), max_turns: on ? maxTurns : null } });
 
-/** A triage card fans out into children it waits on (Hermes's decomposer); answers their ids. */
+/** File the named card's tasks only if its workflow accepts decompose; refusal leaves no cards behind. */
 export async function decompose(board, id, children, { author = 'user', roles } = {}) {
   if (!children.length) throw new Error('decompose names at least one child (--child "<title>[@<assignee>]")');
-  const task = view(board, (db) => must(db, id));
-  const ids = [];
-  for (const c of children) ids.push(createCard(board, await prepareCard(board, {
-    title: c.title, body: c.body ?? null, assignee: c.assignee ?? task.assignee, machine: task.machine,
-    workspace: task.workspace_anchor ? `${task.workspace_kind}:${task.workspace_anchor}` : task.workspace_path ? `${task.workspace_kind}:${task.workspace_path}` : task.workspace_kind, tenant: task.tenant, createdBy: author,
-  })).id);
-  await act(board, id, 'decompose', { roles, payload: { children: ids, author } });
-  return ids;
+  const entry = await loadWorkflow(board.root);
+  await refreshCardInputs(board, id);
+  const result = tx(board, db => {
+    const task = must(db, id), sender = roles ?? callerRoles(db, id);
+    if (task.subtask_of) throw new Error(`${id} is itself a subtask of ${task.subtask_of}; decompose its arc instead`);
+    // Creation and authorization share this transaction. Guards see the actual child ids, and any refusal
+    // (including a later child's invalid spec) rolls back every child, event, subscription and queued effect.
+    const ids = children.map(c => createCard(board, {
+      title: c.title, body: c.body ?? null, assignee: c.assignee ?? task.assignee, machine: task.machine,
+      subtaskOf: id, workspace: 'scratch', tenant: task.tenant, createdBy: author,
+    }).id);
+    const move = fire(db, board, entry, id, 'decompose', { roles: sender, payload: { children: ids, author } });
+    for (const child of ids) settle(db, board, entry, child, move.effects);
+    return { ids, effects: move.effects };
+  });
+  await runEffects(board, result.effects);
+  return result.ids;
 }
 
 /** `child` waits for `parent`. */