@volter/supercode-orchestrator 0.5.133 → 0.5.134

package/board/cli.mjs

@@ -362,7 +362,7 @@ export async function runVerb(argv) {
   if (sid && !READS.has(verb) && boardExists(root, slug)) {
     // binding the caller's launch is a write: only the owner, answering the caller's own verb, makes it (a local read
     // never writes)
-    await withBoardAsync(async (b) => { if (isCallersCall()) await reconcileCallerLaunch(b, sid); const own = ownCard(b.db, sid); if (own) authorize(b.db, verb, rest, args, own); });
+    await withBoardAsync(async (b) => { if (isCallersCall()) await reconcileCallerLaunch(b, sid); const own = ownCards(b.db, sid); if (own.worked.size) authorize(b.db, verb, rest, args, own); });
   }
   // the board's workflow (the IR's): what each verb does, and who may send it, is its
   // every verb reads the board through its workflow (a list settles cards too), so every verb loads it
@@ -1378,10 +1378,28 @@ function workerRun(db, id, sessionId) {
   return hit ? Number(hit.id) : null;
 }
 
-function ownCard(db, sessionId) {
-  const hit = db.prepare('SELECT task_id FROM task_runs WHERE metadata LIKE ? ORDER BY id DESC LIMIT 1').get(`%"session_id":"${sessionId}"%`);
-  if (!hit) return null;
-  return engine.lastSession(db, hit.task_id)?.session_id === sessionId ? engine.getTask(db, hit.task_id) : null;
+/**
+ * The cards the calling session works. A session in no pane can hold several cards at once (an adoption onto a second
+ * card binds its run beside the first; only a pane's session is one run's alone, workflow.mjs retireSupersededRuns), so
+ * this is a set: `worked`, every card whose current run names the session as
+ * its worker, and the card of the newest run naming it while it is still that card's last worker (its card between
+ * runs); `held`, those and every card whose current run names it in any slot (a card it reviews). A session with no
+ * worked card is held to nothing here. The newest run alone named one card, and a session adopted into a second card
+ * was refused every write on its first (volter-org t_9a9c2a9c: no comment, heartbeat or closed subtask there, read
+ * by the board as no progress).
+ */
+function ownCards(db, sessionId) {
+  const worked = new Set(), held = new Set();
+  const like = `%"session_id":"${sessionId}"%`;
+  for (const row of db.prepare('SELECT t.id, r.metadata FROM tasks t JOIN task_runs r ON r.id = t.current_run_id WHERE r.metadata LIKE ?').all(like)) {
+    const session = json(row.metadata, {})?.supercode;
+    if (session?.session_id !== sessionId) continue;
+    held.add(row.id);
+    if ((session.slot ?? 'worker') === 'worker') worked.add(row.id);
+  }
+  const newest = db.prepare('SELECT task_id FROM task_runs WHERE metadata LIKE ? ORDER BY id DESC LIMIT 1').get(like);
+  if (newest && engine.lastSession(db, newest.task_id)?.session_id === sessionId) { worked.add(newest.task_id); held.add(newest.task_id); }
+  return { worked, held };
 }
 
 const READS = new Set(['list', 'ls', 'show', 'context', 'brief', 'runs', 'log', 'tail', 'watch', 'stats', 'assignees', 'diagnostics', 'diag', 'attachments', 'notify-list', 'capacity', 'help', 'init']);
@@ -1432,19 +1450,21 @@ function rolesFor(db, cardId, sessionId, params = {}) {
 }
 
 function authorize(db, verb, rest, args, own) {
-  const refuse = (why) => { throw new Error(`the session working ${own.id} ${why}`); };
+  const cards = [...own.worked];
+  const named = cards.join(', ');
+  const refuse = (why) => { throw new Error(`the session working ${named} ${why}`); };
   if (verb === 'create') {
-    if (args['subtask-of'] !== own.id) refuse(`files subtasks of its own card only (--subtask-of ${own.id})`);
+    if (!own.worked.has(args['subtask-of'])) refuse(`files subtasks of its own card only (--subtask-of ${cards.join(' or ')})`);
     return;
   }
   if (verb === 'boards') { if (!['list', 'ls', 'show', 'current', undefined].includes(rest[0])) refuse('does not change the home\'s boards'); return; }
   // verbs that act on the board rather than on a card are the manager's and the board's, never a card's session's
   // (what a session may do to a card is its workflow's: each transition's `by`)
   if ((['pause', 'resume'].includes(verb) && !rest[0]) || ['swarm', 'dispatch', 'daemon', 'serve', 'gc', 'repair', 'adopt', 'close', 'claim', 'attach-rm', 'migrate'].includes(verb)) refuse(`does not ${verb}; the fleet's manager does`);
-  if (verb === 'set' && !(rest[0] === own.id && rest[1] === 'every')) refuse("sets only Every on its own auditor card; other properties are the manager's");
+  if (verb === 'set' && !(own.worked.has(rest[0]) && rest[1] === 'every')) refuse("sets only Every on its own auditor card; other properties are the manager's");
   if (args.all) refuse(`does not ${verb} every card; only its own`);
   if (['notify-subscribe', 'notify-unsubscribe'].includes(verb) && args['for-card']) {
-    if (args['for-card'] !== own.id) refuse(`subscribes only its own arc (--for-card ${own.id})`);
+    if (!own.worked.has(args['for-card'])) refuse(`subscribes only its own arc (--for-card ${cards.join(' or ')})`);
     return;
   }
   const targets = verb === 'request-state' ? [...rest, ...(args.ids ?? [])] : [rest[0], ...(args.ids ?? [])];
@@ -1453,7 +1473,8 @@ function authorize(db, verb, rest, args, own) {
     if (!card) continue;
     if (isCaller(completionOwnerOf(db, card.id))) continue;
     if (verb === 'comment' && isLatestReviewer(db, card.id, actorOf())) continue;
-    if (card.id !== own.id && card.subtask_of !== own.id) refuse(`writes only its own card and its subtasks, not ${card.id}`);
+    // the card it names is the one it addresses: any card it holds, or a subtask of one it works
+    if (!own.held.has(card.id) && !own.worked.has(card.subtask_of)) refuse(`writes only its own card${cards.length > 1 ? 's' : ''} and ${cards.length > 1 ? 'their' : 'its'} subtasks, not ${card.id}`);
   }
 }
 

package/board/dispatch.mjs

@@ -383,6 +383,8 @@ const unavailable = message => Object.assign(new Error(message), { launchDeferre
 function progressedSince(db, task, runRow) {
   const started = Number(runRow?.started_at ?? 0);
   const progress = sessionProgress(db, task);
+  // an unread checkout is not a run without commits: it is never counted as one
+  if (progress.commit == null) return true;
   if (progress.commit >= started && progress.commit > 0) return true;
   const at = progress.event ? db.prepare('SELECT created_at FROM task_events WHERE id=?').get(progress.event)?.created_at : null;
   return at != null && Number(at) >= started;
@@ -500,7 +502,11 @@ async function supervise(board, fleet, settings, report, entry, effects) {
           return;
         }
         if (session.offline_since != null) {
-          setRunSession(db,runRow.id,{...session,offline_since:null,offline_notified_at:null});
+          // What the board could not see is not the session's: the outage is no working time of the run (its runtime
+          // limit, its coding time), its idle and unknown-turn clocks start again from here (observeIdle), and a
+          // session read missing before the machine went is read again before it is missed.
+          setRunSession(db,runRow.id,{...session,offline_since:null,offline_notified_at:null,missing_since:null,unknown_since:null,watch_since:t,
+            stopped_seconds:Number(session.stopped_seconds??0)+Math.max(0,t-Number(session.offline_since))});
           observe('machine_online',{machine:session.machine,reason:'machine linked again'},null);
           session=currentRun(db,id)?.metadata?.supercode ?? session;
         }
@@ -1258,6 +1264,9 @@ export async function closeRequested(board, report, { taskId = null, caller = nu
   }
 }
 
+// When this process last read each run's turn (run id → seconds). Kept in memory on purpose: a board that restarted
+// has watched nothing, and its first reading of a run is where that run's watch begins.
+const idleWatch = new Map();
 /** Native idle intervals are independent of dispatch cadence and transcript writes.
  * Keep bounded readings on the run so an ordinary quiet stretch can be reviewed later. */
 async function observeIdle(board, fleet, settings, report, entry, effects) {
@@ -1296,15 +1305,18 @@ async function observeIdle(board, fleet, settings, report, entry, effects) {
     if (addressOf(session)) cardsOf.set(addressOf(session), [...(cardsOf.get(addressOf(session)) ?? []), id]);
   }
   for (const { id } of running) {
-    let staged = [];
+    let staged = [], watched = null;
     txRead(board, (db) => {
-      staged = [];
+      staged = []; watched = null;
       const task = getTask(db, id);
       const status = statusOf(db, task);
       if (!(entry.workflow.statuses[status]?.on?.session_idle || entry.workflow.on?.session_idle || entry.workflow.run?.on?.session_idle)) return;
       const runRow = currentRun(db, id);
-      const session = runRow?.metadata?.supercode;
+      let session = runRow?.metadata?.supercode;
       if (!session?.session_id || !['pane', 'native'].includes(session.surface) || session.offline_since != null) return;
+      // a machine this round did not read as online (offline, or its door silent) shows nothing of its session: no
+      // clock of the run moves on a round that could not see it
+      if (session.machine && !fleet.online.has(session.machine)) return;
       if (session.surface === 'native' && sessionAlive(fleet, session) !== true) return;
       // a session in no pane has its turn on its machine's discovery row, which sessionAlive just read
       let nativeRow = null;
@@ -1312,10 +1324,23 @@ async function observeIdle(board, fleet, settings, report, entry, effects) {
       const live = fleet.sessions.find((x) => x.address === addressOf(session)) ?? (nativeRow ? { address: addressOf(session), turn: nativeRow.activity?.turn ?? null, waiting_for: nativeRow.activity?.evidence?.waiting_for ?? null,
         turn_source: nativeRow.activity?.evidence?.source ?? null, turn_since_ms: nativeRow.activity?.evidence?.native_state_since_ms ?? null } : undefined);
       const observedAt = now();
-      const progress = sessionProgress(db, task);
+      // Quiet time is time the board watched. A run this process has not read for a while (the board restarted, was
+      // paused, could not read the fleet or the machine) starts its idle and unknown-turn clocks from this reading:
+      // the gap is not idleness, and no reminder is spent on it (volter-org t_9a9c2a9c: reminder 1 in the second its
+      // machine came back, the run reclaimed 45 minutes later).
+      const lastWatched = idleWatch.get(runRow.id);
+      if (lastWatched == null || observedAt - lastWatched > Math.max(3 * settings.interval, settings.idleQuiet / 2)) {
+        setRunSession(db, runRow.id, { watch_since: observedAt, unknown_since: null });
+        session = { ...session, watch_since: observedAt, unknown_since: null };
+      }
+      watched = [runRow.id, observedAt];
+      const read = sessionProgress(db, task);
       const priorProgress = session.work_progress;
-      const worked = Boolean(priorProgress) && (progress.event > priorProgress.event || progress.commit > priorProgress.commit);
-      if (!priorProgress || worked) setRunSession(db, runRow.id, { work_progress: progress, ...(worked ? { goal_turns: 0 } : {}) });
+      // The commit a run is measured from is the last one read. A checkout that could not be read (its machine silent,
+      // its daemon without the door) keeps that baseline: its first reading after is where it stands, not work done.
+      const progress = { event: read.event, commit: read.commit ?? priorProgress?.commit ?? null, ...(read.commit == null ? { commit_unread: read.commit_unread } : {}) };
+      const worked = Boolean(priorProgress) && (progress.event > priorProgress.event || (read.commit != null && priorProgress.commit != null && read.commit > priorProgress.commit));
+      if (!priorProgress || worked || (priorProgress.commit == null && read.commit != null)) setRunSession(db, runRow.id, { work_progress: { event: progress.event, commit: progress.commit }, ...(worked ? { goal_turns: 0 } : {}) });
       const lastAtMs = Number(live?.last_message_at_ms) || updatedAt(session);
       const lastAt = Math.floor(Number(lastAtMs) / 1000);
       const reading = {
@@ -1407,6 +1432,9 @@ async function observeIdle(board, fleet, settings, report, entry, effects) {
       if (session.idle_since !== interval.since) setRunSession(db, runRow.id, { idle_since: interval.since });
       if (reading.quiet_seconds < settings.idleQuiet) { retain('below_threshold'); return; }
       if (session.goal_nudged_at && observedAt - session.goal_nudged_at < settings.idleQuiet) { retain('nudge_cooldown'); return; }
+      // A reminder says the card shows no progress, and the last of them ends the run for it. With the card's checkout
+      // unread that is not known: nothing is said or counted until it is read (the reading's `progress` says why).
+      if (read.commit == null) { retain('progress_unread'); return; }
       try {
         const where = whereOf(board, task);
         // the ask names what the session may do, as its run's prompt did
@@ -1424,8 +1452,10 @@ async function observeIdle(board, fleet, settings, report, entry, effects) {
         report.failed.push([id, `session_idle: ${String(error.message).slice(-200)}`]);
       }
     });
+    if (watched) idleWatch.set(...watched);
     effects.push(...staged);
   }
+  for (const [runId, at] of idleWatch) if (now() - at > 86_400) idleWatch.delete(runId);
 }
 
 function effectMessageKey(effect) {

package/board/session-work.mjs

@@ -40,10 +40,13 @@ export function delegatedWork(address, edges, sessions) {
   return working;
 }
 
-/** Idle time belongs to a native idle interval, never to transcript freshness. */
+/** Idle time belongs to a native idle interval, never to transcript freshness, and only to time the board watched:
+ * it starts no earlier than `session.watch_since`, where the board's unbroken reading of the run began (its machine
+ * linked again, the board restarted or resumed). Quiet the board could not see is not idleness. */
 export function idleInterval(session, live, observedAt) {
   const nativeSince = Number(live?.turn_since_ms);
-  const since = nativeSince > 0 && nativeSince <= observedAt * 1000
+  const read = nativeSince > 0 && nativeSince <= observedAt * 1000
     ? Math.floor(nativeSince / 1000) : Number(session.idle_since ?? observedAt);
+  const since = Math.min(observedAt, Math.max(read, Number(session.watch_since ?? 0)));
   return { since, quiet: Math.max(0, observedAt - since) };
 }

package/board/workflow.mjs

@@ -15,7 +15,7 @@ import { randomBytes } from 'node:crypto';
 import { actorOf, appendRunObservation, event as record, json, now } from './store.mjs';
 import { evaluate, holds, render } from './expr.mjs';
 import { completionEvidence, declaredWorkBranches, namedWorkBranch, reviewCandidate } from './ci.mjs';
-import { isWorkspacePath } from './workspace.mjs';
+import { cardCommitsOn, isLocalWorkspace, isWorkspacePath } from './workspace.mjs';
 import { identifyNotice } from './notices.mjs';
 
 const loaded = new Map();
@@ -206,64 +206,92 @@ function pattern(p) {
 // and the default branch they merge into. Another ref naming the card (an evidence branch, a later card's work) is not
 // a change to its reviewed work. Merge commits are not the card's work: merging its reviewed PR, or main into its
 // branch, is not a newer change to review.
-const commitTimes = new Map();
-async function observeLastCommit(path, id, branches = []) {
-  if (!path) return null;
-  const key = `${path}:${id}`;
-  const cached = commitTimes.get(key);
-  if (cached && now() - cached.at < 15) return cached.value;
+//
+// A reading is known or it is not. A checkout on this machine is read here; one on another machine is read by that
+// machine's daemon (workspace.mjs cardCommitsOn, the same reading: sdk/teams/workspaces.mjs cardCommitTime), never by
+// running git here on a path of that machine (a Windows path read on a Mac answered no commits for as long as the card
+// ran: volter-org t_9a9c2a9c). A folder that is not there, a git that did not answer, a machine that could not be asked:
+// unknown, with why, and never "no commits".
+const commitTimes = new Map(); // `${path}:${id}` → { at, known, value, error }
+async function readCardCommit(path, id, branches) {
+  if (!existsSync(path)) return { known: false, value: null, error: `no folder ${path} on this machine` };
   // awaited, never a wait that holds the event loop: `status` 0 or the exit code, as a synchronous run answered
-  const git = (repo, args) => execFileAsync('git', ['-C', repo, ...args], { encoding: 'utf8', timeout: 10_000 }).then(({ stdout }) => ({ status: 0, stdout }), (error) => ({ status: error.code ?? 1, stdout: error.stdout ?? '' }));
+  const git = (repo, args) => execFileAsync('git', ['-C', repo, ...args], { encoding: 'utf8', timeout: 10_000 }).then(({ stdout }) => ({ status: 0, stdout }), (error) => ({ status: error.code ?? 1, stdout: error.stdout ?? '', timedOut: Boolean(error.killed) }));
   const readCommit = async (repo) => {
     const listed = await git(repo, ['for-each-ref', '--format=%(refname)', 'refs/heads', 'refs/remotes']);
-    if (listed.status !== 0) return { repo: false, value: null };
+    if (listed.timedOut) return { repo: true, known: false, value: null, error: `git did not answer in ${repo} within 10s` };
+    if (listed.status !== 0) return { repo: false, known: true, value: null };
     const current = (await git(repo, ['branch', '--show-current'])).stdout?.trim();
     const fallback = (await git(repo, ['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD'])).stdout?.trim().replace(/^refs\/remotes\/origin\//, '');
     const names = new Set([...branches, current, fallback].filter(Boolean));
     const short = (ref) => ref.startsWith('refs/heads/') ? ref.slice(11) : ref.split('/').slice(3).join('/');
     const refs = listed.stdout.split('\n').filter((ref) => ref && !ref.endsWith('/HEAD') && (names.has(short(ref)) || namedWorkBranch(id, short(ref))));
-    if (!refs.length) return { repo: true, value: null };
+    if (!refs.length) return { repo: true, known: true, value: null };
     const r = await git(repo, ['log', ...refs, '--no-merges', '-1', '--format=%ct', '--fixed-strings', `--grep=${id}`, '--']);
+    if (r.status !== 0) return { repo: true, known: false, value: null, error: `git log ${r.timedOut ? 'did not answer within 10s' : 'failed'} in ${repo}` };
     const value = Number(r.stdout?.trim());
-    return { repo: r.status === 0, value: Number.isFinite(value) && value > 0 ? value : null };
+    return { repo: true, known: true, value: Number.isFinite(value) && value > 0 ? value : null };
   };
   const own = await readCommit(path);
-  let value = own.value;
-  if (!own.repo) {
-    // A fleet card may span sibling repositories under its declared workspace.
-    // Only direct children with a Git door participate; never scan arbitrary home trees.
-    let entries = []; try { entries = readdirSync(path, { withFileTypes: true }); } catch {}
-    for (const child of entries) {
-      if (!child.isDirectory() && !child.isSymbolicLink()) continue;
-      const repo = resolve(path, child.name);
-      if (!existsSync(resolve(repo, '.git'))) continue;
-      const t = (await readCommit(repo)).value;
-      if (t != null) value = Math.max(value ?? 0, t);
-    }
+  if (own.repo) return { known: own.known, value: own.value, ...(own.error ? { error: own.error } : {}) };
+  // A fleet card may span sibling repositories under its declared workspace.
+  // Only direct children with a Git door participate; never scan arbitrary home trees.
+  let value = null, unread = null;
+  let entries = []; try { entries = readdirSync(path, { withFileTypes: true }); } catch (error) { return { known: false, value: null, error: `${path} could not be listed: ${error.code ?? error.message}` }; }
+  for (const child of entries) {
+    if (!child.isDirectory() && !child.isSymbolicLink()) continue;
+    const repo = resolve(path, child.name);
+    if (!existsSync(resolve(repo, '.git'))) continue;
+    const read = await readCommit(repo);
+    if (!read.known) unread ??= read.error;
+    if (read.value != null) value = Math.max(value ?? 0, read.value);
   }
-  commitTimes.set(key, { at: now(), value });
-  return value;
+  // a commit that was read stands; with none read, a child that could not be read leaves the whole reading unknown
+  return value == null && unread ? { known: false, value: null, error: unread } : { known: true, value };
+}
+async function observeLastCommit(path, id, branches = [], machine = null) {
+  if (!path) return null;
+  const key = `${path}:${id}`;
+  const cached = commitTimes.get(key);
+  if (cached && now() - cached.at < 15) return cached.value;
+  let reading;
+  try {
+    if (isLocalWorkspace({ machine })) reading = await readCardCommit(path, id, branches);
+    else reading = { known: true, value: (await cardCommitsOn(machine, path, id, branches)).at };
+  } catch (error) { reading = { known: false, value: null, error: String(error?.message ?? error).slice(0, 300) }; }
+  commitTimes.set(key, { at: now(), ...reading });
+  return reading.value;
 }
 
 function lastCommitAt(path, id) { return path ? commitTimes.get(`${path}:${id}`)?.value ?? null : null; }
+/** The checkout a card's commits are read in, and the machine it is on: its current run's session's machine, else the
+ *  card's own. A scratch card has none, and a subtask's commits are its arc's (refreshCardInputs reads none for it). */
+function commitSource(db, task) {
+  const path = task.workspace_kind !== 'scratch' && !task.subtask_of ? task.workspace_path ?? null : null;
+  if (!path) return { path: null, machine: null };
+  const session = task.current_run_id ? json(one(db, 'SELECT metadata FROM task_runs WHERE id=?', task.current_run_id)?.metadata, {})?.supercode : null;
+  return { path, machine: session?.machine ?? one(db, 'SELECT machine FROM supercode_cards WHERE task_id=?', task.id)?.machine ?? null };
+}
 /** Material card work. Comments, reminder replies and timestamp writes are
- * deliberately absent; a heartbeat is a separately bounded waiting lease. */
+ * deliberately absent; a heartbeat is a separately bounded waiting lease.
+ * `commit` is the time of the card's latest commit, 0 for none, and null when its checkout could not be read
+ * (`commit_unread` says why): an unread checkout is not a card with no commits, and nothing may count it as one. */
 export function sessionProgress(db, task) {
   const event = one(db, `SELECT MAX(e.id) AS id FROM task_events e WHERE
     (e.task_id=? AND e.kind IN ('specified','review_requested','review_pass','changes_requested','audited')) OR
     (e.task_id IN (SELECT task_id FROM supercode_cards WHERE subtask_of=?) AND e.kind IN ('completed','cancelled'))`, task.id, task.id);
-  return { event: Number(event?.id ?? 0), commit: Number(lastCommitAt(task.workspace_path, task.id) ?? 0) };
+  const { path } = commitSource(db, task);
+  const read = path ? commitTimes.get(`${path}:${task.id}`) ?? { known: false, error: 'its checkout has not been read yet' } : { known: true, value: null };
+  return { event: Number(event?.id ?? 0), commit: read.known ? Number(read.value ?? 0) : null, ...(read.known ? {} : { commit_unread: read.error ?? 'its checkout could not be read' }) };
 }
 /** Observe external facts before entering an optimistic board mutation. */
 export async function refreshCardInputs(board, id, { commits = false } = {}) {
   const task=board.db.prepare('SELECT t.*,c.subtask_of FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.id=?').get(id);
   if (!task)return;
   if (commits && !task.subtask_of) {
-    const own=task.workspace_kind!=='scratch'?task.workspace_path:null;
-    const parent=!own && task.subtask_of?board.db.prepare('SELECT workspace_path FROM tasks WHERE id=?').get(task.subtask_of)?.workspace_path:null;
-    const path=own??parent??null;
+    const { path, machine } = commitSource(board.db, task);
     if(path)commitTimes.delete(`${path}:${id}`);
-    await observeLastCommit(path,id,declaredWorkBranches(board.db,id));
+    await observeLastCommit(path,id,declaredWorkBranches(board.db,id),machine);
   }
 }
 

package/board/workspace.mjs

@@ -33,6 +33,35 @@ async function workspaceDoor(machine, verb, value, options = {}) {
   if (r.code !== 0) throw new Error(`workspace on ${machine}: ${own ? `${own.message}; the machine daemon: ` : ''}${(r.stderr || r.stdout || r.error?.message).trim()}`);
   return JSON.parse(r.stdout);
 }
+// A machine whose commit door did not answer is not asked again for a while: each call would wait out its bound, once
+// per running card per round. One that has no such door (a daemon older than the door) is asked again in ten minutes.
+const commitDoorHeld = new Map(); // machine → { until (ms), why }
+/**
+ * When the latest commit naming `card` was made on its work in the checkout at `path` on another machine, as that
+ * machine's own daemon reads it (`harness.v1.workspaces.commits`: fixed git arguments, ten seconds a call there, ten
+ * seconds here): `{ at }`, seconds or null for none. Throws when it could not be read (the machine offline or silent,
+ * its daemon without the door, no such folder there): an unread checkout is unknown, never a card with no commits.
+ */
+export async function cardCommitsOn(machine, path, card, branches = []) {
+  const name = normalMachine(machine);
+  if (presence?.known === true && !presence.online.has(name)) throw new Error(`machine ${name} is offline`);
+  const held = commitDoorHeld.get(name);
+  if (held && Date.now() < held.until) throw new Error(held.why);
+  const r = await runtimeDoor(machine, 'harness.v1.workspaces.commits', { path, card, branches }, { timeout: 10_000 });
+  if (r.code !== 0) {
+    let refusal = null; try { refusal = JSON.parse(String(r.stderr).trim().split('\n').pop()); } catch { /* said in its own words */ }
+    const missing = refusal?.code === -32601 || /unknown method/.test(refusal?.message ?? '');
+    const why = missing ? `machine ${name}'s daemon has no commit reading door (harness.v1.workspaces.commits); it answers once that machine runs a supercode that has it`
+      : `machine ${name}: ${String(refusal?.message ?? r.stderr ?? 'its door did not answer').trim().slice(0, 200)}`;
+    // the machine's own answer about one path says nothing of its other checkouts; a door that did not answer does
+    if (missing || refusal?.code == null || ['unavailable', 'machine_offline', 'ETIMEDOUT', 'ECONNRESET', 504, '504'].includes(refusal.code) || /timed out|timeout/i.test(refusal?.message ?? '')) commitDoorHeld.set(name, { until: Date.now() + (missing ? 600_000 : 60_000), why });
+    throw new Error(why);
+  }
+  commitDoorHeld.delete(name);
+  const answer = JSON.parse(r.stdout);
+  if (!answer || typeof answer !== 'object' || !('at' in answer) || (answer.at !== null && !(Number(answer.at) > 0))) throw new Error(`machine ${name} answered no commit reading`);
+  return { at: answer.at === null ? null : Number(answer.at) };
+}
 /** A workspace declaration that asks no machine (scratch, or a repository named by id), else null: a path is declared
  *  through its machine's door (declareWorkspace). */
 export function plainWorkspace(kind, value, branch = null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.133",
+  "version": "0.5.134",
   "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": {