@volter/supercode-orchestrator 0.4.110 → 0.4.112

package/board/dispatch.mjs

@@ -15,6 +15,7 @@
 // Every side effect follows a committed transition: a card is claimed before its session is launched, and a
 // subscriber's cursor moves only after its notice was delivered, so two dispatchers over one board never both
 // launch and a crash between the two steps is answered by the next tick.
+import { createRequire } from 'node:module';
 import { spawn as spawnChild, spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { hostname, tmpdir } from 'node:os';
@@ -54,10 +55,22 @@ export function localMachine() {
 /** The supercode command the dispatcher drives. */
 export const supercodeBin = () => process.env.SUPERCODE_BIN || 'supercode';
 
+// Installed board workers use their sibling Teams package, not a CLI build's retained checkout.
+// An explicit operator override remains authoritative for source development.
+let teamsEntry;
+function commandEnv(as = null) {
+  if (teamsEntry === undefined) {
+    try { teamsEntry = createRequire(import.meta.url).resolve('@volter/supercode-teams/bin'); }
+    catch { teamsEntry = null; }
+  }
+  return { ...process.env, ...(!process.env.SUPERCODE_TEAMS_ENTRY && teamsEntry ? { SUPERCODE_TEAMS_ENTRY: teamsEntry } : {}),
+    ...(as ? { SUPERCODE_CALLER: as } : {}) };
+}
+
 function sc(args, { input = null, timeout = 120_000, as = null } = {}) {
   // a neutral directory: `supercode teams …` resolves its entry from a checkout at the cwd. `as`: the board this
   // command acts for, so a card's pane is started and closed by its board, whichever session ran the board's verb
-  const env = as ? { ...process.env, SUPERCODE_CALLER: as } : process.env;
+  const env = commandEnv(as);
   const r = spawnSync(supercodeBin(), args, { cwd: tmpdir(), input: input ?? undefined, encoding: 'utf8', timeout, env, maxBuffer: 512 * 1024 * 1024 });
   return { code: r.status, stdout: r.stdout ?? '', stderr: (r.stderr ?? '') + (r.error ? r.error.message : '') };
 }
@@ -166,6 +179,7 @@ export function boardSettings(params = {}) {
     ttl: claimTtl(params.claim_ttl_seconds),
     grace: pos(params.session_grace_seconds) ?? 120,
     interval: Math.max(Number(params.dispatch_interval_seconds) || 60, 1),
+    idleQuiet: pos(params.session_idle_quiet_seconds) ?? 600,
     logRotateBytes: pos(params.worker_log_rotate_bytes) ?? 2 * 1024 * 1024,
     logBackups: Number.isInteger(Number(params.worker_log_backup_count)) && Number(params.worker_log_backup_count) >= 0 ? Number(params.worker_log_backup_count) : 1,
     hooks: params.hooks && typeof params.hooks === 'object' ? params.hooks : {},
@@ -525,10 +539,11 @@ export function closeRequested(board, report, { taskId = null, caller = null } =
   for (const row of rows) {
     let session = json(board.db.prepare('SELECT metadata FROM task_runs WHERE id = ?').get(row.id)?.metadata, {})?.supercode;
     if (session?.launch_key && !session.pane && (row.ended_at || session.close_requested)) {
-      const receipt = launchReceipt(board, session);
+      let receipt = null, receiptError = null;
+      try { receipt = launchReceipt(board, session); } catch (error) { receiptError = error.message; }
       if (receipt?.pane) { bindLaunch(board, row, session, receipt.pane, session.session_id); session = { ...session, pane: receipt.pane }; }
       else {
-        const error = `close deferred: awaiting launch receipt ${session.launch_key}`;
+        const error = `close deferred: ${receiptError ?? `awaiting launch receipt ${session.launch_key}`}`;
         tx(board, (db) => {
           setRunSession(db, row.id, { close_error: error, close_requested: session.close_requested ?? now() });
           if (session.close_error !== error) event(db, row.task_id, 'session_close_failed', { error, retry: true }, row.id);
@@ -596,9 +611,9 @@ function observeIdle(board, fleet, settings, report, entry, effects) {
       // a supercode that reports no last message time gives no reading, and no reading gives no verdict
       const lastAt = Math.floor(Number(live?.last_message_at_ms) / 1000);
       if (!(lastAt > 0)) return;
-      if (now() - lastAt < settings.interval) return;
-      if (session.goal_nudged_at && now() - session.goal_nudged_at < settings.interval * 2) return;
-      const worked = Boolean(session.goal_nudged_at) && lastAt >= session.goal_nudged_at + settings.interval;
+      if (now() - lastAt < settings.idleQuiet) return;
+      if (session.goal_nudged_at && now() - session.goal_nudged_at < settings.idleQuiet) return;
+      const worked = Boolean(session.goal_nudged_at) && lastAt > session.goal_nudged_at;
       try {
         const where = whereOf(board, task);
         // the ask names what the session may do, as its run's prompt did
@@ -732,9 +747,13 @@ const getTaskNow = (board, id) => view(board, (db) => getTask(db, id));
 
 /** A transport error is not a negative launch receipt. The key remains owned by its run. */
 function launchReceipt(board, session) {
-  const r = sc(['teams', 'rpc', 'launches.get', JSON.stringify({ key: session.launch_key }), '--machine', session.machine],
+  const r = sc(['teams', 'launches', 'get', session.launch_key, '--machine', session.machine],
     { timeout: 30_000, as: boardAddress(board.label) });
-  return r.code === 0 ? lastJson(r.stdout) : null;
+  if (r.code !== 0) throw new Error(`launch receipt unavailable on ${session.machine}: install the matching Teams CLI and machine capability (teams launches get): ${(r.stderr || r.stdout).trim().slice(-300)}`);
+  if (r.stdout.trim() === 'null') return null;
+  const receipt = lastJson(r.stdout);
+  if (!receipt || receipt.key !== session.launch_key) throw new Error(`invalid launch receipt for ${session.launch_key} on ${session.machine}`);
+  return receipt;
 }
 
 function bindLaunch(board, row, session, pane, sid) {
@@ -758,6 +777,8 @@ function bindLaunch(board, row, session, pane, sid) {
 
 /** A fast worker can reach its first board door before open's reply. Bind only the daemon's keyed pane. */
 export function reconcileCallerLaunch(board, sid) {
+  if (view(board, (db) => db.prepare(`SELECT 1 FROM task_runs r JOIN tasks t ON t.current_run_id=r.id
+    WHERE json_extract(r.metadata, '$.supercode.session_id')=? AND COALESCE(json_extract(r.metadata, '$.supercode.launch_pending'),0)=0`).get(sid))) return;
   const rows = view(board, (db) => db.prepare(`SELECT r.id, r.task_id, r.metadata FROM task_runs r
     JOIN tasks t ON t.current_run_id=r.id WHERE r.ended_at IS NULL
     AND json_extract(r.metadata, '$.supercode.launch_pending') = 1`).all());
@@ -846,10 +867,12 @@ function launchPane(board, task, runId, lane, fleet, { input = null, slot = 'wor
     if (prev?.close_requested && !prev.closed_at) throw new Error(`the slot's session ${prev.session_id} asked to be closed and its pane ${prev.pane} could not be: ${report.undelivered.map((u) => u[2]).join('; ') || 'no reason given'}`);
   }
   const openOwned = (key, sid, mode, args) => {
+    launchReceipt(board, { machine, launch_key: key }); // Prove the exact receipt door before starting a process.
     tx(board, (db) => setRunSession(db, runId, { ...meta, surface: 'pane', machine, harness, slot,
       session_id: sid, mode, launch_key: key, launch_pending: true, launched_at: now() }));
     const result = sc(args, { timeout: 180_000, as: boardAddress(board.label) });
-    const facts = launchReceipt(board, { machine, launch_key: key });
+    let facts = null, receiptError = null;
+    try { facts = launchReceipt(board, { machine, launch_key: key }); } catch (error) { receiptError = error.message; }
     const pane = facts?.pane ?? lastJson(result.stdout)?.pane ?? null;
     // The daemon's keyed receipt is authoritative even when the stream carrying open's reply closed.
     if (pane) tx(board, (db) => {
@@ -863,7 +886,7 @@ function launchPane(board, task, runId, lane, fleet, { input = null, slot = 'wor
         launch_pending: false, launch_error: null, launched_at: now() };
     }
     const reason = facts?.live === false && pane ? `launch pane ${pane} ended` :
-      `launch ${key} is awaiting its machine receipt or session identity: ${(result.stderr || result.stdout).trim().slice(-300)}`;
+      `launch ${key} is awaiting its machine receipt or session identity: ${receiptError ?? (result.stderr || result.stdout).trim().slice(-300)}`;
     tx(board, (db) => {
       setRunSession(db, runId, { launch_pending: true, launch_error: reason });
       event(db, task.id, 'session_launch_pending', { key, pane, reason }, runId);
@@ -1101,7 +1124,7 @@ export function adoptSession(board, id, who, { workspace = null, ttl, assignee =
 
 // a notice sent within a transaction's caller that cannot await (the launcher): the same door, synchronously
 function deliverNow(board, to, body, key) {
-  const request = { op: 'send', from: boardAddress(board.label), from_name: `${board.label} board`, to, queue: false, id: key,
+  const request = { op: 'send', from: boardAddress(board.label), from_name: `${board.label} board`, to, queue: false, id: key, subject: String(body).split('\n')[0].slice(0, 160),
     body: `[Board notice from the ${board.label} board] ${body}\n\n(An automated notice from the board's dispatcher; replies to this address go nowhere.)` };
   const r = sc(['message', 'remote-deliver'], { input: JSON.stringify(request), timeout: 120_000 });
   const answer = lastJson(r.stdout);
@@ -1110,7 +1133,7 @@ function deliverNow(board, to, body, key) {
 
 async function send(from, label, to, body, key, { queue = false, ask = false } = {}) {
   const request = {
-    op: 'send', from, from_name: `${label} board`, to, queue, id: key,
+    op: 'send', from, from_name: `${label} board`, to, queue, id: key, subject: String(body).split('\n')[0].slice(0, 160),
     // a question the board waits on is answered by a reply; a notice is not
     body: ask ? `[A question from the ${label} board] ${body}` : `[Board notice from the ${label} board] ${body}\n\n(An automated notice from the board's dispatcher; replies to this address go nowhere.)`,
   };
@@ -1423,7 +1446,7 @@ export function boardLabel(root, slug) {
 /** `sc` without blocking the tick: notices to many sessions go out side by side. */
 function scAsync(args, { input = null, timeout = 120_000 } = {}) {
   return new Promise((done) => {
-    const child = spawnChild(supercodeBin(), args, { cwd: tmpdir(), env: process.env, stdio: ['pipe', 'pipe', 'pipe'] });
+    const child = spawnChild(supercodeBin(), args, { cwd: tmpdir(), env: commandEnv(), stdio: ['pipe', 'pipe', 'pipe'] });
     let stdout = '';
     let stderr = '';
     const timer = setTimeout(() => { stderr += ` timed out after ${timeout}ms`; child.kill('SIGKILL'); }, timeout);

package/board/workflow.mjs

@@ -344,7 +344,7 @@ export function fire(db, board, entry, id, name, { roles = [], payload = {}, ext
   // `sender`: the roles the event was sent with (a validator can ask who is asking)
   const scope = scopeOf(db, board, task, { params, event: payload, extra: { lanes: lanesIn(entry), ...extra, sender: roles } });
   const allowed = candidates.filter((t) => !t.by?.length || t.by.some((r) => roles.includes(r)));
-  if (!allowed.length) throw new Error(`${id} is ${from}; ${name.replace(/_/g, '-')} there is for ${[...new Set(candidates.flatMap((t) => t.by ?? []))].join(' or ')}`);
+  if (!allowed.length) throw new Error(`${id} is ${from}; ${name.replace(/_/g, '-')} there is for ${[...new Set(candidates.flatMap((t) => t.by ?? []))].join(' or ')}. ${candidates.map((t) => t.description).filter(Boolean).join(' ')}`);
   const taken = allowed.find((t) => holds(t.guard ?? null, scope));
   if (!taken) { const none = new Error(`${id} is ${from}; ${name.replace(/_/g, '-')} does not apply to it now`); none.noTransition = true; throw none; }
   for (const v of taken.validate ?? []) {
@@ -557,7 +557,8 @@ const ACTIONS = {
     if (!['paused', 'archived'].includes(name)) throw new Error(`unknown flag ${name}`);
     if (name === 'paused') {
       const was = json(one(ctx.db, 'SELECT paused FROM supercode_cards WHERE task_id = ?', ctx.id)?.paused, null);
-      if (!value && was && was.by !== actorOf() && !ctx.scope.sender?.includes('owner') && !(ctx.scope.sender?.includes('hermes') && ctx.scope.event?.hermes)) throw new Error('only the pauser or owner may resume this card');
+      const clearBy = ctx.entry.workflow.flags?.paused?.clear_by ?? ['pauser', 'owner'];
+      if (!value && was && !clearBy.some((role) => role === 'pauser' ? was.by === actorOf() : ctx.scope.sender?.includes(role))) throw new Error(`only ${clearBy.join(' or ')} may resume this card; ask the manager with your reason`);
       if (value && !String(reason ?? '').trim()) throw new Error('pause needs a reason');
       cardField(ctx, name, value ? JSON.stringify({ by: actorOf(), reason }) : null);
     } else cardField(ctx, name, Number(Boolean(value)));

package/board/ztrack.mjs

@@ -136,6 +136,7 @@ class ZtrackBoard {
           if(source.name==='supercode_cards')return JSON.stringify(canonical(source.row,new Set(['since','after_fired','next_run_at'])))!==JSON.stringify(canonical(this.rows.cachedCards[JSON.parse(source.key)[0]],new Set(['since','after_fired','next_run_at'])));
           return false;
         });
+        this.publishedFingerprints = {};
         const documents = this.seed || documentChanges.length ? this.documents(this.seed ? null : documentChanges) : {open:this.text, archived:this.archiveText};
         const files = [{ path: this.path, before: hash(this.text), base: this.text, text: documents.open }, { path: this.archive, before: hash(this.archiveText), base: this.archiveText, text: documents.archived }];
         const snapshot = this.snapshot(documents);
@@ -330,18 +331,7 @@ class ZtrackBoard {
       if (this.originals.has(id)) throw new Error(`duplicate board card ${id}`);
       this.originals.set(id, card); this.fileIds.set(id, card.id);
       this.loadCard(id, card);
-      for (const task of card.acceptanceCriteria) {
-        const tid = task.metadata?.id ?? this.saved.taskIds?.[`${id}:${task.id}`] ?? `t_${randomBytes(4).toString('hex')}`;
-        this.taskKeys.set(tid, `${id}:${task.id}`);
-        const body = task.metadata?.body ?? '';
-        const taskCard = { ...task.metadata?.card, id: tid, title: `${task.id} ${task.text}`, body,
-          status: task.status === 'passed' ? (task.metadata?.status === 'cancelled' ? 'cancelled' : 'done') : (['done','cancelled'].includes(task.metadata?.status) ? 'todo' : task.metadata?.status ?? 'todo'),
-          metadata: task.metadata?.properties ?? {}, assignee: task.metadata?.assignee ?? card.assignee,
-          machine: task.metadata?.machine ?? card.machine, acceptanceCriteria: [],
-          acceptance: task.lines ?? [], relations: (task.blockedBy ?? []).map((b) => ({ type: 'blocked-by', issueId: b.ac ? `${nativeId(b.issue)}:${b.ac}` : nativeId(b.issue) })) };
-        if (task.waitingOn) taskCard.relations.push({ type: 'blocked-by', issueId: task.waitingOn });
-        this.loadCard(tid, taskCard, id);
-      }
+      for (const [tid, taskCard] of this.taskCards(id, card)) this.loadCard(tid, taskCard, id);
     }
     // Keep the last readable projection only for the affected malformed cards.
     // Their raw document spans remain untouched and their verbs refuse with this reason.
@@ -368,24 +358,48 @@ class ZtrackBoard {
     }
     if (observe) this.documentEvents();
   }
+  taskCards(id, card) {
+    return card.acceptanceCriteria.map((task) => {
+      const tid = task.metadata?.id ?? this.saved.taskIds?.[`${id}:${task.id}`] ?? `t_${randomBytes(4).toString('hex')}`;
+      this.taskKeys.set(tid, `${id}:${task.id}`);
+      const taskCard = { ...task.metadata?.card, id: tid, title: `${task.id} ${task.text}`, body: task.metadata?.body ?? '',
+        status: task.status === 'passed' ? (task.metadata?.status === 'cancelled' ? 'cancelled' : 'done') : (['done','cancelled'].includes(task.metadata?.status) ? 'todo' : task.metadata?.status ?? 'todo'),
+        metadata: task.metadata?.properties ?? {}, assignee: task.metadata?.assignee ?? card.assignee,
+        machine: task.metadata?.machine ?? card.machine, acceptanceCriteria: [], acceptance: task.lines ?? [],
+        relations: (task.blockedBy ?? []).map((b) => ({ type: 'blocked-by', issueId: b.ac ? `${nativeId(b.issue)}:${b.ac}` : nativeId(b.issue) })) };
+      if (task.waitingOn) taskCard.relations.push({ type: 'blocked-by', issueId: task.waitingOn });
+      return [tid, taskCard];
+    });
+  }
   loadCard(id, card, parent = null) {
+    const rows = this.cardRows(id, card, parent);
+    this.insert('tasks', rows.task); this.insert('supercode_cards', rows.state);
+  }
+  cardRows(id, card, parent = null) {
     const meta = card.metadata ?? {};
     const stored = this.preset.serializeKanbanCard({ ...card, acceptanceCriteria: [], relations: [], metadata: undefined, paused: undefined, every: undefined, workspace: undefined, branch: undefined, machine: undefined, priority: undefined });
     const workspace = /^(scratch|dir|worktree)(?::(.*))?$/.exec(card.workspace ?? 'scratch');
-    this.insert('tasks', { ...meta, ...this.saved.runtime?.[id], id, title: card.title, body: stored.body,
+    const task = { ...meta, ...this.saved.runtime?.[id], id, title: card.title, body: stored.body,
       status: card.status, assignee: card.assignee ?? null, created_at: meta.created_at ?? now(), priority: card.priority ?? 0,
-      workspace_kind: workspace?.[1] ?? 'scratch', workspace_path: workspace?.[1] === 'scratch' ? (this.saved.runtime?.[id]?.workspace_path ?? meta.workspace_path ?? null) : workspace?.[2] ?? null, branch_name: card.branch ?? null });
-    this.insert('supercode_cards', { ...this.saved.clocks?.[id], task_id: id, stage: card.status, machine: card.machine ?? null, subtask_of: parent,
+      workspace_kind: workspace?.[1] ?? 'scratch', workspace_path: workspace?.[1] === 'scratch' ? (this.saved.runtime?.[id]?.workspace_path ?? meta.workspace_path ?? null) : workspace?.[2] ?? null, branch_name: card.branch ?? null };
+    const state = { ...this.saved.clocks?.[id], task_id: id, stage: card.status, machine: card.machine ?? null, subtask_of: parent,
       blocked_by: JSON.stringify((card.relations ?? []).map((r) => ({ ...(meta.blocked_by ?? []).find((b) => b.id === nativeId(r.issueId)), id: nativeId(r.issueId), kind: /^[ma]-/.test(r.issueId) ? 'message' : 'card' }))),
-      paused: card.paused ? JSON.stringify(card.paused) : null, archived: meta.archived ? 1 : 0, every: card.every ?? null });
+      paused: card.paused ? JSON.stringify(card.paused) : null, archived: meta.archived ? 1 : 0, every: card.every ?? null };
+    return { task, state };
+  }
+  fingerprint(t, c) {
+    const status = c.stage ?? t.status;
+    return { hash: hash(JSON.stringify([t.title, t.body, status, t.assignee, c.machine, c.blocked_by, c.paused, c.every])), title: hash(t.title), body: hash(t.body ?? ''), status, assignee: t.assignee, machine: c.machine, parent: c.subtask_of };
   }
   fingerprints() {
     return Object.fromEntries(this.mem.prepare('SELECT * FROM tasks').all().map((t) => {
       const c = this.mem.prepare('SELECT * FROM supercode_cards WHERE task_id = ?').get(t.id) ?? {};
-      return [t.id, { hash: hash(JSON.stringify([t.title, t.body, c.stage, t.assignee, c.machine, c.blocked_by, c.paused, c.every])), title: hash(t.title), body: hash(t.body ?? ''), status: c.stage, assignee: t.assignee, machine: c.machine, parent: c.subtask_of }];
+      return [t.id, this.fingerprint(t, c)];
     }));
   }
   documentEvents() {
+    // A published native document is already represented by its authored events.
+    if (this.saved.documentHashes?.open === hash(this.text) && this.saved.documentHashes?.archived === hash(this.archiveText)) return;
     const previous = this.saved.fingerprints ?? {};
     const current = this.fingerprints();
     if (!Object.keys(previous).length) return;
@@ -412,6 +426,7 @@ class ZtrackBoard {
     return 'document-editor';
   }
   documents(changes=null) {
+    this.publishedFingerprints = {};
     const allRows = this.mem.prepare('SELECT * FROM tasks ORDER BY created_at, id').all();
     const states = new Map(this.mem.prepare('SELECT * FROM supercode_cards').all().map((c) => [c.task_id, c]));
     const affected=changes?new Set(changes.map(({source})=>{const id=JSON.parse(source.key)[0];return states.get(id)?.subtask_of??this.rows.cachedCards[id]?.subtask_of??id;})):null;
@@ -456,6 +471,15 @@ class ZtrackBoard {
     for (const [id, card] of cards) {
       const serialized = this.preset.serializeKanbanCard(card);
       const record = { id: card.id, title: card.title, status: card.status, ...(card.assignee ? { assignee: card.assignee } : {}), body: serialized.body };
+      // Fingerprint the codec's persisted projection, not the pre-serialization input.
+      // The codec normalizes bodies (including their trailing newline) and subtask titles.
+      const persisted = this.preset.KanbanRootSchema.parse(this.preset.parseKanban([record])).issues[0];
+      const rows = this.cardRows(id, persisted);
+      this.publishedFingerprints[id] = this.fingerprint(rows.task, rows.state);
+      for (const [tid, taskCard] of this.taskCards(id, persisted)) {
+        const rows = this.cardRows(tid, taskCard, id);
+        this.publishedFingerprints[tid] = this.fingerprint(rows.task, rows.state);
+      }
       (states.get(id)?.archived || ['done', 'cancelled'].includes(card.status) ? archived : open).push(record);
     }
     const original=this.documentRecords;
@@ -463,7 +487,11 @@ class ZtrackBoard {
     return { open: !changedPath(this.path)?this.text:this.codec.renderBoardDocument(this.text, open, this.path, [...(this.preserve.get(this.path)??[])]), archived: !changedPath(this.archive)?this.archiveText:this.codec.renderBoardDocument(this.archiveText, archived, this.archive, [...(this.preserve.get(this.archive)??[])]) };
   }
   snapshot(documents) {
-    return { documentHashes:{open:hash(documents.open),archived:hash(documents.archived)}, errors:[...this.errors], fingerprints: this.fingerprints(), taskIds: Object.fromEntries([...this.taskKeys].map(([id, key]) => [key, id])) };
+    const fingerprints = this.fingerprints();
+    if (this.saved.documentHashes?.open === hash(this.text) && this.saved.documentHashes?.archived === hash(this.archiveText)) {
+      for (const id of Object.keys(fingerprints)) if (this.saved.fingerprints?.[id]) fingerprints[id] = this.saved.fingerprints[id];
+    }
+    return { documentHashes:{open:hash(documents.open),archived:hash(documents.archived)}, errors:[...this.errors], fingerprints: { ...fingerprints, ...this.publishedFingerprints }, taskIds: Object.fromEntries([...this.taskKeys].map(([id, key]) => [key, id])) };
   }
 
   lift() {

package/package.json

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