@volter/supercode-orchestrator 0.5.73 → 0.5.74

package/board/engine.mjs

@@ -8,10 +8,10 @@
 // Each function takes an open board (`store.mjs`) and runs in one write transaction. Nothing here launches,
 // observes or sends: the dispatcher (`dispatch.mjs`) does, and records what it did through these.
 import { current } from './call.mjs';
-import { spawn, spawnSync } from 'node:child_process';
+import { spawn, execFile } from 'node:child_process';
 import { existsSync, rmSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { checkWorkspace, assertWorkspaceOwner, declareWorkspace, isLocalWorkspace } from './workspace.mjs';
+import { checkWorkspace, assertWorkspaceOwner, declareWorkspace, isLocalWorkspace, plainWorkspace } from './workspace.mjs';
 import { DatabaseSync } from 'node:sqlite';
 import { view, actorOf, principalOf, claimer, contention, event, json, newTaskId, now, retryContention, tx } from './store.mjs';
 import { completionPhase, inspectCompletionEvidence, observeCompletionEvidence, withCompletionEvidence } from './ci.mjs';
@@ -181,6 +181,25 @@ export function bodyTasks(body) {
   return { body: rest || null, tasks: tasks.map((t) => ({ title: t.title, body: t.body.join('\n') || null })) };
 }
 
+/**
+ * A card's workspace declared through its machine's door when it names a path (a `dir`, a legacy checkout path), awaited
+ * before the card is filed: the filing (createCard) is one write that asks no machine. Answers the spec to file.
+ */
+export async function prepareCard(board, spec) {
+  const ws = parseWorkspace(spec.workspace ?? 'scratch');
+  const project = spec.project ? projectOf(board.root, spec.project) : null;
+  if (project) {
+    if (ws.kind === 'scratch') ws.kind = 'worktree';
+    if (ws.kind === 'worktree' && !ws.path) ws.path = project.primary_path;
+  }
+  if (plainWorkspace(ws.kind, ws.path, spec.branch)) return spec;
+  const machineHint = spec.machine ?? (spec.subtaskOf ? getTask(board.db, spec.subtaskOf)?.machine : null);
+  const declared = await declareWorkspace(ws.kind, ws.path, machineHint, spec.branch);
+  const workspaceTask = { workspace_kind: ws.kind, workspace_path: declared.path, workspace_anchor: declared.repository, branch_name: declared.branch, machine: machineHint };
+  // Logical repositories may be filed before a machine has registered them; launch refuses missing mappings.
+  const checked = ws.kind === 'dir' && declared.path ? await checkWorkspace(board, workspaceTask) : null;
+  return { ...spec, workspaceDeclared: { declared, checked } };
+}
 export function createCard(board, spec) {
   const title = String(spec.title ?? '').trim();
   if (!title) throw new Error('a card has a title');
@@ -196,10 +215,11 @@ export function createCard(board, spec) {
     if (ws.kind === 'worktree' && !ws.path) ws.path = project.primary_path;
   }
   const machineHint = spec.machine ?? (spec.subtaskOf ? getTask(board.db, spec.subtaskOf)?.machine : null);
-  const declared = declareWorkspace(ws.kind, ws.path, machineHint, spec.branch);
+  const declared = spec.workspaceDeclared?.declared ?? plainWorkspace(ws.kind, ws.path, spec.branch);
+  if (!declared) throw new Error('a workspace path is declared through its machine before the card is filed (prepareCard)');
   const workspaceTask = { workspace_kind: ws.kind, workspace_path: declared.path, workspace_anchor: declared.repository, branch_name: declared.branch, machine: machineHint };
   // Logical repositories may be filed before a machine has registered them; launch refuses missing mappings.
-  const checked = ws.kind === 'dir' && declared.path ? checkWorkspace(board, workspaceTask) : null;
+  const checked = spec.workspaceDeclared?.checked ?? null;
   ws.path = declared.path;
   spec = { ...spec, branch: declared.branch ?? spec.branch };
   const initial = spec.initialStatus ?? null;
@@ -367,12 +387,13 @@ export function extendClaim(db, id, { ttl, reason, extra = {} }) {
  * A completed card's workspace goes, as Hermes cleans up on completion: a scratch directory under the board's own
  * workspaces, or a worktree (its branch stays); never while a child still waits on it, never a `dir`.
  */
-function cleanupWorkspace(board, id) {
+async function cleanupWorkspace(board, id) {
   const task = view(board, (db) => getTask(db, id));
   if (!task?.workspace_path || !isLocalWorkspace(task) || !['scratch', 'worktree'].includes(task.workspace_kind)) return;
   const waiting = view(board, (db) => one(db, "SELECT 1 FROM task_links l JOIN tasks t ON t.id = l.child_id WHERE l.parent_id = ? AND t.status NOT IN ('done', 'archived') LIMIT 1", id));
   if (waiting || !existsSync(task.workspace_path)) return;
-  if (task.workspace_kind === 'worktree') { spawnSync('git', ['-C', task.workspace_path, 'worktree', 'remove', '--force', task.workspace_path], { encoding: 'utf8' }); return; }
+  // awaited, never a wait that holds the event loop
+  if (task.workspace_kind === 'worktree') { await new Promise((resolve) => execFile('git', ['-C', task.workspace_path, 'worktree', 'remove', '--force', task.workspace_path], { encoding: 'utf8' }, () => resolve())); return; }
   const managed = resolve(board.slug === 'default' ? join(board.root, 'kanban', 'workspaces') : join(board.root, 'kanban', 'boards', board.slug, 'workspaces'));
   if (resolve(task.workspace_path).startsWith(`${managed}/`)) rmSync(task.workspace_path, { recursive: true, force: true });
 }
@@ -406,9 +427,9 @@ export async function act(board, id, name, { roles = null, payload = {}, extra =
   const entry = await loadWorkflow(board.root);
   if (name === 'comment' && (!String(payload.body ?? '').trim() || !String(payload.author ?? '').trim())) throw new Error('a comment has an author and body');
   refuseCredentialDump(name === 'comment' ? `the comment on ${id}` : `${name.replace(/_/g, '-')} on ${id}`, payload);
-  refreshCardInputs(board, id, { commits: ['complete', 'request_review'].includes(name) });
+  await refreshCardInputs(board, id, { commits: ['complete', 'request_review'].includes(name) });
   const evidencePhase = ['complete', 'request_review', 'request_state'].includes(name) ? completionPhase(board, id, entry, name, payload, roles ?? callerRoles(board.db, id)) : null;
-  if (evidencePhase) payload = { ...payload, ci: observeCompletionEvidence(board, id, entry, payload, evidencePhase) };
+  if (evidencePhase) payload = { ...payload, ci: await observeCompletionEvidence(board, id, entry, payload, evidencePhase) };
   if (payload.ci?.required && !payload.ci.ready && (name !== 'request_state' || evidencePhase === 'review_verdict')) throw new Error(payload.ci.reason ?? 'The PR candidate could not be verified.');
   const result = tx(board, (db) => {
     roles ??= callerRoles(db, id);
@@ -423,7 +444,7 @@ export async function act(board, id, name, { roles = null, payload = {}, extra =
   });
   await runEffects(board, result.effects);
   // A card this verb closed ends its agents' assignments; the verb hands the ends on itself (agent-declarations.mjs).
-  if (result.moved) { const { endFinishedAgents } = await import('./agent-declarations.mjs'); endFinishedAgents(board, [id]); }
+  if (result.moved) { const { endFinishedAgents } = await import('./agent-declarations.mjs'); await endFinishedAgents(board, [id]); }
   return { from: result.from, to: result.to, moved: result.moved, ...(result.commentId ? { commentId: result.commentId } : {}) };
 }
 
@@ -431,16 +452,16 @@ export async function requestStateMany(board, ids, payload = {}) {
   const targets = [...new Set(ids.map(String))];
   if (!targets.length) throw new Error('A state request names at least one card.');
   const entry = await loadWorkflow(board.root);
-  const prepared = new Map(targets.map(id => {
+  const prepared = new Map(await Promise.all(targets.map(async id => {
     const roles = callerRoles(board.db, id);
     const phase = completionPhase(board, id, entry, 'request_state', payload, roles);
-    const evidence = inspectCompletionEvidence(board, id, entry, payload, phase);
+    const evidence = await inspectCompletionEvidence(board, id, entry, payload, phase);
     // An ordinary request mails a decision to the manager, not a completion.
     // Keep a failed source observation in that mail. A reviewer recording an
     // actual verdict still has to verify the requested PR head.
     if (phase === 'review_verdict' && evidence.required && !evidence.ready) throw new Error(evidence.reason ?? 'The reviewed PR head could not be verified.');
     return [id, evidence];
-  }));
+  })));
   const result = tx(board, db => {
     const effects = [];
     const results = targets.map(id => withCompletionEvidence(board, id, prepared.get(id), () => {
@@ -451,15 +472,15 @@ export async function requestStateMany(board, ids, payload = {}) {
     return { results, effects };
   });
   await runEffects(board, result.effects);
-  { const { endFinishedAgents } = await import('./agent-declarations.mjs'); endFinishedAgents(board, targets); }
+  { const { endFinishedAgents } = await import('./agent-declarations.mjs'); await endFinishedAgents(board, targets); }
   return result.results;
 }
 
 /** Take card `id` to `status` by the event the workflow says goes there for this caller (`goto`). */
 export async function goto(board, id, status, { roles = null, payload = {} } = {}) {
   const entry = await loadWorkflow(board.root);
-  refreshCardInputs(board, id, { commits: true });
-  observeCompletionEvidence(board, id, entry, payload);
+  await refreshCardInputs(board, id, { commits: true });
+  await observeCompletionEvidence(board, id, entry, payload);
   const { name, refusal, from } = (() => {
     const db=board.db;
     roles ??= callerRoles(db, id);
@@ -553,10 +574,10 @@ export async function runEffects(board, effects = [], { pending: due = false, el
 /** One effect's I/O: true when it is done, false when it is not done yet (the caller counts the attempt). */
 async function runEffect(board, e) {
   if (e.kind === 'session_notice') { const { sessionNotice } = await import('./dispatch.mjs'); return await sessionNotice(board, e) !== false; }
-  if (e.kind === 'cleanup_workspace') { cleanupWorkspace(board, e.id); return true; }
-  if (e.kind === 'declare_card_agent') { const { declareCardAgentEffect } = await import('./agent-declarations.mjs'); return declareCardAgentEffect(board, e) !== false; }
+  if (e.kind === 'cleanup_workspace') { await cleanupWorkspace(board, e.id); return true; }
+  if (e.kind === 'declare_card_agent') { const { declareCardAgentEffect } = await import('./agent-declarations.mjs'); return (await declareCardAgentEffect(board, e)) !== false; }
   // a verb's own ask files its card's mail at once (a local write; the mailbox delivers it)
-  if (e.kind === 'board_message') { const { fileBoardMail } = await import('./dispatch.mjs'); fileBoardMail(board, { undelivered: [] }, e.id); return true; }
+  if (e.kind === 'board_message') { const { fileBoardMail } = await import('./dispatch.mjs'); await fileBoardMail(board, { undelivered: [] }, e.id); return true; }
   if (e.kind === 'merge_reviewed') { const { mergeReviewed } = await import('./dispatch.mjs'); return await mergeReviewed(board, e) !== false; }
   if (e.kind === 'invalidate_descendants') { tx(board, (db) => invalidateDescendants(db, board, e.id)); return true; }
   if (e.kind === 'stop_run') { stopWorker(board, e.runId); return true; }
@@ -624,14 +645,14 @@ function invalidateDescendants(db, board, id) {
 
 // each of Hermes's verbs is an event of the workflow; the words it takes are the event's payload
 
-export const complete = (board, id, { result = null, summary = null, metadata = null, roles, runId = null, commit = null, ci_run = null, branch = null, pr = null, pr_head = null, reviewed_sha = null } = {}) =>
-  act(board, id, 'complete', { roles, payload: { result, summary, metadata, run_id: runId, commit, ci_run, branch, pr, pr_head, reviewed_sha } });
+export const complete = async (board, id, { result = null, summary = null, metadata = null, roles, runId = null, commit = null, ci_run = null, branch = null, pr = null, pr_head = null, reviewed_sha = null } = {}) =>
+  await act(board, id, 'complete', { roles, payload: { result, summary, metadata, run_id: runId, commit, ci_run, branch, pr, pr_head, reviewed_sha } });
 // a block names the one thing that ends it: a card it waits on (`on`), or the message whose answer it waits for (`waiting_on`)
-export const block = (board, id, { reason = null, on = null, waitingOn = null, roles, runId = null } = {}) =>
-  act(board, id, 'block', { roles, payload: { reason, on, waiting_on: waitingOn, run_id: runId } });
+export const block = async (board, id, { reason = null, on = null, waitingOn = null, roles, runId = null } = {}) =>
+  await act(board, id, 'block', { roles, payload: { reason, on, waiting_on: waitingOn, run_id: runId } });
 export const unblock = (board, id, { reason = null, on = null, roles } = {}) => act(board, id, 'unblock', { roles, payload: { reason, on } });
-export const requestReview = (board, id, { summary = null, metadata = null, reviewer = null, force = false, expectedRunId = null, roles, commit = null, ci_run = null, branch = null, pr = null, pr_head = null } = {}) =>
-  act(board, id, 'request_review', { roles, payload: { summary, metadata, reviewer, force, run_id: expectedRunId, commit, ci_run, branch, pr, pr_head } });
+export const requestReview = async (board, id, { summary = null, metadata = null, reviewer = null, force = false, expectedRunId = null, roles, commit = null, ci_run = null, branch = null, pr = null, pr_head = null } = {}) =>
+  await act(board, id, 'request_review', { roles, payload: { summary, metadata, reviewer, force, run_id: expectedRunId, commit, ci_run, branch, pr, pr_head } });
 export const requestChanges = (board, id, { reason = null, reviewer = null, roles } = {}) => act(board, id, 'request_changes', { roles, payload: { reason, reviewer } });
 export const reopen = (board, id, { author = 'user', reason = null, roles } = {}) => act(board, id, 'reopen', { roles, payload: { author, reason } });
 export const reopenReview = (board, id, { roles, reason = null } = {}) => act(board, id, 'reopen_review', { roles, payload: { reason } });
@@ -651,10 +672,10 @@ export async function specify(board, id, { title = null, body = null, workspace
     const ws = parseWorkspace(word);
     if (task.current_run_id) throw new Error('end the current run before changing its workspace');
     if (branch != null && ws.kind === 'scratch') throw new Error('a scratch workspace has no repository branch');
-    declaration = { kind: ws.kind, ...declareWorkspace(ws.kind, ws.path, target, branch), ...(machine != null && target !== task.machine ? { machine: target } : {}) };
+    declaration = { kind: ws.kind, ...(await declareWorkspace(ws.kind, ws.path, target, branch)), ...(machine != null && target !== task.machine ? { machine: target } : {}) };
     if (declaration.repository === task.workspace_anchor) declaration.branch ??= task.branch_name;
     if (declaration.kind === 'worktree') declaration.branch ??= `wt/${id}`;
-    if (declaration.kind === 'dir') declaration.path = checkWorkspace(board, { ...task, machine: target, workspace_kind: declaration.kind, workspace_anchor: declaration.repository, workspace_path: declaration.path, branch_name: declaration.branch }).path;
+    if (declaration.kind === 'dir') declaration.path = (await checkWorkspace(board, { ...task, machine: target, workspace_kind: declaration.kind, workspace_anchor: declaration.repository, workspace_path: declaration.path, branch_name: declaration.branch })).path;
   }
   // an arc's new task lines are filed as its subtasks once the specify itself is accepted
   const steps = body != null && !one(board.db, 'SELECT subtask_of FROM supercode_cards WHERE task_id = ?', id)?.subtask_of ? bodyTasks(body) : { body, tasks: [] };
@@ -670,10 +691,11 @@ export const setGoal = (board, id, { on = true, maxTurns = null, roles } = {}) =
 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 = children.map((c) => createCard(board, {
+  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);
+  })).id);
   await act(board, id, 'decompose', { roles, payload: { children: ids, author } });
   return ids;
 }

package/board/git-document.mjs

@@ -6,8 +6,15 @@
 // the two texts of a board document merged by ztrack's own document merge, in which a hand edit wins its cards. Nothing
 // either side wrote is dropped; a merge that cannot be made stops the push and says why, leaving both texts in the
 // checkout's history.
+//
+// The remote is never waited on (D192): a fetch runs beside the process, and what it brings is merged in one local step
+// on this process's loop, serialized with its writes, as a write's own commit is; a push runs beside the process too.
+// What is owed is git's own state, never a queue in memory: board documents that differ from HEAD are a commit owed,
+// and a HEAD ahead of its upstream is a push owed. A process that ends with either owed leaves it in the checkout, and
+// the next one to open each board derives it again and does it (`derive`): after that board's own recovery has written
+// what its store accepted, over every document the board has (the open one, its archive and each rotated archive).
 import { current } from './call.mjs';
-import { execFileSync, spawn } from 'node:child_process';
+import { execFile, execFileSync, spawn } from 'node:child_process';
 import { readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, relative } from 'node:path';
 
@@ -25,6 +32,17 @@ const indexed = (cwd, args) => {
 };
 
 const FETCH_EVERY_MS = 15_000;
+// A fetch beside the process, the network's part: its result is merged (locally, in one step) when it lands.
+const fetchAside = (cwd, branch, timeout = 120_000) => new Promise((resolve) => execFile('git', ['fetch', '--quiet', 'origin', branch], { cwd, timeout }, (error) => resolve(!error)));
+const fetching = new Map(); // checkout root → the fetch in flight (one at a time per checkout, in this process)
+const derived = new Set(); // boards (by their open document) whose owed commit this process has derived from git's state
+const pushDerived = new Set(); // checkouts whose owed push this process has derived
+
+/** The fetches in flight, landed and merged, until none is left: a process that exits after a write awaits this first. */
+export async function settleDocuments() {
+  // until none is left: a verb answered while one landed may have started another
+  while (fetching.size) await Promise.all([...fetching.values()]);
+}
 /** The background push: `git push`, then its error kept for `behind()` (or the last one cleared when it landed). */
 const PUSH = `const {spawnSync}=require('node:child_process'),fs=require('node:fs');const [branch,failure,temporary]=process.argv.slice(1);
 const r=spawnSync('git',['push','--quiet','origin','HEAD:'+branch],{encoding:'utf8',windowsHide:true});
@@ -40,6 +58,29 @@ export class GitDocument {
     this.merge = merge; // (base, theirs, ours, path) => text | null, ztrack's mergeBoardDocument
   }
 
+  /** Whether this board's owed commit is still to be derived in this process (its board calls `derive` after its first
+   *  recovery, when `paths` is its whole inventory). */
+  get underived() { return this.usable && !derived.has(this.paths[0]); }
+
+  /** What an earlier process left owed, from git's own state: this board's documents that differ from HEAD are
+   *  committed (a write, or a recovered one, that ended before its commit), and a HEAD ahead of its upstream is pushed.
+   *  Once per board per process, by the board, after its recovery and with every document it has in `paths`. */
+  derive() {
+    if (!this.usable) return;
+    derived.add(this.paths[0]);
+    this.commitDirty('board: documents written before this process started');
+    if (pushDerived.has(this.root)) return;
+    pushDerived.add(this.root);
+    const branch = this.branch();
+    if (branch && this.unpushed(branch) && !this.pushing) this.pushInBackground(branch);
+  }
+
+  /** This board's documents that differ from HEAD, committed as the board (a recovery's writes are no doer's). */
+  commitDirty(message) {
+    if (!this.usable) return;
+    if (quiet(this.root, ['status', '--porcelain', '--', ...this.paths.map((path) => this.rel(path))])?.trim()) this.commit(null, message);
+  }
+
   get usable() { return this.root !== null; }
   rel(path) { return relative(this.root, path); }
   /** The checkout's branch, or null on no branch (a detached HEAD has nowhere to push and nothing to pull). */
@@ -66,13 +107,31 @@ export class GitDocument {
     if (Date.now() - fetchedAt(this.root) < FETCH_EVERY_MS) return;
     const branch = this.branch();
     if (!branch) return this.detached();
-    if (this.unpushed(branch)) return this.pushing ? undefined : this.publish(branch, 'board');
-    if (quiet(this.root, ['fetch', '--quiet', 'origin', branch]) === null) return; // offline: the next write tries again
+    this.fetchThenTake(branch);
+  }
+
+  /** The fetch beside the process; when it lands, what was pushed is taken (take) in one local step. One at a time. */
+  fetchThenTake(branch, timeout) {
+    if (fetching.has(this.root)) return fetching.get(this.root);
+    const root = this.root;
+    const landing = fetchAside(root, branch, timeout).then((fetched) => {
+      if (!fetched) return; // offline: a later write asks again
+      try { this.take(branch); } catch (error) { current().err(`board: ${error.message}\n`); }
+    }).finally(() => fetching.delete(root));
+    fetching.set(root, landing);
+    return landing;
+  }
+
+  /** After a fetch: what was pushed merged into this checkout (local, serialized with this process's writes), then a
+   *  push of what this checkout holds that the remote lacks, beside the process. */
+  take(branch) {
     const behind = Number(git(this.root, ['rev-list', '--count', `HEAD..origin/${branch}`]).trim());
-    if (behind === 0) return;
-    const dirty = git(this.root, ['status', '--porcelain', '--', ...this.paths.map((path) => this.rel(path))]).trim();
-    if (dirty) return; // a write in progress publishes first and takes what was pushed after
-    this.integrate(branch, 'board');
+    if (behind > 0) {
+      const dirty = git(this.root, ['status', '--porcelain', '--', ...this.paths.map((path) => this.rel(path))]).trim();
+      if (dirty) return; // a write's documents are not committed yet: its commit is owed, and the next fetch takes this
+      this.integrate(branch, 'board');
+    }
+    if (this.unpushed(branch) && !this.pushing) this.pushInBackground(branch);
   }
 
   // After a write: commit the board documents as their doer, then push, taking anything pushed meanwhile.
@@ -136,9 +195,8 @@ export class GitDocument {
     if (!this.usable || this.pushing) return;
     const branch = this.branch();
     if (!branch || !this.unpushed(branch)) return;
-    // A remote that hangs costs the round 15 s, not git's two minutes.
-    if (quiet(this.root, ['fetch', '--quiet', 'origin', branch], 15_000) === null) return; // offline: the next round tries again
-    if (this.unpushed(branch)) this.publish(branch, 'board');
+    // A remote that hangs costs this fetch 15 s, beside the round, never the round.
+    this.fetchThenTake(branch, 15_000);
   }
 
   /** Whether this checkout holds board commits the remote does not have. */
@@ -146,16 +204,6 @@ export class GitDocument {
     return Number(quiet(this.root, ['rev-list', '--count', `origin/${branch}..HEAD`])?.trim() || 0) > 0;
   }
 
-  /** Push what this checkout holds, taking anything pushed meanwhile. */
-  publish(branch, who) {
-    for (let attempt = 0; attempt < 3; attempt++) {
-      if (quiet(this.root, ['push', '--quiet', 'origin', `HEAD:${branch}`]) !== null) { try { rmSync(this.failurePath(), { force: true }); } catch { /* none */ } return; }
-      if (quiet(this.root, ['fetch', '--quiet', 'origin', branch]) === null) throw new Error('the board documents were committed here but could not be pushed: the remote did not answer');
-      this.integrate(branch, who);
-    }
-    throw new Error('the board documents were committed here but the push was refused three times');
-  }
-
   // Take what was pushed with a merge: it works beside the other edits in this checkout (the manager's own files), which
   // a rebase refuses. A board document both sides changed is merged by the board's own document merge; any other
   // conflict leaves the checkout as it was and says so.

package/board/machine-fleet.mjs

@@ -4,32 +4,45 @@
 // (`capabilities`: its board process guard's harnesses, and whether it has the keyed launch door). Teams' session feed
 // is for viewers; dispatch never waits on it (D137, D138).
 //
-// Every machine is read at once, each within DEADLINE_MS (bin/machine-fleet.mjs), so one hung machine or relay costs a
+// Every machine is read at once, each within DEADLINE_MS, in this process through its door (doors.mjs), so one hung machine or relay costs a
 // reading that long, not the sum of them. A machine that answered is `online`. A remote machine that did not is
 // `unknown` (its runs are kept, as an unread machine's always were), unless the relay positively answered that it is
 // not linked (`machine_offline`): then it is offline. This machine's door not answering is no reading at all.
-import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
 import { noteStep } from '@volter/supercode-harness-sdk/slow-log';
+import { machineCall } from './doors.mjs';
 
-const entry = fileURLToPath(new URL('../bin/machine-fleet.mjs', import.meta.url));
 const DEADLINE_MS = 10_000;
+const within = (promise, ms) => Promise.race([promise, new Promise((_, reject) => setTimeout(() => reject(Object.assign(new Error(`no answer within ${ms} ms`), { code: 'timeout' })), ms).unref?.())]);
 
-/** One reading of `machines` (normalized names) and this machine, `local`. */
-export function readMachineFleet(machines, local) {
+// One machine's reading, through its door in this process (doors.mjs): its panes, what a board launch needs of it, and
+// the session under each live pane.
+async function readOne(name, at) {
+  const panes = await machineCall(at, 'harness.v1.panes.list', {});
+  // What a board launch needs of this machine: its board process guard (describe), and its keyed launch door, asked
+  // for a key no launch has (an answer of null is the door; an unknown method is its absence)
+  const description = await machineCall(at, 'harness.v1.machine.describe', {}).catch(() => null);
+  const keyed = await machineCall(at, 'harness.v1.launches.get', { key: 'board-capability-reading' }).then(() => null, (error) => String(error?.message ?? error).slice(0, 200));
+  const capabilities = { guard: description?.boardProcessPolicy?.version === 1 ? description.boardProcessPolicy.harnesses ?? [] : [], launches: keyed === null, launchesRefused: keyed };
+  const live = (Array.isArray(panes) ? panes : []).filter((pane) => !pane.dead && pane.pid);
+  // the session under each live pane: the harness stream, an operator's; a caller the machine admits only to its panes
+  // (a box another custodian enrolled, granting view and control) reads its panes and no sessions
+  let activities = [], sessionsUnread = null;
+  if (live.length) {
+    try { activities = (await machineCall(at, 'harness.v1.sessions.activity_under', { pids: live.map((pane) => pane.pid) }))?.activities ?? []; }
+    catch (error) { sessionsUnread = String(error?.message ?? error).slice(0, 200); }
+  }
+  return { machine: name, panes, activities, capabilities, sessionsUnread };
+}
+
+/** One reading of `machines` (normalized names) and this machine, `local`: every machine at once, each bounded. */
+export async function readMachineFleet(machines, local) {
   const names = [...new Set([local, ...machines])];
   const started = performance.now();
-  const reply = spawnSync(process.execPath, [entry], { input: JSON.stringify({ machines: names.map((name) => ({ name, at: name === local ? null : name })), deadlineMs: DEADLINE_MS }),
-    encoding: 'utf8', timeout: DEADLINE_MS + 5_000, maxBuffer: 64 * 1024 * 1024 });
+  const rows = await Promise.all(names.map((name) => within(readOne(name, name === local ? null : name), DEADLINE_MS)
+    .catch((error) => ({ machine: name, error: String(error?.message ?? error).slice(0, 300), code: error?.code ?? 'unavailable' }))));
   noteStep(`fleet reading (${names.length} machine${names.length === 1 ? '' : 's'})`, performance.now() - started);
-  let rows = null;
-  try { rows = JSON.parse(String(reply.stdout).trim().split('\n').pop()); } catch { /* no reading */ }
   // `panes`: each answering machine's live pane ids, whether or not a session was read in them
   const online = new Set(), unknown = new Set(), alive = new Set(), native = new Map(), sessions = [], capabilities = new Map(), panes = new Map();
-  if (!Array.isArray(rows)) {
-    const error = String(reply.stderr || reply.error?.message || 'no answer').trim().slice(-300);
-    return { ok: false, presenceKnown: false, online, unknown: new Set(names), alive, native, sessions, capabilities, panes, error: `the fleet reading did not answer: ${error}` };
-  }
   let localError = null;
   for (const row of rows) {
     if (row.error) {

package/board/runtime-door.mjs

@@ -1,16 +1,19 @@
-import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-import { noteStep } from '@volter/supercode-harness-sdk/slow-log';
-const entry = fileURLToPath(new URL('../bin/runtime-door.mjs',import.meta.url));
+// A machine's public door (`harness.v1.*`), called in this process through the held channel to its daemon (doors.mjs):
+// no helper process, nothing that waits on this process's event loop. Answered as the helper it replaces answered,
+// `{code, stdout, stderr}`, so a caller reads a door's refusal as it always did.
+import { machineCall } from './doors.mjs';
 
-/** Public machine RPC only; no Teams binary or implementation/state-file access. */
-export function runtimeDoor(machine,method,params={}, {env=process.env,timeout=60_000,as=null}={}) {
-  // a step of the running command (a dispatch round's slow-log line names its doors, and their time, by method)
-  const started = performance.now();
-  const result = spawnSync(process.execPath,[entry],{
-    input:JSON.stringify({machine,method,params}),encoding:'utf8',timeout,
-    env:{...env,...(as?{SUPERCODE_CALLER:as}:{})},maxBuffer:512*1024*1024,
-  });
-  noteStep(`door ${method}${machine ? ' (another machine)' : ''}`, performance.now() - started);
-  return {code:result.status,stdout:result.stdout??'',stderr:(result.stderr??'')+(result.error?.message??'')};
+/**
+ * One door call. `machine` null for this machine. `as`: the board this call acts for (`sc:<machine>:board:<name>`),
+ * named to the daemon as the caller, which it takes from the process that registered that board's home (machine.mjs).
+ */
+export async function runtimeDoor(machine, method, params = {}, { timeout = 60_000, as = null } = {}) {
+  try {
+    if (!method.startsWith('harness.v1.')) throw Object.assign(new Error('the runtime door accepts harness.v1 methods'), { code: 'invalid_request' });
+    const named = as && !method.startsWith('harness.v1.sessions.') ? { ...params, caller: as } : params;
+    const result = await machineCall(machine, method, named, { timeoutMs: timeout });
+    return { code: 0, stdout: `${JSON.stringify(result ?? null)}\n`, stderr: '' };
+  } catch (error) {
+    return { code: 1, stdout: '', stderr: `${JSON.stringify({ code: error?.code ?? 'unavailable', message: String(error?.message ?? error) })}\n` };
+  }
 }

package/board/tools.mjs

@@ -175,12 +175,12 @@ export async function boardTool(root, name, args = {}, env = {}) {
         return ok({ task_id: tid, attachments: tx(board, (db) => engine.attachments(db, tid)).map((a) => ({ id: a.id, filename: a.filename, size: a.size, content_type: a.content_type, path: a.stored_path })) });
       case 'kanban_create': {
         const workspace = args.workspace_kind ? `${args.workspace_kind}${args.workspace_path ? `:${args.workspace_path}` : ''}` : undefined;
-        const made = engine.createCard(board, {
+        const made = engine.createCard(board, await engine.prepareCard(board, {
           title: args.title, body: args.body ? redact(String(args.body)) : null, assignee: args.assignee ?? null, parents: [args.parents ?? []].flat(), tenant: args.tenant ?? null,
           priority: args.priority ?? 0, workspace, project: args.project ?? null, triage: Boolean(args.triage), idempotencyKey: args.idempotency_key ?? null,
           maxRuntime: args.max_runtime_seconds ?? null, initialStatus: args.initial_status ?? null, skills: args.skills ?? null, model: args.model ?? null, provider: args.provider ?? null,
           goal: args.goal_mode ? { maxTurns: args.goal_max_turns ?? null } : null, createdBy: author,
-        });
+        }));
         await engine.runEffects(board,made.effects??[]);
         return ok({ task_id: made.id, existing: made.existing, status: tx(board, (db) => engine.getTask(db, made.id)).status });
       }

package/board/workflow.mjs

@@ -6,7 +6,7 @@
 // pane, sending a session a message, cleaning a workspace) is answered as effects the caller runs after commit.
 import { current } from './call.mjs';
 import { notRuntime } from './owner-files.mjs';
-import { spawnSync, execFile } from 'node:child_process';
+import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { existsSync, readdirSync, realpathSync, watch, readFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
@@ -206,26 +206,27 @@ function pattern(p) {
 // 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();
-function observeLastCommit(path, id, branches = []) {
+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;
-  const git = (repo, args) => spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', timeout: 10_000 });
-  const readCommit = (repo) => {
-    const listed = git(repo, ['for-each-ref', '--format=%(refname)', 'refs/heads', 'refs/remotes']);
+  // 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 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 };
-    const current = git(repo, ['branch', '--show-current']).stdout?.trim();
-    const fallback = git(repo, ['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD']).stdout?.trim().replace(/^refs\/remotes\/origin\//, '');
+    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 };
-    const r = git(repo, ['log', ...refs, '--no-merges', '-1', '--format=%ct', '--fixed-strings', `--grep=${id}`, '--']);
+    const r = await git(repo, ['log', ...refs, '--no-merges', '-1', '--format=%ct', '--fixed-strings', `--grep=${id}`, '--']);
     const value = Number(r.stdout?.trim());
     return { repo: r.status === 0, value: Number.isFinite(value) && value > 0 ? value : null };
   };
-  const own = readCommit(path);
+  const own = await readCommit(path);
   let value = own.value;
   if (!own.repo) {
     // A fleet card may span sibling repositories under its declared workspace.
@@ -235,7 +236,7 @@ function observeLastCommit(path, id, branches = []) {
       if (!child.isDirectory() && !child.isSymbolicLink()) continue;
       const repo = resolve(path, child.name);
       if (!existsSync(resolve(repo, '.git'))) continue;
-      const t = readCommit(repo).value;
+      const t = (await readCommit(repo)).value;
       if (t != null) value = Math.max(value ?? 0, t);
     }
   }
@@ -245,7 +246,7 @@ function observeLastCommit(path, id, branches = []) {
 
 function lastCommitAt(path, id) { return path ? commitTimes.get(`${path}:${id}`)?.value ?? null : null; }
 /** Observe external facts before entering an optimistic board mutation. */
-export function refreshCardInputs(board, id, { commits = false } = {}) {
+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) {
@@ -253,7 +254,7 @@ export function refreshCardInputs(board, id, { commits = false } = {}) {
     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;
     if(path)commitTimes.delete(`${path}:${id}`);
-    observeLastCommit(path,id,declaredWorkBranches(board.db,id));
+    await observeLastCommit(path,id,declaredWorkBranches(board.db,id));
   }
 }
 

package/board/workspace.mjs

@@ -18,7 +18,7 @@ export const isWorkspacePath = value => /^(\/|~|[A-Za-z]:[\\/])/.test(value ?? '
 // The dispatcher's latest presence reading (observeFleet): a machine it reads as offline is not asked.
 let presence = null;
 export const notePresence = (reading) => { presence = reading; };
-function workspaceDoor(machine, verb, value, options = {}) {
+async function workspaceDoor(machine, verb, value, options = {}) {
   if (machine && presence?.known === true && normalMachine(machine) !== localMachine() && !presence.online.has(normalMachine(machine))) {
     throw new Error(`workspace on ${machine}: machine ${normalMachine(machine)} is offline`);
   }
@@ -27,39 +27,46 @@ function workspaceDoor(machine, verb, value, options = {}) {
   // none on a volume macOS guards, where the session that named the path does, and a verdict waited on the daemon's
   // EPERM. The daemon is asked when this process cannot read it.
   let own = null;
-  if (local && verb === 'inspect') { try { return inspectCheckout(value); } catch (error) { own = error; } }
+  if (local && verb === 'inspect') { try { return await inspectCheckout(value); } catch (error) { own = error; } }
   const params = verb === 'list' ? {} : verb === 'inspect' || verb === 'register' ? {path:value} : {repository:value,...options};
-  const r = runtimeDoor(local?null:machine,`harness.v1.workspaces.${verb}`,params,{env:commandEnv()});
+  const r = await runtimeDoor(local?null:machine,`harness.v1.workspaces.${verb}`,params,{env:commandEnv()});
   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);
 }
-export function declareWorkspace(kind, value, machine, branch = null) {
+/** 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) {
   if (kind === 'scratch') return { repository: null, branch: null, path: null };
   if (!value) throw new Error('workspace names a repository, for example worktree:volter-ai/editor');
   if (!isWorkspacePath(value)) return { repository: repositoryId(value), branch, path: null };
+  return null;
+}
+export async function declareWorkspace(kind, value, machine, branch = null) {
+  const plain = plainWorkspace(kind, value, branch);
+  if (plain) return plain;
   // A legacy path supplied explicitly is checked and registered on its machine, never copied into the card.
-  const info = workspaceDoor(machine, 'inspect', value);
+  const info = await workspaceDoor(machine, 'inspect', value);
   if (kind === 'worktree' && info.linked) throw new Error('worktree workspace already names a linked worktree; name its repository for a solo worktree');
   if (kind === 'dir' && !info.branch && !branch) throw new Error('a detached checkout has no portable branch identity; name the repository and a solo worktree branch');
-  const row = workspaceDoor(machine, 'register', value);
+  const row = await workspaceDoor(machine, 'register', value);
   return { repository: row.repository, branch: branch ?? (kind === 'dir' ? row.branch : null), path: kind === 'dir' ? row.path : null };
 }
 /** The checkouts this machine keeps of any repository on `branch`: where an arc changing several repositories
  *  keeps its work in each of them (its own worktree aside). Another machine's map is not read from here. */
-export function branchCheckouts(machine, branch) {
+export async function branchCheckouts(machine, branch) {
   if (!branch || (machine && normalMachine(machine) !== localMachine())) return [];
-  const listed = workspaceDoor(null, 'list', null);
+  const listed = await workspaceDoor(null, 'list', null);
   return (Array.isArray(listed) ? listed : listed.workspaces ?? listed.items ?? []).filter((row) => (branch === '*' || row.branch === branch) && existsSync(row.path));
 }
 /** The registered checkout of `repository` on `branch` on `machine`: where a card changing several repositories
  *  keeps its work in each of them. */
-export function checkoutOf(machine, repository, branch) {
+export async function checkoutOf(machine, repository, branch) {
   return workspaceDoor(machine, 'resolve', repositoryId(repository), { branch });
 }
-export function resolveWorkspace(task, create = false) {
+export async function resolveWorkspace(task, create = false) {
   const declared = task.workspace_anchor ?? task.workspace_path;
   if (isWorkspacePath(declared)) {
-    const info = workspaceDoor(task.machine, 'inspect', declared);
+    const info = await workspaceDoor(task.machine, 'inspect', declared);
     if (task.workspace_kind === 'dir') return info;
     if (info.linked) throw new Error('worktree declaration is already a linked worktree; name its repository instead');
     throw new Error('legacy worktree path needs registration and a repository declaration before launch');
@@ -70,7 +77,7 @@ export function resolveWorkspace(task, create = false) {
   if (task.workspace_kind === 'worktree' && task.workspace_path &&
       basename(task.workspace_path) === task.id && basename(dirname(task.workspace_path)) === '.worktrees' &&
       (!isLocalWorkspace(task) || existsSync(task.workspace_path))) {
-    const cached = workspaceDoor(task.machine, 'inspect', task.workspace_path);
+    const cached = await workspaceDoor(task.machine, 'inspect', task.workspace_path);
     if (cached.linked && basename(cached.path) === task.id && basename(dirname(cached.path)) === '.worktrees' &&
         cached.repository === repositoryId(declared) && cached.branch === (task.branch_name ?? `wt/${task.id}`)) {
       return { ...cached, root: dirname(dirname(cached.path)) };
@@ -79,14 +86,14 @@ export function resolveWorkspace(task, create = false) {
   }
   return workspaceDoor(task.machine, 'resolve', declared, { branch: task.branch_name, solo: task.workspace_kind === 'worktree', card: task.id, create });
 }
-export function checkWorkspace(board, task) {
+export async function checkWorkspace(board, task) {
   if (task.workspace_kind === 'scratch') return null;
-  const facts = resolveWorkspace(task), peers = [];
+  const facts = await resolveWorkspace(task), peers = [];
   if (task.workspace_kind === 'dir' && !facts.linked) {
     for (const row of board.db.prepare(`SELECT t.id,t.workspace_path,t.branch_name,c.workspace_anchor,c.machine FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.current_run_id IS NOT NULL AND t.workspace_kind='dir'`).all()) {
       if (row.id === task.id || normalMachine(row.machine ?? localMachine()) !== normalMachine(task.machine ?? localMachine())) continue;
       let other;
-      try { other = resolveWorkspace({ ...row, workspace_kind: 'dir' }); } catch { continue; } // That card's own launch reports its invalid workspace.
+      try { other = await resolveWorkspace({ ...row, workspace_kind: 'dir' }); } catch { continue; } // That card's own launch reports its invalid workspace.
       if (!other.linked && other.root === facts.root) peers.push(row.id);
     }
   }