@volter/supercode-orchestrator 0.4.128 → 0.4.130

package/board/cli.mjs

@@ -302,6 +302,7 @@ export async function runWorkflow(argv) {
       }), true);
       let answer = { id: created.id, existing: created.existing };
       if (args.adopt) {
+        withBoard(b => { if (!rolesFor(b.db, created.id, sid, workflowFor(root).params).includes('manager')) throw new Error('Only the manager adopts an existing session.'); });
         const adopted = withBoard(b => adoptSession(b, created.id, args.adopt, { ttl: settings.ttl }));
         answer = { ...answer, started: true, session: adopted.address, mode: adopted.mode };
       } else if (!args['no-start'] && !created.existing && !args['subtask-of']) {
@@ -827,6 +828,7 @@ export async function runWorkflow(argv) {
     }
     case 'adopt': {
       need(2, 'a card id and a session');
+      withBoard(b => { if (!rolesFor(b.db, id, sid, workflowFor(root).params).includes('manager')) throw new Error('Only the manager adopts an existing session.'); });
       const { settings } = await laneState(root);
       const got = withBoard((b) => adoptSession(b, id, rest[1], { workspace: args.workspace ?? null, ttl: settings.ttl, assignee: args.assignee ?? null, role: args.role ?? null }));
       say(args, `${id} is worked by ${got.address} (pane ${got.pane ?? '?'} in ${got.workspace ?? 'its card\'s directory'})`, { ok: true, ...got });

package/board/dispatch.mjs

@@ -450,16 +450,23 @@ function startCards(board, fleet, lanes, settings, report, entry, effects, { onl
     return { target, runSpec: spec, profile, lane: profile ? lanes[profile] ?? null : null };
   };
   const candidates = [];
+  const waiting = (task, why) => {
+    report.queued.push([task.id, why]);
+    if (!dry) tx(board, db => noteGuard(db, task.id, why));
+  };
   for (const task of everyCard) {
     if (only && task.id !== only) continue;
     const state = scopeFor(task).card;
-    if (state.dispatch_hold) continue;
-    if (workflow.run && (task.subtask_of || state.paused || state.archived || state.blocked_by.length || task.current_run_id || (state.every && state.next_run_at > now()))) continue;
-    if (!startable.has(statusOf(board.db, task))) continue;
+    if (task.subtask_of || state.archived || task.current_run_id || ['done', 'cancelled'].includes(state.status)) continue;
+    if (state.dispatch_hold) { waiting(task, 'dispatch held: an explicit start or verified adoption must release it'); continue; }
+    if (workflow.run && state.paused) { waiting(task, `paused: ${state.paused.reason ?? 'manager pause'}`); continue; }
+    if (workflow.run && state.blocked_by.length) { waiting(task, `blocked by ${state.blocked_by.map(b => b.id).join(', ')}`); continue; }
+    if (workflow.run && state.every && state.next_run_at > now()) { waiting(task, `next scheduled run at ${state.next_run_at}`); continue; }
+    if (!startable.has(state.status)) { waiting(task, `no ${d.start} transition from ${state.status}`); continue; }
     const plan = planOf(task, scopeFor(task));
-    if (!plan) continue;
+    if (!plan) { waiting(task, `start guard refused: ${transitionsFor(workflow, state.status, d.start).map(t => t.guard ?? 'sender role').join(' | ')}`); continue; }
     const scope = scopeFor(task, { lane: plan.lane ?? {}, run: { surface: plan.lane?.surface ?? null, local: plan.lane?.surface !== 'pane' || normalMachine(task.machine ?? '') === localMachine() } });
-    if (!holds(d.eligible ?? null, scope)) continue;
+    if (!holds(d.eligible ?? null, scope)) { waiting(task, `dispatch eligibility refused (memory ${pressure}, local starts ${tickState.local_started}): ${d.eligible}`); continue; }
     candidates.push({ task, plan, scope });
   }
   const keyOf = (c) => (d.order ?? []).map((o) => { const desc = o.startsWith('-'); const v = evaluate(desc ? o.slice(1) : o, c.scope); return { v, desc }; });
@@ -770,16 +777,17 @@ export async function sessionNotice(board, e) {
     return true;
   }
   e = { ...e, address: e.address ?? addressOf(prior) };
-  let error = null;
+  let error = null, receipt = null;
   try {
     if (!e.address) throw new Error('lifecycle notice awaits the owned launch session identity');
-    await send(boardAddress(board.label), board.label, e.address, e.text, `board-run-notice-${e.id}-${e.durableId}`, { queue: true }); }
+    receipt = await send(boardAddress(board.label), board.label, e.address, e.text, `board-run-notice-${e.id}-${e.durableId}`);
+    if (!receipt.delivered) error = receipt.reason ?? 'notice queued; native transcript confirmation pending'; }
   catch (failure) { error = String(failure.message).slice(-500); }
   tx(board, (db) => {
     const session = json(db.prepare('SELECT metadata FROM task_runs WHERE id = ?').get(e.runId)?.metadata, {})?.supercode;
     if (session) setRunSession(db, e.runId, { ...session,
       ...(error ? { lifecycle_notice_error: error } : { lifecycle_notice_error: null, ...(session.lifecycle_notice_pending === e.durableId ? { lifecycle_notice_pending: null } : {}) }) });
-    if (!error || session?.lifecycle_notice_error !== error) event(db, e.id, error ? 'session_notice_failed' : 'session_notice_delivered', { address: e.address, verb: e.verb, source_event: e.sourceEvent, notice: e.durableId, ...(error ? { error, retry: true } : {}) }, e.runId);
+    if (!error || session?.lifecycle_notice_error !== error) event(db, e.id, error ? (receipt?.queued ? 'session_notice_queued' : 'session_notice_failed') : 'session_notice_delivered', { address: e.address, verb: e.verb, source_event: e.sourceEvent, notice: e.durableId, receipt, ...(error ? { error, retry: true } : {}) }, e.runId);
   });
   return !error;
 }
@@ -787,12 +795,21 @@ export async function sessionNotice(board, e) {
 /** A session effect a committed move asked for: a message to the card's current actor, or closing a slot's pane. */
 export async function sessionEffect(board, e) {
   if (e.kind === 'send_to_actor') {
-    const run = view(board, (db) => currentRun(db, e.id));
-    const session = run?.metadata?.supercode;
+    const row = view(board, db => e.runId ? db.prepare('SELECT metadata FROM task_runs WHERE id=?').get(e.runId) : null);
+    const session = json(row?.metadata, {})?.supercode;
     const address = addressOf(session);
-    if (!address) return;
-    await send(boardAddress(board.label), board.label, address, e.text, `board-actor-${e.id}-${now()}`);
-    return;
+    let receipt;
+    try {
+      if (!address) throw new Error('actor session identity unavailable');
+      receipt = await send(boardAddress(board.label), board.label, address, e.text, `board-actor-${e.id}-${e.durableId}`);
+    } catch (error) { receipt = { delivered: false, reason: error.message }; }
+    const kind = receipt.delivered ? 'actor_notice_delivered' : receipt.queued ? 'actor_notice_queued' : 'actor_notice_failed';
+    tx(board, db => {
+      const previous = db.prepare("SELECT kind,payload FROM task_events WHERE task_id=? AND kind IN ('actor_notice_delivered','actor_notice_queued','actor_notice_failed') ORDER BY id DESC LIMIT 1").get(e.id);
+      const payload = { notice: e.durableId, address, receipt };
+      if (previous?.kind !== kind || JSON.stringify(json(previous?.payload, {})?.receipt) !== JSON.stringify(receipt)) event(db, e.id, kind, payload, e.runId);
+    });
+    return receipt.delivered;
   }
   if (e.kind === 'close_session' || e.kind === 'run_ended') {
     tx(board, (db) => requestSessionClose(db, e.id, e.kind === 'run_ended' ? { runId: e.runId } : { slot: e.slot, through: e.runId }));
@@ -1212,6 +1229,12 @@ function resolveLocalWorkspace(board, task) {
  * its card. `who` is an address, a session id, or a `name@machine` the fleet lists.
  */
 export function adoptSession(board, id, who, { workspace = null, ttl, assignee = null, role = null } = {}) {
+  // Hold before discovery or any other process I/O: a failed attachment remains
+  // visible and cannot race a dispatcher into launching a replacement worker.
+  tx(board, db => {
+    if (!getTask(db, id)) throw new Error(`no card ${id}`);
+    event(db, id, 'dispatch_held', { session: who, reason: 'adoption requested' });
+  });
   const fleet = observeFleet();
   if (!fleet.ok) throw new Error(`supercode could not read the fleet: ${fleet.error}`);
   const found = fleet.sessions.find((s) => s.address === who || s.address.endsWith(`:${who}`) || s.name === who);
@@ -1293,6 +1316,7 @@ async function send(from, label, to, body, key, { queue = false, ask = false } =
   const r = await scAsync(['message', 'remote-deliver'], { input: JSON.stringify(request), timeout: 180_000 });
   const answer = lastJson(r.stdout) ?? {};
   if (answer.code !== 0) throw new Error((answer.text || r.stderr || `no answer (exit ${r.code})`).trim().slice(-300));
+  return answer.receipt ?? { delivered: false, reason: 'mail door returned no delivery receipt' };
 }
 
 /**

package/board/engine.mjs

@@ -170,6 +170,7 @@ export function createCard(board, spec) {
   ws.path = declared.path;
   spec = { ...spec, branch: declared.branch ?? spec.branch };
   const initial = spec.initialStatus ?? null;
+  if (initial === 'running' && (spec.noStart || spec.adopt)) throw new Error('A held or awaiting-adoption card cannot be created initially running.');
   if (initial && !['blocked', 'running'].includes(initial)) throw new Error('initial status is blocked or running');
   if (spec.provider && !spec.model) throw new Error('a provider needs a model');
   return tx(board, (db) => {
@@ -396,7 +397,7 @@ export async function runEffects(board, effects = [], { retryNotices = false } =
     else if (e.kind === 'close_session' || e.kind === 'send_to_actor' || e.kind === 'run_ended') {
       if (e.kind === 'run_ended' && e.outcome === 'reclaimed') stopWorker(board, e.runId);
       const { sessionEffect } = await import('./dispatch.mjs');
-      await sessionEffect(board, e);
+      if (await sessionEffect(board, e) === false) continue;
     }
     if (e.durableId) tx(board, (db) => db.prepare('DELETE FROM supercode_effects WHERE id = ?').run(e.durableId));
   }

package/board/wake.mjs

@@ -20,7 +20,7 @@ export function signalBoardWrite(root, actor) {
 /** One coalescing queue shared by standalone serve and the hosted dispatcher. */
 export function watchBoard({ root, binary, env, log = () => {} }) {
   const watchers = new Map();
-  let pending = null, waiter = null, closed = false, child = null, retry = null, lastError = null;
+  let pending = null, waiter = null, closed = false, child = null, retry = null, lastError = null, catalogue = null;
   const wake = (source, at = Date.now()) => {
     if (closed) return;
     if (!pending) pending = { at, sources: new Set() };
@@ -83,7 +83,7 @@ export function watchBoard({ root, binary, env, log = () => {} }) {
     if (closed) return;
     let buffer = '', error = '';
     const command = env.SUPERCODE_TEAMS_ENTRY ? process.execPath : binary;
-    const args = [...(env.SUPERCODE_TEAMS_ENTRY ? [env.SUPERCODE_TEAMS_ENTRY] : []), 'sessions', 'list', '--watch', '--json'];
+    const args = [...(env.SUPERCODE_TEAMS_ENTRY ? [env.SUPERCODE_TEAMS_ENTRY] : []), 'sessions', 'list', '--watch', '--json', '--limit', '200'];
     child = spawn(command, args, { cwd: tmpdir(), env, stdio: ['ignore', 'pipe', 'pipe'] });
     child.stdout.setEncoding('utf8').on('data', chunk => {
       buffer += chunk;
@@ -94,7 +94,24 @@ export function watchBoard({ root, binary, env, log = () => {} }) {
         try {
           const event = JSON.parse(line);
           lastError = null;
-          if (!['heartbeat', 'ping', 'keepalive'].includes(event.type)) wake('session-catalogue');
+          if (['heartbeat', 'ping', 'keepalive'].includes(event.type)) continue;
+          if (event.type === 'catalog_reset' && Array.isArray(event.data?.items)) {
+            // Transcript revisions and sort order are not scheduling events.
+            // The safety sweep reads quiet timestamps; wake for session identity,
+            // availability and available delivery/control doors changing now.
+            const next = JSON.stringify(event.data.items.map(item => ({
+              id:item.id, harness:item.harness, machines:[...(item.machine_ids ?? [])].sort(),
+              bindings:(item.bindings ?? []).map(binding => ({ id:binding.id, machine:binding.machine_id,
+                incarnation:binding.incarnation_id, runtime:binding.native_runtime_id, session:binding.native_session_id,
+                harness:binding.harness, state:binding.state, capabilities:[...(binding.native_capabilities ?? [])].sort(),
+              })).sort((a,b)=>String(a.id).localeCompare(String(b.id))), actions:item.actions,
+              presence:item.activity?.presence, turn:item.activity?.turn,
+              status:item.live_status, delivery:item.delivery,
+            })).sort((a,b)=>String(a.id).localeCompare(String(b.id))));
+            if (next === catalogue) continue;
+            catalogue = next;
+          }
+          wake('session-catalogue');
         } catch { /* CLI diagnostics are not events */ }
       }
     });

package/board/workflow.mjs

@@ -359,7 +359,15 @@ export function fire(db, board, entry, id, name, { roles = [], payload = {}, ext
   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 ')}. ${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; }
+  if (!taken) {
+    const state = scope.card;
+    const reasons = [state.paused && `paused: ${state.paused.reason ?? 'manager pause'}`,
+      state.blocked_by.length && `blocked by ${state.blocked_by.map(b => b.id).join(', ')}`,
+      state.dispatch_hold && 'dispatch held', state.current_run_id && `current run ${state.current_run_id}`,
+      state.archived && 'archived'].filter(Boolean);
+    const none = new Error(`${id} is ${from}; ${name.replace(/_/g, '-')} cannot proceed: ${reasons.join('; ') || `guard ${allowed.map(t => t.guard).join(' | ')}`}`);
+    none.noTransition = true; throw none;
+  }
   for (const v of taken.validate ?? []) {
     if (!holds(v.expr, scope)) { const refusal = new Error(v.message); refusal.refusal = v.message; throw refusal; }
   }
@@ -763,7 +771,11 @@ const ACTIONS = {
     record(ctx.db, ctx.id, 'board_message', { to: String(to), text: `${String(text ?? '')}\n\nAnswer with reply_to ${id}.`, message_id: id }, null);
     ctx.effects.push({ kind: 'board_message', id: ctx.id });
   },
-  send_to_actor(ctx, text) { ctx.effects.push({ kind: 'send_to_actor', id: ctx.id, text }); },
+  send_to_actor(ctx, text) {
+    const effect = { kind: 'send_to_actor', id: ctx.id, runId: ctx.runId, text };
+    const inserted = run(ctx.db, 'INSERT INTO supercode_effects (effect) VALUES (?)', JSON.stringify(effect));
+    ctx.effects.push({ ...effect, durableId: Number(inserted.lastInsertRowid) });
+  },
 };
 
 /** Binding a newer run transfers ownership; stale run references cannot veto its later stop. */

package/package.json

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