@volter/supercode-orchestrator 0.5.73 → 0.5.75

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);
     }
   }

package/board/ztrack.mjs

@@ -17,6 +17,7 @@ import { DatabaseSync } from 'node:sqlite';
 import { actorOf, contention, event, json, now, principalOf } from './store.mjs';
 import { GitDocument } from './git-document.mjs';
 import { noteStep, recordSlow } from '@volter/supercode-harness-sdk/slow-log';
+import * as slowLog from '@volter/supercode-harness-sdk/slow-log';
 
 /** Run `fn` as a named step of the running command (the slow log names its slowest step). */
 const timedStep = (step, fn) => { const started = performance.now(); try { return fn(); } finally { noteStep(step, performance.now() - started); } };
@@ -100,7 +101,7 @@ class ZtrackBoard {
     const said = current().said;
     if (this.git && !said.has(`behind:${this.path}`)) {
       said.add(`behind:${this.path}`);
-      const late = this.git.behind();
+      const late = timedStep('board open git behind', () => this.git.behind());
       // A push younger than a minute is still on its way.
       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`);
     }
@@ -112,12 +113,12 @@ class ZtrackBoard {
     // `sqlite3 <store> "select …"` made the empty file the next release then opened instead of importing).
     if (existsSync(this.file) && statSync(this.file).size === 0) unlinkSync(this.file);
     if (!existsSync(this.file)) this.create(legacy);
-    this.conn = new DatabaseSync(this.file);
+    this.conn = timedStep('board open connection', () => new DatabaseSync(this.file));
     this.refuseUnimported(legacy);
     this.errors = new Map(); this.statements = new Map(); this.hashes = new Map();
     this.active = false; this.overlay = false; this.seen = null; this.refused = new Set();
-    this.prepareConnection();
-    this.loadErrors();
+    timedStep('board open schema', () => this.prepareConnection());
+    timedStep('board open errors', () => this.loadErrors());
     const self = this;
     this.db = {
       boardErrors: self.errors,
@@ -132,7 +133,9 @@ class ZtrackBoard {
       exec(sql) { return self.active ? self.noting(() => self.conn.exec(sql)) : self.tx(() => self.conn.exec(sql)); },
       close() { self.close(); },
     };
-    if (seed) this.tx(() => {});
+    // A board's first open in this process recovers what its store accepted and derives what git owes for it (tx), so
+    // a board that is only read, or whose owner runs no round, still finishes an earlier process's commit.
+    if (seed || this.git?.underived) this.tx(() => {});
   }
   // The board's documents: the open one, the current archive, and each rotated archive (recorded in the board's own
   // state, so a rotation committed but not yet written is still a document of the board).
@@ -394,13 +397,12 @@ class ZtrackBoard {
       try {
         txStarted = performance.now();
         this.dropOverlay();
-        this.conn.exec('BEGIN');
-        fenced(this.conn);
+        timedStep('board tx begin', () => { 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();
         timedStep('board tx errors', () => this.loadErrors());
-        timedStep('board tx recover', () => this.recover());
+        const recovered = timedStep('board tx recover', () => this.recover());
         if (this.seed) this.indexForSeed();
         else {
           const stale = timedStep('board tx stale check', () => this.staleDocuments({ pending: false }));
@@ -416,13 +418,13 @@ class ZtrackBoard {
           this.put('pending', { intent, files });
           this.put('pending_hashes', Object.fromEntries(files.map((f) => [f.role, { before: f.before, after: f.after }])));
         }
-        this.conn.exec('COMMIT');
+        timedStep('board tx commit', () => this.conn.exec('COMMIT'));
         // A long transaction holds every other writer of this board (the dispatcher's tick included), so it is a line
         // of its own in the slow log, from whichever process ran it.
         const held = performance.now() - txStarted;
         noteStep('board transaction', held);
-        recordSlow({ kind: 'call', name: 'board transaction', ms: held, slowest: null, extra: { board: this.path } });
-        outcome = { result, files, intent };
+        recordSlow({ kind: 'call', name: 'board transaction', ms: held, slowest: null, extra: { board: this.path, steps: slowLog.stepsWithin?.(txStarted, performance.now()) ?? null } });
+        outcome = { result, files, intent, recovered };
       } catch (error) {
         try { this.conn.exec('ROLLBACK'); } catch { /* not begun */ }
         this.active = false; this.seen = null; this.loadErrors();
@@ -430,6 +432,13 @@ class ZtrackBoard {
         throw error;
       } finally { this.active = false; }
       this.seed = null;
+      // What an earlier process left owed in git is derived once this board's recovery has written what its store
+      // accepted, with every document the board has; a recovery in any later write is committed the same way.
+      if (this.git && (this.git.underived || outcome.recovered)) {
+        this.git.paths = this.docs.map((doc) => doc.path);
+        try { timedStep('board git derive', () => outcome.recovered && !this.git.underived ? this.git.commitDirty('board: documents another write accepted') : this.git.derive()); }
+        catch (error) { current().err(`board: ${error.message}\n`); }
+      }
       if (outcome.intent) {
         this.publish(outcome);
         // Committed as the session (or person) whose act this write was, and pushed.
@@ -471,7 +480,7 @@ class ZtrackBoard {
   // document it replaced; merge it into a document edited since (the hand edit wins its cards).
   recover() {
     const pending = this.get('pending');
-    if (!pending) return;
+    if (!pending) return false;
     for (const file of pending.files) {
       const current = this.fileHash(file.path);
       if (current.hash === file.after) continue;
@@ -483,6 +492,7 @@ class ZtrackBoard {
       if (merged) atomic(file.path, merged.text);
     }
     this.drop('pending'); this.drop('pending_hashes');
+    return true;
   }
 
   // ------------------------------------------------------------------ the document index

package/hermes-cli.mjs

@@ -4,8 +4,8 @@
 // pinned `hermes` on its `PATH`; and what Hermes's scheduler records about a failed run (its incidents,
 // in `cron/executions.db`) the orchestrator records through Hermes's own function.
 import { spawn, spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { accessSync, constants, existsSync, readFileSync, statSync } from 'node:fs';
+import { delimiter, dirname, join } from 'node:path';
 import { parseDotenv } from './orchestration.mjs';
 import { locateHermes } from './apply/doors.mjs';
 
@@ -28,7 +28,8 @@ let located;
 export function hermesInstall() {
   if (located !== undefined) return located;
   try {
-    const which = spawnSync('sh', ['-c', 'command -v hermes'], { encoding: 'utf8' }).stdout.trim();
+    // `hermes` on PATH, found by the file system (no shell started for it)
+    const which = String(process.env.PATH ?? '').split(delimiter).filter(Boolean).map((dir) => join(dir, 'hermes')).find((path) => { try { accessSync(path, constants.X_OK); return statSync(path).isFile(); } catch { return false; } }) ?? '';
     located = which ? { bin: dirname(which), ...locateHermes() } : null;
   } catch {
     located = null;
@@ -350,15 +351,6 @@ export async function memorySnapshot(profileDir) {
   return runHermes(profileDir, { op: 'snapshot' });
 }
 
-/** memorySnapshot for a synchronous caller (the board's launch). An unreadable store contributes nothing. */
-export function memorySnapshotSync(profileDir) {
-  const install = hermesInstall();
-  if (!install?.python) return '';
-  const run = spawnSync(install.python, ['-c', HERMES_TOOL], { input: JSON.stringify({ op: 'snapshot' }), encoding: 'utf8', timeout: 30_000, cwd: install.source, env: hermesEnv(install, profileDir) });
-  try { const out = hermesAnswer('snapshot', { stdout: run.stdout ?? '', stderr: run.stderr || run.error?.message || '' }); return typeof out === 'string' ? out : ''; }
-  catch { return ''; }
-}
-
 /**
  * A schedule string as Hermes parses it (`{ kind: once|interval|cron, … }`), or null when no Hermes is
  * installed; throws Hermes's own refusal. Synchronous: schedules are parsed where a job is built.

package/loop.mjs

@@ -180,16 +180,16 @@ export class Orchestrator {
   tick(at = this.clock()) {
     this.queue = this.queue.then(() => this.adoptOutsideJobs()).catch((error) => this.log('warn', `cron/jobs.json not read back: ${error.message}`));
     return this.dispatch(events.tick(at, cronInactivitySeconds(), cronMaxParallel())).then(
-      (result) => { this.tickerHeartbeat(true); this.declareLocalAgents();return result; },
+      (result) => { this.tickerHeartbeat(true); void this.declareLocalAgents().catch((error) => this.log('warn', `agent hand-off: ${error.message}`));return result; },
       (error) => { this.tickerHeartbeat(false); throw error; },
     );
   }
 
   /** The home's agent declarations and ends a launch could not hand to this machine's daemon (none was running) are
    * handed on. The daemon declares and ends them in Teams and binds their sessions; the gateway makes no Teams call. */
-  declareLocalAgents(){
+  async declareLocalAgents(){
     if(!existsSync(join(this.state.root,'agent-state.sqlite')))return;
-    try{for(const pending of handOffAgents(this.state.root))this.log('warn',`agent ${pending.agent}: ${pending.error}`);}
+    try{for(const pending of await handOffAgents(this.state.root))this.log('warn',`agent ${pending.agent}: ${pending.error}`);}
     catch(error){this.log('warn',`agent hand-off: ${error.message}`);}
   }
 
@@ -416,8 +416,8 @@ export class Orchestrator {
         if(!record)throw new Error('launch as an agent requires its retained profile intent');
         agent=record;
       }
-      agent??=localProfileAgent({root:this.state.root,org:scope.org,server:scope.server,profiles:this.state.profiles,profile:profileName,agent:agentName,declarations:this.state.agents});
-      if(!scope.offline)for(const pending of handOffAgents(this.state.root,{context}))this.log('warn',`agent ${pending.agent}: ${pending.error}`);
+      agent??=await localProfileAgent({root:this.state.root,org:scope.org,server:scope.server,profiles:this.state.profiles,profile:profileName,agent:agentName,declarations:this.state.agents});
+      if(!scope.offline)for(const pending of await handOffAgents(this.state.root,{context}))this.log('warn',`agent ${pending.agent}: ${pending.error}`);
       agent.intended.resolved.worker={...agent.intended.resolved.worker,...worker,cwd};
       main=new_fork||!agent.identity.main_session;
       if(resume_runtime_id&&!new_fork){
@@ -507,8 +507,8 @@ export class Orchestrator {
     if(this.runtimes.has(leaseId(profileName,keyString)))throw new Error('fork requires an unoccupied target conversation');
     if(!(await this.descriptorFor(locator.harness))?.runtime?.capabilities?.resume_session)throw new Error('this harness cannot resume a materialized fork');
     const context=process.env.SUPERCODE_CONTEXT,scope=agentScope(context),session=`${locator.harness}:${locator.session_id}`;
-    const child=localForkAgent({root:this.state.root,org:scope.org,server:scope.server,profiles:this.state.profiles,parent,session,name,key});
-    if(!scope.offline)for(const pending of handOffAgents(this.state.root,{context}))this.log('warn',`agent ${pending.agent}: ${pending.error}`);
+    const child=await localForkAgent({root:this.state.root,org:scope.org,server:scope.server,profiles:this.state.profiles,parent,session,name,key});
+    if(!scope.offline)for(const pending of await handOffAgents(this.state.root,{context}))this.log('warn',`agent ${pending.agent}: ${pending.error}`);
     const runKey=`fork:${key}`,prior=agentRunForKey(this.state.root,scope.org,child.identity.id,runKey);
     let target;
     if(prior) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.73",
+  "version": "0.5.75",
   "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.24",
+    "@volter/teams": "0.2.25",
     "@volter/ztrack": "^2.4.23",
     "yaml": "^2.9.0"
   },

package/bin/machine-fleet.mjs

@@ -1,38 +0,0 @@
-#!/usr/bin/env node
-// One fleet reading for a synchronous board process: each named machine's panes and the harness session under each live
-// pane, every machine read at once through its own door, each bounded by its own deadline. Prints one row per machine:
-// { machine, panes, activities } when its door answered, { machine, error, code } when it did not.
-import { openMachine } from '@volter/teams/machine-door';
-import { StreamRpc, harnessTransport } from '@volter/teams/client';
-import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
-let input = ''; for await (const chunk of process.stdin) input += chunk;
-const { machines, deadlineMs } = JSON.parse(input);
-const within = (promise, ms) => Promise.race([promise, new Promise((_, reject) => setTimeout(() => reject(Object.assign(new Error(`no answer within ${ms} ms`), { code: 'timeout' })), ms))]);
-async function read({ name, at }) {
-  let channel;
-  try {
-    channel = await openMachine({ machine: at });
-    const node = new StreamRpc(await channel.open('node'));
-    const panes = await node.call('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 node.call('harness.v1.machine.describe', {}).catch(() => null);
-    const keyed = await node.call('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) {
-      const client = new SupercodeHarnessClient({ transport: harnessTransport(channel) });
-      try { await client.start?.(); activities = (await client.request('harness.v1.sessions.activity_under', { pids: live.map((pane) => pane.pid) }))?.activities ?? []; }
-      catch (error) { sessionsUnread = String(error?.message ?? error).slice(0, 200); }
-      finally { await client.close?.().catch(() => {}); }
-    }
-    return { machine: name, panes, activities, capabilities, sessionsUnread };
-  } finally { channel?.close(); }
-}
-const rows = await Promise.all(machines.map((machine) => within(read(machine), deadlineMs)
-  .catch((error) => ({ machine: machine.name, error: String(error?.message ?? error).slice(0, 300), code: error?.code ?? 'unavailable' }))));
-process.stdout.write(`${JSON.stringify(rows)}\n`);
-process.exit(0);

package/bin/runtime-door.mjs

@@ -1,23 +0,0 @@
-#!/usr/bin/env node
-// A synchronous board process delegates one request to the public daemon door.
-// This helper owns neither credentials nor machine state; the SDK opens the admitted channel.
-import { openMachine } from '@volter/teams/machine-door';
-import { StreamRpc, harnessTransport } from '@volter/teams/client';
-import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
-let input = ''; for await (const chunk of process.stdin) input += chunk;
-let channel;
-try {
-  const { machine, method, params = {} } = JSON.parse(input);
-  if (!method.startsWith('harness.v1.')) throw new Error('the runtime door accepts harness.v1 methods');
-  channel = await openMachine({machine});
-  let result;
-  if (method.startsWith('harness.v1.sessions.')) {
-    // A session's records are the harness's own service, spoken by its SDK over the machine's harness stream.
-    const client = new SupercodeHarnessClient({ transport: harnessTransport(channel) });
-    try { await client.start?.(); result = await client.request(method, params); } finally { await client.close?.(); }
-  } else result = await new StreamRpc(await channel.open('node')).call(method,params);
-  process.stdout.write(JSON.stringify(result)+'\n');
-} catch (error) {
-  process.stderr.write(JSON.stringify({code:error.code??'unavailable',message:error.message})+'\n');
-  process.exitCode = 1;
-} finally { channel?.close(); }