@volter/supercode-orchestrator 0.5.193 → 0.5.195

package/board/capacity.mjs

@@ -16,6 +16,13 @@ const GROUP = {
 /** The fleet statuses of a session in a turn (`waiting`: a turn stopped on a question it asked). */
 const IN_TURN = new Set(['busy', 'waiting']);
 
+// A kept dispatcher session is recorded as adopt too, but retains its launch key. An unissued claim reserves a
+// place; a deferred launch has not started a session and waits for admission on its retry.
+export const dispatched = (s) => Boolean(s?.launch_key || s?.surface === 'headless' || ['fresh', 'resume'].includes(s?.mode) || (!s?.mode && !s?.launch_deferred));
+
+// Headless workers execute on the board host; only panes execute on their named target.
+export const executionHost = (lane, target, home, normalise) => lane?.surface === 'pane' ? normalise(target ?? home) : home;
+
 /** Whether `thing` (a counted card or session, or a card being started) is one the filter is about. */
 export function matches(filter, thing) {
   for (const [key, names] of Object.entries(filter ?? {})) {
@@ -31,10 +38,10 @@ const applies = (cap, thing) => matches(cap.where, thing) && !(Object.keys(cap.u
 /** Each slot's latest recorded session on a card (implementer `worker`, `reviewer`, …), newest run first. */
 function sessionsOf(db, taskId) {
   const out = new Map();
-  for (const row of db.prepare('SELECT metadata FROM task_runs WHERE task_id = ? AND metadata IS NOT NULL ORDER BY id DESC').all(taskId)) {
+  for (const row of db.prepare('SELECT id, metadata FROM task_runs WHERE task_id = ? AND metadata IS NOT NULL ORDER BY id DESC').all(taskId)) {
     const s = json(row.metadata, {})?.supercode;
     const slot = s?.slot ?? 'worker';
-    if (s?.session_id && !out.has(slot)) out.set(slot, s);
+    if (s?.session_id && !out.has(slot)) out.set(slot, { ...s, run: row.id });
   }
   return out;
 }
@@ -46,7 +53,7 @@ function sessionsOf(db, taskId) {
  * own transcript reports it runs, or null where none can be read; `machineOf` normalises a machine name; `lanes` gives
  * a profile's harness and model.
  */
-export function holdings(board, { lanes, fleetOk, alive, liveRecord, modelOf = () => null, storedOf = null, machineOf, home = null }) {
+export function holdings(board, { lanes, fleetOk, alive, liveRecord, modelOf = () => null, storedOf = null, machineOf, home = null, runLaneOf = null }) {
   const out = [];
   const rows = board.db.prepare("SELECT t.id, t.status, t.assignee, t.current_run_id, t.model_override, c.machine, c.subtask_of FROM tasks t LEFT JOIN supercode_cards c ON c.task_id = t.id WHERE t.status != 'archived'").all();
   for (const row of rows) {
@@ -64,14 +71,16 @@ export function holdings(board, { lanes, fleetOk, alive, liveRecord, modelOf = (
     const sessionOf = (s, slot) => {
       const configured = s.model ?? card.model;
       return { ...card, counts: 'sessions', slot, session: s.session_id ?? null, unconfigured: !configured,
-        machine: s.machine ? machineOf(s.machine) : card.machine, harness: s.harness ?? card.harness ?? 'claude-code',
+        dispatch: dispatched(s), run: s.run ?? null,
+        machine: s.surface === 'headless' ? home : s.machine || s.surface ? machineOf(s.machine ?? row.machine ?? home)
+          : executionHost(runLaneOf ? runLaneOf(row) : lane, row.machine, home, machineOf), harness: s.harness ?? card.harness ?? 'claude-code',
         model: (s.session_id ? modelOf(s) : null) ?? configured };
     };
     const sessions = fleetOk ? sessionsOf(board.db, row.id) : new Map();
     const held = [];
     let current = null;
     if (row.current_run_id) {
-      current = json(board.db.prepare('SELECT metadata FROM task_runs WHERE id = ?').get(row.current_run_id)?.metadata, {})?.supercode ?? {};
+      current = { ...json(board.db.prepare('SELECT metadata FROM task_runs WHERE id = ?').get(row.current_run_id)?.metadata, {})?.supercode, run: row.current_run_id };
       out.push({ ...sessionOf(current, current.slot ?? 'worker'), session: undefined, slot: undefined, counts: 'runs' });
     }
     for (const [slot, s] of sessions) {
@@ -114,6 +123,7 @@ export function harnessDefaults(held) {
  */
 export function capacity(caps, held, evaluate) {
   const list = (caps ?? []).map((cap) => ({ ...cap, where: cap.where ?? {} }));
+  const trackDispatcherSlots = list.some(cap => cap.counts === 'sessions' && cap.where.dispatch === true);
   // shared by every board of a tick, so what one board starts counts on the next
   const things = held;
   const counted = (cap, group) => things.filter((x) => x.counts === cap.counts && applies(cap, x) && GROUP[cap.scope](x) === group);
@@ -138,7 +148,8 @@ export function capacity(caps, held, evaluate) {
      * start. `scope` evaluates each max; `waiting` is every card still to be planned this tick, for reserves (a waiting card
      * the cap counts already takes no new place, so none is held for it). A card
      * that already holds a place in a count (its implementer's live session while its review starts) keeps it: that
-     * cap does not hold it.
+     * cap does not hold it. A dispatcher-only sessions cap keeps a place only for the same slot: review is another
+     * session, so it must have room.
      */
     admit(entry, scope, waiting = []) {
       for (const cap of list) {
@@ -147,7 +158,8 @@ export function capacity(caps, held, evaluate) {
         if (max === null || max === undefined || max === '') continue;
         const group = GROUP[cap.scope](entry);
         const now = counted(cap, group);
-        if (now.some((x) => x.card === entry.card)) continue;
+        const bySlot = cap.counts === 'sessions' && cap.where.dispatch === true;
+        if (now.some((x) => x.card === entry.card && (!bySlot || x.slot === entry.slot))) continue;
         const reserved = cap.reserve && !matches(cap.reserve.for, entry) && waiting.some((w) => w.card !== entry.card && matches(cap.reserve.for, w) && GROUP[cap.scope](w) === group && !now.some((x) => x.card === w.card))
           ? Number(evaluate(cap.reserve.slots, scope) ?? 0) : 0;
         if (now.length >= Number(max) - reserved) {
@@ -160,11 +172,13 @@ export function capacity(caps, held, evaluate) {
     },
     /**
      * Count `entry` as started: its run, its card, its session (in a turn from its first prompt) and its start. What the card
-     * already holds is not counted again: the run takes the place its card holds.
+     * already holds is not counted again: the run takes the place its card holds. Dispatcher sessions are retained
+     * separately by slot so two reviews started in one round cannot share one place.
      */
     take(entry) {
       for (const counts of ['runs', 'cards', 'sessions', 'turns', 'starts']) {
-        const had = things.find((x) => x.card === entry.card && x.counts === counts);
+        const had = things.find((x) => x.card === entry.card && x.counts === counts &&
+          (!trackDispatcherSlots || !entry.dispatch || !['sessions', 'turns'].includes(counts) || (x.dispatch && x.slot === entry.slot)));
         // the card is counted already: it is now in the status its start moved it to
         // the start is the card's next run, in its assignee's harness and model now (a card reassigned from Codex to
         // Claude Code counts against Claude Code's caps from this start, not as the harness its last session ran)

package/board/dispatch.mjs

@@ -44,7 +44,7 @@ import { fileURLToPath } from 'node:url';
 import { view, boardCopyOf, boardPath, briefPath, claimer, claimHolds, copyRefusal, event, json, listBoards, logsDir, newClaim, now, openBoard, 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, harnessDefaults, holdings } from './capacity.mjs';
+import { capacity, dispatched, executionHost, harnessDefaults, holdings } from './capacity.mjs';
 import { evaluate, holds, render } from './expr.mjs';
 import { identifyNotice } from './notices.mjs';
 import { pendingRequestMail } from './request-mail.mjs';
@@ -391,6 +391,13 @@ export function lanesOf(profiles = {}) {
   return out;
 }
 
+/** The current run's role can select a different execution surface from the card's assignee. */
+function runLane(db, board, entry, task, lanes) {
+  const spec = runSpec(entry, statusOf(db, task), task);
+  const profile = spec ? evaluate(entry.workflow.roles?.[spec.role] ?? 'card.assignee', scopeOf(db, board, task, { params: entry.params })) : task.assignee;
+  return lanes[profile] ?? {};
+}
+
 // The latest presence reading (observeFleet). A machine that did not answer it (offline, or unread this round) is not
 // asked again until the next reading: each remote call would wait out its timeout, and one silent machine held every
 // close and launch on this one. Its door answers `machine_offline`, which every caller tries again next round.
@@ -754,7 +761,8 @@ async function homeHoldings(root, slugs, lanes, fleet, entry) {
         // each run's session read before it is counted live or not (unknown stays unknown)
         for (const r of b.db.prepare('SELECT r.metadata FROM tasks t JOIN task_runs r ON r.id = t.current_run_id').all()) await readBefore(fleet, json(r.metadata, {})?.supercode);
         const storedOf = (id) => storedStatus(b.db, b, entry, id).stored;
-        out.push(...holdings(b, { lanes, fleetOk: fleet.ok, alive: (s) => sessionAlive(fleet, s), liveRecord: live, modelOf: transcriptModel, storedOf, machineOf: normalMachine, home: localMachine() }));
+        out.push(...holdings(b, { lanes, fleetOk: fleet.ok, alive: (s) => sessionAlive(fleet, s), liveRecord: live, modelOf: transcriptModel, storedOf, machineOf: normalMachine, home: localMachine(),
+          runLaneOf: row => runLane(b.db, b, entry, getTask(b.db, row.id), lanes) }));
       }
       finally { b.close(); }
     } catch { /* its own tick reports it */ }
@@ -851,7 +859,7 @@ async function startCards(board, fleet, lanes, settings, report, entry, effects,
     if (!startable.has(state.status)) { waiting(task, `no ${d.start} transition from ${state.status}`); continue; }
     const plan = planOf(task, scopeFor(task));
     if (!plan) { waiting(task, `start guard refused: ${transitionsFor(workflow, state.status, d.start).map(t => t.guard ?? 'sender role').join(' | ')}`); continue; }
-    const scope = scopeFor(task, { lane: plan.lane ?? {}, run: { surface: plan.lane?.surface ?? null, local: plan.lane?.surface !== 'pane' || normalMachine(task.machine ?? '') === localMachine() } });
+    const scope = scopeFor(task, { lane: plan.lane ?? {}, run: { surface: plan.lane?.surface ?? null, local: executionHost(plan.lane, task.machine, localMachine(), normalMachine) === localMachine() } });
     if (!holds(d.eligible ?? null, scope)) { waiting(task, `dispatch eligibility refused (memory ${pressure}, local starts ${tickState.local_started}): ${d.eligible}`); continue; }
     candidates.push({ task, plan, scope });
   }
@@ -867,7 +875,8 @@ async function startCards(board, fleet, lanes, settings, report, entry, effects,
   });
   // the caps, over what the home holds now; what each candidate would be once started
   const caps = capacity(d.capacity, held, evaluate);
-  const entryOf = (c) => ({ card: c.task.id, board: board.slug, machine: normalMachine(c.task.machine ?? localMachine()), assignee: c.plan.profile ?? null,
+  const entryOf = (c) => ({ card: c.task.id, board: board.slug, machine: executionHost(c.plan.lane, c.task.machine, localMachine(), normalMachine), assignee: c.plan.profile ?? null,
+    dispatch: true, slot: String(templateValue(c.plan.runSpec?.session ?? 'worker', c.scope) ?? 'worker'),
     status: c.plan.target, stored: c.plan.target, model: c.task.model_override ?? c.plan.lane?.model ?? held.defaults?.[c.plan.lane?.harness] ?? null, harness: c.plan.lane?.harness ?? null });
   const waitingEntries = candidates.map(entryOf);
   // a dry run (dispatch --dry-run) plans the same way and writes nothing: no notes, no moves, no launches
@@ -882,7 +891,7 @@ async function startCards(board, fleet, lanes, settings, report, entry, effects,
     if (!why) why = launcherCheck(board.db, task, plan.lane, fleet);
     if (why) { note(task.id, why); report.queued.push([task.id, why]); continue; }
     if (dry) {
-      report.would.push({ id: task.id, status: plan.target, role: plan.runSpec?.role ?? null, assignee: plan.profile, machine: task.machine ?? null, surface: plan.lane.surface });
+      report.would.push({ id: task.id, status: plan.target, role: plan.runSpec?.role ?? null, assignee: plan.profile, machine: waitingEntries[i].machine, surface: plan.lane.surface });
       caps.take(waitingEntries[i]);
       continue;
     }
@@ -895,9 +904,13 @@ async function startCards(board, fleet, lanes, settings, report, entry, effects,
         // still waits where it did and still fits.
         const now = getTask(db, task.id);
         if (!now || now.current_run_id || now.archived || statusOf(db, now) !== scope.card.status) throw Object.assign(new Error('started or moved by another round'), { claimedElsewhere: true });
-        for (const row of db.prepare('SELECT t.id, t.assignee, t.model_override, c.machine FROM tasks t LEFT JOIN supercode_cards c ON c.task_id = t.id WHERE t.current_run_id IS NOT NULL').all()) {
+        for (const row of db.prepare('SELECT t.id, t.assignee, t.model_override, c.machine, r.metadata FROM tasks t LEFT JOIN supercode_cards c ON c.task_id = t.id JOIN task_runs r ON r.id=t.current_run_id WHERE t.current_run_id IS NOT NULL').all()) {
           const lane = lanes[row.assignee] ?? {}, status = statusOf(db, row);
-          caps.take({ card: row.id, board: board.slug, machine: normalMachine(row.machine ?? localMachine()), assignee: row.assignee ?? null, status, stored: status, model: row.model_override ?? lane.model ?? null, harness: lane.harness ?? null });
+          const session = json(row.metadata, {})?.supercode ?? {};
+          const host = session.surface === 'headless' ? localMachine() : session.machine || session.surface ? normalMachine(session.machine ?? row.machine ?? localMachine())
+            : executionHost(runLane(db, board, entry, getTask(db, row.id), lanes), row.machine, localMachine(), normalMachine);
+          caps.take({ card: row.id, board: board.slug, machine: host, assignee: row.assignee ?? null, status, stored: status, model: row.model_override ?? lane.model ?? null, harness: lane.harness ?? null,
+            dispatch: dispatched(session), slot: session.slot ?? 'worker' });
         }
         const refused = caps.admit(waitingEntries[i], scope, waitingEntries);
         if (refused) throw Object.assign(new Error(refused.why), { claimedElsewhere: true });
@@ -921,7 +934,7 @@ async function startCards(board, fleet, lanes, settings, report, entry, effects,
     try {
       const session = await launchRun(board, entry, task.id, plan.lane, fleet, settings);
       if (session) {
-        if (session.surface !== 'pane' || normalMachine(task.machine ?? '') === localMachine()) tickState.local_started += 1;
+        if (normalMachine(session.machine ?? localMachine()) === localMachine()) tickState.local_started += 1;
         report.started.push([task.id, session.address ?? `pid ${session.pid}`, session.mode]);
       }
     } catch (error) {
@@ -1001,6 +1014,20 @@ async function launchAttempt(board, entry, id, lane, fleet, settings, runId) {
   // the run's session record knows its status, role and slot (a reviewer's slot is never the implementer's); the slot
   // is a template, so a step can ask for isolation by naming a new one
   const slot = String(templateValue(spec.session ?? 'worker', scope) ?? 'worker');
+  // Explicit starts and deferred/resumed launches reach this path without startCards. Recheck the dispatcher-session
+  // caps here too, excluding this attempt's own reservation. Other cap kinds keep their existing admission rules.
+  const sessionCaps = entry.workflow.dispatch.capacity?.filter(cap => cap.counts === 'sessions' && cap.where?.dispatch === true) ?? [];
+  if (sessionCaps.length) {
+    const held = await homeHoldings(board.root, listBoards(board.root), lanesOf(entry.profiles), fleet, entry);
+    const others = held.filter(x => !(x.board === board.slug && x.run === runId));
+    const refused = capacity(sessionCaps, others, evaluate).admit({ card: id, board: board.slug, machine: executionHost(lane, task.machine, localMachine(), normalMachine),
+      assignee: lane.name ?? task.assignee, status, stored: scope.card.stored ?? status, model: task.model_override ?? lane.model ?? null, harness: lane.harness,
+      dispatch: true, slot }, { ...scope, lane });
+    if (refused) {
+      runTx(board, id, runId, db => setRunSession(db, runId, { status, role: spec.role, slot, launched_at: now(), launch_deferred: true, launch_deferred_error: refused.why }));
+      throw Object.assign(new Error(refused.why), { launchPending: true });
+    }
+  }
   if (spec.role === 'reviewer') {
     const worker = view(board, (db) => lastSession(db, id, 'worker'));
     const reviewer = view(board, (db) => lastSession(db, id, slot));
@@ -1024,7 +1051,7 @@ async function launchAttempt(board, entry, id, lane, fleet, settings, runId) {
     prompt=`${agentPreamble(agent,{previous:previous.map(item=>({session:item.session,machine:item.machine,ended_at:item.ended_at,end_reason:item.end_reason}))})}\n\n${prompt}`;
     Object.assign(meta,{agent_id:agent.identity.id,agent_org:team.org,agent_context:context??null,
       agent_profile_intent:structuredClone(agent.intended.resolved),
-      agent_env:agentEnvironment(agent,{root:board.root,context:normalMachine(task.machine??localMachine())===localMachine()?localReaderContext(team.org,agent.identity.id)??undefined:undefined})});
+      agent_env:agentEnvironment(agent,{root:board.root,context:executionHost(lane,task.machine,localMachine(),normalMachine)===localMachine()?localReaderContext(team.org,agent.identity.id)??undefined:undefined})});
     // The agent's own memory reaches every session of it: headless runs open its home; a pane, which may sit on
     // another machine, gets the home's snapshot in its run's brief. A shared profile's memory is never used.
     const agentHome=materializeAgentHome(board.root,team.org,agent.identity.id,lane);
@@ -1699,7 +1726,7 @@ export async function mergeReviewed(board, e) {
 function launcherCheck(db, task, lane, fleet) {
   if (lane.surface !== 'pane') return null;
   if (!task.machine) return 'the card names no machine; a pane session runs on the machine its card names';
-  const machine = normalMachine(task.machine);
+  const machine = executionHost(lane, task.machine, localMachine(), normalMachine);
   if (!fleet.ok) return `supercode could not read the fleet: ${fleet.error}`;
   if (fleet.unknown?.has(machine)) return `machine ${machine}'s door did not answer; the card starts when it does`;
   // a machine is scheduled only when it can take a board launch: its board process guard runs this harness, and its
@@ -1991,7 +2018,7 @@ async function reconcileLaunches(board, fleet, report, entry, effects, settings,
 }
 
 async function launchPane(board, task, runId, lane, fleet, { input = null, slot = 'worker', meta = {} } = {}) {
-  const machine = normalMachine(task.machine);
+  const machine = executionHost(lane, task.machine, localMachine(), normalMachine);
   // Whether a board session opens a terminal window on its machine is the workflow's choice, stated on every launch;
   // no machine default decides it.
   const window = workflowFor(board.root).params.session_window;
@@ -2247,7 +2274,7 @@ async function launchHeadless(board, task, runId, lane, settings, { prompt = nul
     },
   });
   child.unref();
-  const session = { surface: 'headless', pid: child.pid, machine: localMachine(), mode: 'fresh', launched_at: now(), exit_file: exitFile, launch_secret: createHash('sha256').update(launchSecret).digest('hex'), ...meta };
+  const session = { surface: 'headless', pid: child.pid, machine: executionHost(lane, task.machine, localMachine(), normalMachine), mode: 'fresh', launched_at: now(), exit_file: exitFile, launch_secret: createHash('sha256').update(launchSecret).digest('hex'), ...meta };
   // recorded against this run only while it is still the card's current one; a run ended meanwhile gets no worker
   const recorded = tx(board, (db) => {
     if (!runCurrent(db, task.id, runId)) return false;

package/ontology.d.ts

@@ -178,6 +178,8 @@ export type CapCount =
 
 /** Which cards and sessions a cap is about: each key given narrows it; a key's names are alternatives. */
 export interface CapFilter {
+  /** Whether the session was started or resumed by the dispatcher, rather than attached by hand. */
+  dispatch?: boolean | null;
   /** The card itself, by id. */
   card?: Names;
   /** The model a session runs (the card's model, else its profile's). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.193",
+  "version": "0.5.195",
   "type": "module",
   "description": "The orchestrator runtime over the Volter Harness ontology: one typed operational model whose folder is its serialization, read and written through the harness orchestration doors (docs/ORCHESTRATOR-IR.md)",
   "exports": {
@@ -30,7 +30,7 @@
   "dependencies": {
     "@volter/supercode-terminal": "^0.3.8",
     "@volter/supercode-harness-sdk": "^0.3.101",
-    "@volter/teams": "0.2.89",
+    "@volter/teams": "0.2.90",
     "@volter/ztrack": "^2.4.23",
     "yaml": "^2.9.0"
   },