@volter/supercode-orchestrator 0.5.69 → 0.5.70

package/board/ztrack.mjs

@@ -7,6 +7,8 @@
 // triggers name the rows it touched. Only the cards whose text changed are rendered, and each is
 // spliced into the document at its indexed span. A document edited by hand is re-read only in the
 // region the edit touched. So a write costs what it changes, not the size of the board.
+import { current } from './call.mjs';
+import { fenced } from './fence.mjs';
 import { createRequire } from 'node:module';
 import { createHash, randomBytes } from 'node:crypto';
 import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
@@ -74,10 +76,9 @@ export function openZtrackBoard(marker, { create = false, document = null, decla
   }
   const config = JSON.parse(read(marker));
   const backing = new ZtrackBoard({ ...config, seed, marker, init, root, slug });
-  return { db: backing.db, tx: (fn) => backing.tx(fn), publishPending: () => backing.git?.publishPending(), close: () => backing.close(), document: backing.path };
+  return { db: backing.db, tx: (fn) => backing.tx(fn), publishPending: () => backing.git?.publishPending(), unimported: () => backing.unimported(), close: () => backing.close(), document: backing.path };
 }
 
-const behindSaid = new Set(), heartbeatSaid = new Set();
 
 class ZtrackBoard {
   constructor({ document, seed, marker, init, root, slug, commit = false, manager = null, archive = {} }) {
@@ -94,23 +95,24 @@ class ZtrackBoard {
     // own work; the backing commits only the writes the manager does not make.
     this.manager = manager;
     this.git = commit ? new GitDocument(this.baseDocs.map((doc) => doc.path), (base, theirs, ours, path) => { try { return this.codec.mergeBoardDocument(base, theirs, ours, path)?.text ?? null; } catch { return null; } }) : null;
-    // A publish that is behind is said once per process, on whichever workflow verb opened the board: a refused push
+    // A publish that is behind is said once per call, on whichever workflow verb opened the board: a refused push
     // surfaces on the next call instead of only in the dispatcher's report, and stops being said once the push lands.
-    if (this.git && !behindSaid.has(this.path)) {
-      behindSaid.add(this.path);
+    const said = current().said;
+    if (this.git && !said.has(`behind:${this.path}`)) {
+      said.add(`behind:${this.path}`);
       const late = this.git.behind();
       // A push younger than a minute is still on its way.
-      if (late && Date.now() - late.since > 60_000) process.stderr.write(`board: warning: ${late.commits} board document commit${late.commits === 1 ? '' : 's'} not published since ${new Date(late.since).toISOString().slice(0, 16)}Z${late.error ? ` (last push: ${late.error})` : ''}; the dispatcher's next round retries\n`);
+      if (late && Date.now() - late.since > 60_000) current().err(`board: warning: ${late.commits} board document commit${late.commits === 1 ? '' : 's'} not published since ${new Date(late.since).toISOString().slice(0, 16)}Z${late.error ? ` (last push: ${late.error})` : ''}; the dispatcher's next round retries\n`);
     }
     // The dispatcher's standing errors are said the same way, on every workflow call until a round clears them: a round
     // that has not completed in five minutes, and each card or run the last round could not start, read or sync.
-    if (root && !heartbeatSaid.has(root)) {
-      heartbeatSaid.add(root);
+    if (root && !said.has(`heartbeat:${root}`)) {
+      said.add(`heartbeat:${root}`);
       try {
         const beat = JSON.parse(readFileSync(join(root, 'dispatcher-heartbeat.json'), 'utf8'));
         const age = Date.now() - Date.parse(beat.at);
-        if (age > 300_000) process.stderr.write(`board: error: the dispatcher has completed no round since ${String(beat.at).slice(0, 16)}Z; nothing starts, moves or is supervised\n`);
-        for (const error of beat.errors ?? []) process.stderr.write(`board: error: ${error}\n`);
+        if (age > 300_000) current().err(`board: error: the dispatcher has completed no round since ${String(beat.at).slice(0, 16)}Z; nothing starts, moves or is supervised\n`);
+        for (const error of beat.errors ?? []) current().err(`board: error: ${error}\n`);
       } catch { /* a board no dispatcher serves yet has no heartbeat */ }
     }
     this.seed = seed; this.root = root; this.slug = slug; this.init = init;
@@ -256,6 +258,7 @@ class ZtrackBoard {
       if (keys.length) db.prepare(`INSERT OR REPLACE INTO ${quote(name)} (${keys.map(quote).join(',')}) VALUES (${keys.map(() => '?').join(',')})`).run(...keys.map((k) => row[k] ?? null));
     };
     db.exec('BEGIN');
+    fenced(db);
     const runtime = {}, clocks = {}, sequences = [];
     for (const row of old.prepare('SELECT name, key, value FROM runtime_rows WHERE value IS NOT NULL').all()) {
       const value = JSON.parse(row.value);
@@ -354,7 +357,7 @@ class ZtrackBoard {
     // the repair is said, so a span length written wrong stays visible
     const measured = (doc) => {
       const gap = lf(doc.raw).length - this.entries(doc.role).reduce((sum, e) => sum + e.len, 0);
-      if (gap) process.stderr.write(`board: warning: ${doc.path}: its index spans measure ${Math.abs(gap)} character${Math.abs(gap) === 1 ? '' : 's'} ${gap > 0 ? 'short of' : 'past'} its text; this write reads it again\n`);
+      if (gap) current().err(`board: warning: ${doc.path}: its index spans measure ${Math.abs(gap)} character${Math.abs(gap) === 1 ? '' : 's'} ${gap > 0 ? 'short of' : 'past'} its text; this write reads it again\n`);
       return !gap;
     };
     return this.docs.map((doc) => ({ ...doc, ...this.fileHash(doc.path) }))
@@ -376,6 +379,12 @@ class ZtrackBoard {
     this.applyPlan(plan, { overlay: true });
   }
 
+  // Whether a document holds an edit its tables have not imported (a hand edit, a git update): the publication owner
+  // enters a transaction for it, which imports it and so marks its cards. Unreadable reads as yes: the write reports it.
+  unimported() {
+    try { return this.staleDocuments({ pending: true }).length > 0; } catch { return true; }
+  }
+
   dropOverlay() {
     if (!this.overlay) return;
     this.conn.exec('DROP TABLE IF EXISTS temp.tasks; DROP TABLE IF EXISTS temp.supercode_cards; DROP TABLE IF EXISTS temp.task_links');
@@ -389,7 +398,7 @@ class ZtrackBoard {
     if (this.active) return fn(this.db);
     // A pull request merged on the remote (a page edited in Git Notes) is in the document before this write reads it.
     if (this.git) this.git.paths = this.docs.map((doc) => doc.path);
-    try { timedStep('board git pull', () => this.git?.pull()); } catch (error) { process.stderr.write(`board: ${error.message}\n`); }
+    try { timedStep('board git pull', () => this.git?.pull()); } catch (error) { current().err(`board: ${error.message}\n`); }
     let txStarted = 0;
     for (let attempt = 0; ; attempt++) {
       let outcome;
@@ -397,6 +406,7 @@ class ZtrackBoard {
         txStarted = performance.now();
         this.dropOverlay();
         this.conn.exec('BEGIN');
+        fenced(this.conn);
         this.active = true; this.contended = false;
         this.conn.exec('DELETE FROM temp.board_dirty; DELETE FROM temp.board_touched');
         this.refused = new Set();
@@ -437,7 +447,7 @@ class ZtrackBoard {
         const byManager = this.manager !== null && (actorOf() === this.manager || principalOf() === this.manager);
         if (this.git) this.git.paths = this.docs.map((doc) => doc.path);
         if (!byManager) try { timedStep('board git commit and push', () => this.git?.commit(actorOf(), `board: ${outcome.files.map((file) => basename(file.path)).join(', ')} written for ${actorOf() ?? 'the board'}`)); }
-        catch (error) { process.stderr.write(`board: ${error.message}\n`); }
+        catch (error) { current().err(`board: ${error.message}\n`); }
       }
       return outcome.result;
     }
@@ -463,7 +473,7 @@ class ZtrackBoard {
   // A short write of board state alone, retried on contention.
   small(fn) {
     for (let attempt = 0; ; attempt++) {
-      try { this.conn.exec('BEGIN'); fn(); this.conn.exec('COMMIT'); return; }
+      try { this.conn.exec('BEGIN'); fenced(this.conn); fn(); this.conn.exec('COMMIT'); return; }
       catch (error) { try { this.conn.exec('ROLLBACK'); } catch { /* not begun */ } if (!sqliteContention(error)) throw error; backoff(attempt); }
     }
   }

package/hand-off.mjs

@@ -15,12 +15,12 @@ import { fileURLToPath } from 'node:url';
 
 /** The home a command (the whole of it, after the entry) names: --root, wherever it stands (the gateway's form,
  *  `node bin/orchestrator.mjs --root <home>`, has no verb before it); for `import`, which writes the home it names
- *  with --into, that; else the environment the orchestrator reads (SUPERCODE_ORCHESTRATOR_HOME, HERMES_HOME).
+ *  with --into, that; else the home's own variable (SUPERCODE_ORCHESTRATOR_HOME).
  *  (`export` names the home it reads with --from and writes none.) */
 export function homeOfArgs(argv, env = process.env) {
   const flag = argv[0] === 'import' ? '--into' : '--root';
   const at = argv.findIndex((arg) => arg === flag || arg.startsWith(`${flag}=`));
-  const named = at < 0 ? env.SUPERCODE_ORCHESTRATOR_HOME ?? env.HERMES_HOME : argv[at].startsWith(`${flag}=`) ? argv[at].slice(flag.length + 1) : argv[at + 1];
+  const named = at < 0 ? env.SUPERCODE_ORCHESTRATOR_HOME : argv[at].startsWith(`${flag}=`) ? argv[at].slice(flag.length + 1) : argv[at + 1];
   return named ? resolve(named) : null;
 }
 

package/index.d.ts

@@ -113,7 +113,7 @@ export function declareAgentIntent(options: {root: Path; org: string; server: st
 export function agentRunForKey(root: Path, org: string, agent: string, key: string): Record<string, unknown> | null;
 export function agentIntent(root: Path, org: string, id: string): Record<string, unknown> | null;
 export function assignAgent(root: Path, org: string, id: string, assignment: {kind: string; target: string; role: string}): string;
-export function reassignAgent(root: Path, org: string, assignment: string, to: string, options?: {context?: string}): Record<string, unknown>;
+export function reassignAgent(root: Path, org: string, assignment: string, to: string, options?: {context?: string}): Promise<Record<string, unknown>>;
 export function activeAgentAssignments(root: Path): Array<Record<string, unknown>>;
 export function finishAgentAssignment(root: Path, org: string, assignment: string, reason: string): void;
 export function recordAgentRun(root: Path, org: string, id: string, run: {session: string; machine?: string | null; run: string | number; profile?: unknown; main?: boolean; starterSession?: string | null}): void;

package/kanban-worker.mjs

@@ -18,8 +18,7 @@ import { KANBAN_ENV, untrustedServerVerdict, hermesApproval, hermesInstall, memo
 import { pinnedSkills, taskProtocol } from './board/worker-prompt.mjs';
 import { mountOrchestratorMcp } from './mcp/mount.mjs';
 import { normalizeWorkerEvent, widensSandbox } from './loop.mjs';
-import { DEFAULT_BOARD, json, openBoard, tx } from './board/store.mjs';
-import { setRunSession } from './board/engine.mjs';
+import { askBoardOwner, callerFacts } from '@volter/teams/board-owner';
 import { permissionResponse } from './reducer.mjs';
 import { boardGuardArguments } from '@volter/teams/board-process-guard';
 
@@ -98,7 +97,7 @@ async function runTurn({ client, profile, harness, worker, route, root, vault, s
   const mount = mountOrchestratorMcp({ root, profile, harness, surfaceKey, launch, vault, task });
   const policy = approvalPolicy(profile, harness);
   const runtime = await client.startManagedRuntime({ harness, cwd, launch: mount.launch, ...(mount.mcp_servers ? { mcp_servers: mount.mcp_servers } : {}), ...(policy ? { approval_policy: policy } : {}) });
-  try { recordSession(root, task, harness, runtime.handle.runtime_id); } catch (error) { say(`hermes-worker: recording the session on its run: ${error.message}`); }
+  try { await recordSession(root, task, harness, runtime.handle.runtime_id); } catch (error) { say(`hermes-worker: recording the session on its run: ${error.message}`); }
   let text = '';
   // `agent.max_turns` for a worker that takes no cap at launch, held as the daemon holds it (loop.mjs `holdTurnLimit`)
   const counter = turnCounter(profile, harness);
@@ -147,21 +146,17 @@ async function runTurn({ client, profile, harness, worker, route, root, vault, s
 
 /**
  * The worker's session on its run, where supercode keeps it (`metadata.supercode.session_id`, beside the pid the
- * dispatcher recorded): the harness's own transcript, found and resumed by supercode like any session.
+ * dispatcher recorded): the harness's own transcript, found and resumed by supercode like any session. Written by the
+ * board's owner, as every board write is (`workflow run-session`).
  */
-function recordSession(root, task, harness, sessionId) {
+async function recordSession(root, task, harness, sessionId) {
   if (!task.HERMES_KANBAN_RUN_ID || !sessionId) return;
-  const board = openBoard(root, task.HERMES_KANBAN_BOARD || DEFAULT_BOARD);
-  try {
-    tx(board, (db) => {
-      const row = db.prepare('SELECT metadata FROM task_runs WHERE id = ?').get(Number(task.HERMES_KANBAN_RUN_ID));
-      if (!row) return;
-      const meta = json(row.metadata, {}) ?? {};
-      setRunSession(db, Number(task.HERMES_KANBAN_RUN_ID), { ...(meta.supercode ?? {}), session_id: sessionId, harness });
-    });
-  } finally {
-    board.close();
-  }
+  const answer = await askBoardOwner(root, {
+    argv: ['run-session', String(task.HERMES_KANBAN_RUN_ID), String(sessionId), '--harness', harness, '--task', String(task.HERMES_KANBAN_TASK ?? '')],
+    board: task.HERMES_KANBAN_BOARD || null, caller: null, session: null, cwd: process.cwd(), stdin: null,
+    facts: { ...callerFacts(), SUPERCODE_CONTEXT: process.env.SUPERCODE_CONTEXT || 'local' },
+  });
+  if (answer.code) throw new Error((answer.stderr || 'the board owner did not record it').trim());
 }
 
 /** A profile whose worker is Hermes: the dispatcher's own command, run as Hermes would have run it. */

package/loop.mjs

@@ -25,7 +25,7 @@ import { checkMonitor, runJobScript } from './gates.mjs';
 import { SenderIdentityRecord } from '@volter/teams/sender-identity';
 import { agentScope,localProfileAgent,localAgentRecord,localAgentSessions,localForkAgent,handOffAgents,localReaderContext,agentRunForKey,agentPreamble,agentEnvironment,recordAgentRun,recordNativeAgentSession,agentRunForSession } from './agents.mjs';
 import { materializeAgentHome } from './agent-home.mjs';
-import { localMachine } from './board/dispatch.mjs';
+import { knowLocalMachine } from './board/dispatch.mjs';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 
@@ -60,7 +60,7 @@ export class Orchestrator {
     this.identityRecord = new SenderIdentityRecord();
     state.runtime ??= {};
     state.runtime.hostedJobs = !!executeJob;
-    state.runtime.machine = localMachine(); // a job naming another machine fires there (cron.mjs startFire)
+    state.runtime.machine = null; // learned at start(): a job naming another machine fires there (cron.mjs startFire)
     state.runtime.hostedFires = {};
     this.vault = vault;
     // each profile's cron/jobs.json as the state was loaded from it: what changes there later was written by another hand
@@ -84,6 +84,7 @@ export class Orchestrator {
 
   async start() {
     retainWorld();
+    this.state.runtime.machine = await knowLocalMachine();
     for (const [platform, adapter] of Object.entries(this.adapters)) await this.connectAdapter(platform, adapter);
     this.webhooks = await startWebhookListener({
       state: this.state, vault: this.vault, port: webhookPort(this.state),

package/mcp/server.mjs

@@ -16,12 +16,13 @@
 // `supercode mcp serve` are a different server for a different purpose and are
 // untouched by this one.
 
+import { knowLocalMachine } from '../board/dispatch.mjs';
 import { createInterface } from 'node:readline';
 import { connect } from 'node:net';
 import { join } from 'node:path';
 import { KANBAN_TOOLS, PROTOCOL_VERSION, SERVER_NAME, TOOLS } from './tools.mjs';
 import { KANBAN_ENV } from '../hermes-cli.mjs';
-import { boardTool } from '../board/tools.mjs';
+import { askBoardOwner, callerFacts } from '@volter/teams/board-owner';
 
 /** Env var naming the socket, when the loop wants one off the root's default. */
 export const SOCKET_ENV = 'SUPERCODE_ORCHESTRATOR_SOCK';
@@ -56,16 +57,17 @@ const HERMES_ANSWERED = new Set(['session_search', 'memory', 'skills_list', 'ski
 const published = (binding) => (binding.kanban ? [...TOOLS.filter((t) => !HERMES_ANSWERED.has(t.name)), ...KANBAN_TOOLS] : TOOLS);
 
 /**
- * A board tool, answered by supercode's own board (board/tools.mjs) on the home's board file: the task, its run and
- * its claim are this worker's environment, as they are a Hermes worker's, never the daemon's.
+ * A board tool, answered by the board's owner (board/tools.mjs, in the owner's process): the board has one writer.
+ * The task, its run and its claim are this worker's environment, as they are a Hermes worker's, never the daemon's.
  */
 async function kanbanCall(binding, name, args) {
-  try {
-    const out = await boardTool(binding.root, name, args, binding.kanban ?? {});
-    return { ok: true, result: { ran: name, verbatim: out } };
-  } catch (error) {
-    return { ok: false, error: error.message };
-  }
+  const answer = await askBoardOwner(binding.root, {
+    tool: { name, args, env: binding.kanban ?? {} },
+    board: binding.kanban?.HERMES_KANBAN_BOARD ?? null, caller: null, session: null, cwd: binding.root, stdin: null,
+    facts: { ...callerFacts(), SUPERCODE_CONTEXT: process.env.SUPERCODE_CONTEXT || 'local' },
+  });
+  if (answer.code) return { ok: false, error: (answer.stderr || 'the board owner did not answer').trim() };
+  return { ok: true, result: { ran: name, verbatim: answer.stdout } };
 }
 
 /**
@@ -96,6 +98,7 @@ export function ask(binding, verb, args) {
 
 /** `crates/harness/src/mcp.rs::handle_request`'s shape, in JavaScript. */
 export async function handleRequest(binding, request) {
+  await knowLocalMachine();
   const id = request?.id;
   const method = request?.method ?? '';
   const reply = (result) => ({ jsonrpc: '2.0', id, result });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.69",
+  "version": "0.5.70",
   "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": {
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@volter/supercode-harness-sdk": "^0.3.60",
-    "@volter/teams": "0.2.20",
+    "@volter/teams": "0.2.23",
     "@volter/ztrack": "^2.4.23",
     "yaml": "^2.9.0"
   },

package/bin/agent-door.mjs

@@ -1,53 +0,0 @@
-#!/usr/bin/env node
-// The orchestrator's synchronous host reaches Teams through the installed neutral SDK.
-import { fromContext, WorkspaceContexts } from '@volter/teams/context';
-import { supercodeHome } from '@volter/teams/home';
-import { openMachine, normalMachineName } from '@volter/teams/machine-door';
-import { hostname } from 'node:os';
-import { StreamRpc } from '@volter/teams/client';
-// This machine is reached through its own daemon's socket, never through the Teams server: the server route lists the
-// org's machines and opens a channel on the shared credential's allowance for a request that never leaves the box.
-const reach=machine=>machine&&normalMachineName(machine)!==normalMachineName(hostname())?machine:null;
-let input='';for await(const chunk of process.stdin)input+=chunk;
-try{
-  const {op,args=[],context}=JSON.parse(input);
-  // No context selected: identity is this home's own (Org `local`). A context that is named but unreadable is an error.
-  const named=context??process.env.SUPERCODE_CONTEXT??new WorkspaceContexts(supercodeHome()).read().current;
-  if(op==='scope'&&(!named||named==='local')){process.stdout.write(JSON.stringify({server:'local',org:'local',principal:null,offline:true,reason:'no Teams context is selected'})+'\n');process.exit(0);}
-  const {client,context:scope}=fromContext({supercodeHome:supercodeHome(),name:context??process.env.SUPERCODE_CONTEXT});
-  const team=client.team(scope.team_id),options={signal:AbortSignal.timeout(20000)};
-  let result;
-  if(op==='scope')result={server:scope.origin,server_id:scope.server_id,org:scope.team_id,principal:scope.principal_id};
-  else if(op==='root')result=await team.agents.root(options);
-  else if(op==='get')result=await team.agents.get(args[0],options);
-  else if(op==='management')result=await team.agents.management(args[0],options);
-  else if(op==='profile')result=await team.agents.update(args[0],{profile:args[1]},{...options,ifMatch:args[2]});
-  else if(op==='reparent')result=await team.agents.update(args[0],{parent:args[1]},{...options,ifMatch:args[2]});
-  else if(op==='declare')result=await team.agents.declare(args[0],{...options,idempotencyKey:args[1]});
-  else if(op==='sessions')result=await team.agents.sessions(args[0],args[1]??{},options);
-  else if(op==='ownSession')result=await team.agents.ownSession(args[0],args[1],{...options,idempotencyKey:args[2]});
-  else if(op==='session')result=await team.sessions.get(args[0]).identity(options);
-  else if(op==='end'){
-    const agent=(await team.agents.get(args[0],options)).data;
-    result=agent.state==='ended'?{data:{id:agent.id,state:'ended'}}:await team.agents.end(agent.id,{reason:args[1]},{...options,ifMatch:agent.revision,idempotencyKey:args[2]});
-  }
-  else if(op==='reader')result=await team.agents.delegateReader(args[0],{},{...options,ifMatch:args[1]});
-  else if(op==='readerContext'){
-    const identity=await team.agents.get(args[0],options);
-    const reader=await team.agents.delegateReader(args[0],{expires_in_ms:86400000},{...options,ifMatch:identity.data.revision});
-    const channel=await openMachine({machine:reach(args[1]),context:context??process.env.SUPERCODE_CONTEXT});
-    try{const rpc=new StreamRpc(await channel.open('node'));result=await rpc.call('harness.v1.agents.context',{origin:scope.origin,team:scope.team_id,agent:args[0],credential:reader.data});}
-    finally{channel.close();}
-  }
-  else if(op==='resolveIdentity')result=await team.identity.resolve(args[0],options);
-  else if(op==='find'){
-    let after='',found=null;
-    do{
-      const page=await team.agents.list({after,limit:200},options);
-      found=page.items.find(agent=>agent.name===args[0]&&agent.parent===args[1]&&agent.state!=='ended')??null;
-      if(found)break;after=page.next_after;
-    }while(after);
-    result={data:found};
-  }else throw Object.assign(new Error('unsupported agent door'),{code:'invalid_request'});
-  process.stdout.write(JSON.stringify(result)+'\n');
-}catch(error){process.stderr.write(JSON.stringify({status:error.status,code:error.code??'unavailable',message:error.message})+'\n');process.exitCode=1;}