@volter/supercode-orchestrator 0.5.147 → 0.5.149

package/board/dispatch.mjs

@@ -187,9 +187,36 @@ const paneInRecord = (fleet, session) => session?.surface !== 'headless' && sess
 const sessionAlive = (fleet, session) => fleet.native?.has(addressOf(session)) ? fleet.native.get(addressOf(session)).alive : paneInRecord(fleet, session) ?? unpublishedAlive(session);
 /** A subscriber's address as the session it names, for sessionAlive (its machine, harness and native id). */
 const sessionAt = (address) => { const m = /^sc:([^:]+):([^:]+):(.+)$/.exec(String(address)); return m && HARNESSES[m[2]] ? { address, machine: normalMachine(m[1]), harness: m[2], session_id: m[3] } : null; };
-/** A subscriber's liveness, read first (readBefore): true, false, or null when it could not be read (unknown, never dead). */
+/** An agent's address (`sc:<machine>:agent:<name>`) as its machine and name, or null. */
+const agentAt = (address) => { const m = /^sc:([^:\s]+):agent:([^:\s]+)$/.exec(String(address)); return m ? { machine: normalMachine(m[1]), name: m[2] } : null; };
+const agentMains = new Map();
+/**
+ * An agent's main session, where mail to its address goes (ADR 0008), asked of its machine's daemon, which keeps the
+ * agent's record (one reading serves READING_MS): its address, false when that machine declares no such agent, or null
+ * when the daemon did not answer.
+ */
+async function agentMain(address) {
+  const held = agentMains.get(address);
+  if (held && Date.now() - held.at <= READING_MS) return held.main;
+  const { machine, name } = agentAt(address);
+  const local = machine === localMachine();
+  const r = await doorOn(machine, 'harness.v1.agent.show', { name, ...(local ? { claim: { pid: process.pid, ppid: process.ppid, session: null, named: null, owner: null } } : {}) }, { timeout: 5_000 });
+  const answer = r.code === 0 ? lastJson(r.stdout) : null;
+  const main = answer?.agents?.[0]?.main_session;
+  const read = { at: Date.now(), main: typeof main === 'string' && main ? main : answer && Number.isInteger(answer.code) && answer.code !== 0 ? false : null };
+  agentMains.set(address, read);
+  return read.main;
+}
+/**
+ * A subscriber's liveness, read first (readBefore): true, false, or null when it could not be read (unknown, never dead).
+ * An agent's address is as live as its main session.
+ */
 async function subscriberAlive(fleet, address) {
   if (fleet.alive.has(address)) return true;
+  if (agentAt(address)) {
+    const main = await agentMain(address);
+    return main && sessionAt(main) ? subscriberAlive(fleet, main) : main === null ? null : false;
+  }
   const session = sessionAt(address);
   if (!session) return false;
   await readBefore(fleet, session);
@@ -1083,47 +1110,91 @@ export async function startCard(board, id, { roles = ['manager'], lanes, setting
 
 /** Reconcile durable close intent and ended runs, including old unverified closed_at records.
  * Reads and process I/O stay outside the writer. An active successor owns its pane until it ends. */
-/** Why the close of an ended run's live session waits, or null when nothing would be cut. Read last, just before the
- *  kill and outside any write: a pane's by the harness session under its process (whatever session it is: an id the run
- *  never learned, a harness its record does not name), a session in no pane by its own id. Only a session read idle, or
- *  stopped, or no harness session in the pane at all, is closed; working, waiting on input, a turn the harness does not
- *  publish (unknown) and a reading that fails all wait a round. The card's move never does. */
+/** Why the close of an ended run's live session waits (`why`), or null when nothing would be cut. Read last, just
+ *  before the kill and outside any write: a pane's by the harness session under its process (whatever session it is: an
+ *  id the run never learned, a harness its record does not name), a session in no pane by its own id. A session read
+ *  idle, or stopped, or no harness session in the pane at all, is closed. Only a turn read in progress (working, waiting
+ *  on input) holds the close for as long as it is read. A harness pane whose session is not found under its process is
+ *  read by the run's own session id, as a session in no pane is; with no row there it waits, as a reading that fails
+ *  does. A turn its harness does not publish (unknown) is no turn read: its close waits on the session's own record
+ *  instead (`unread`: since when, the record's last write then, and when it was last read), and goes ahead once the
+ *  board has watched `quiet` seconds with nothing written to it. Rounds further apart than `gap` are no watch: the
+ *  count starts again. The card's move never waits. */
 // The programs a harness pane runs in its foreground: Claude Code's, Codex's, and node (the daemon's Codex pane host,
 // a harness installed through npm). A pane running one of these runs a harness session, read or not.
 const HARNESS_COMMANDS = new Set(['claude', 'claude.exe', 'codex', 'codex.exe', 'node']);
 /** A board launch never bound to a session (no session id read for it) whose launch window has passed. */
 export const unboundLaunch = (session, launchWindow, at = now()) => Boolean(session?.launch_key && !session.session_id && launchWindow
   && Number(session.launched_at) > 0 && at - Number(session.launched_at) >= launchWindow);
-async function turnAtClose(session, pane = null, { launchWindow = null } = {}) {
+/** The fleet turns of a session read in a turn (`needs_input`: a turn stopped on a permission or a question). */
+const TURN_IN_PROGRESS = new Set(['working', 'needs_input']);
+/** The watch on a session whose turn is not published: it began (`since`) at the first such reading, at the reading
+ *  that found its record written again (`mark`: its last write and when its harness says its state began, in ms), or
+ *  at the first reading after more than `gap` seconds unread (`seen`: the last reading). */
+function unreadWatch(held, mark, gap, at = now()) {
+  const kept = held && Number(held.mark) === mark && Number(held.since) <= at && at - Number(held.seen) <= gap;
+  return { since: kept ? Number(held.since) : at, mark, seen: at };
+}
+async function turnAtClose(session, pane = null, { launchWindow = null, quiet = null, gap = 0 } = {}) {
   const machine = session.machine ?? localMachine();
-  let activity;
+  const recordOf = (rows, id, harness) => rows.find((row) => row.locator?.session_id === id && row.locator?.harness === harness);
+  let activity, rows = null;
   if (pane?.pid) {
     const r = await doorOn(machine, 'harness.v1.sessions.activity_under', { pids: [pane.pid] }, { timeout: NATIVE_DISCOVERY_MS });
     const page = r.code === 0 ? lastJson(r.stdout) : null;
-    if (!Array.isArray(page?.activities)) return `the session in pane ${session.pane} could not be read just now (${(r.stderr || r.stdout).trim().slice(-160)})`;
+    if (!Array.isArray(page?.activities)) return { why: `the session in pane ${session.pane} could not be read just now (${(r.stderr || r.stdout).trim().slice(-160)})` };
     activity = page.activities.find((item) => item.pid === pane.pid)?.activity ?? null;
     // No session read under the pane is no absence (a registry it could not read, another config home, a failed process
-    // read): the pane's own foreground program says whether a harness runs there. Only a pane running none is closed.
+    // read, a process walk cut short): the pane's own foreground program says whether a harness runs there. A pane
+    // running none is closed; one running a harness is read by the session id the run holds.
     if (!activity) {
       // A pane the board launched whose session no reading ever found (the fleet's never bound it, and none runs under
       // its process now) past the launch window holds a harness that never started a session: nothing is cut by its
       // close. Waiting on it kept t_7ec85b6b's Codex pane on aarons-mac-mini, stuck before its first turn, open for 15 h.
       if (unboundLaunch(session, launchWindow)) return null;
       const command = String(pane.command ?? '').split(/[\\/]/).pop().toLowerCase();
-      return command && !HARNESS_COMMANDS.has(command) ? null : `pane ${session.pane} runs ${command || 'a program it does not name'}, whose session could not be read`;
+      if (command && !HARNESS_COMMANDS.has(command)) return null;
+      const unfound = `pane ${session.pane} runs ${command || 'a program it does not name'}, whose session could not be read`;
+      if (!session.session_id) return { why: unfound };
+      try { rows = (await discoverNative(machine, session.harness ?? 'claude-code', session.session_id)).sessions; }
+      catch (error) { return { why: `${unfound} (${String(error.message).slice(0, 160)})` }; }
+      activity = recordOf(rows, session.session_id, session.harness ?? 'claude-code')?.activity ?? null;
+      // a row that shows no live owner beside a pane that runs a harness places nothing: another session may run there
+      if (activity?.presence !== 'running') return { why: unfound };
     }
   } else if (pane) {
-    return `pane ${session.pane} names no process to read`;
+    return { why: `pane ${session.pane} names no process to read` };
   } else {
-    if (!session.session_id) return 'its session is not known yet';
-    try { activity = nativeReading((await discoverNative(machine, session.harness ?? 'claude-code', session.session_id)).sessions, session).row?.activity ?? null; }
-    catch (error) { return `its session could not be read just now (${String(error.message).slice(0, 160)})`; }
-    if (!activity) return `its session ${addressOf(session)} is not in its machine's discovery`;
+    if (!session.session_id) return { why: 'its session is not known yet' };
+    try { rows = (await discoverNative(machine, session.harness ?? 'claude-code', session.session_id)).sessions; }
+    catch (error) { return { why: `its session could not be read just now (${String(error.message).slice(0, 160)})` }; }
+    activity = nativeReading(rows, session).row?.activity ?? null;
+    if (!activity) return { why: `its session ${addressOf(session)} is not in its machine's discovery` };
   }
   if (activity.presence && activity.presence !== 'running') return null;
   if (activity.turn === 'idle') return null;
   const who = activity.session_id ? `sc:${normalMachine(machine)}:${activity.harness ?? session.harness}:${activity.session_id}` : addressOf(session);
-  return `its session ${who} is in a turn (${activity.turn ?? 'unknown'}); it closes once the turn ends`;
+  const inTurn = (turn) => ({ why: `its session ${who} is in a turn (${turn}); it closes once the turn ends`, unread: null });
+  if (TURN_IN_PROGRESS.has(activity.turn)) return inTurn(activity.turn);
+  // No turn published: the session's own record says whether anything goes on in it. One whose record does not answer,
+  // or shows neither a write nor when its state began, has nothing to count from and waits.
+  const unknown = `its session ${who} publishes no turn (${activity.turn ?? 'unknown'})`;
+  const sessionId = activity.session_id ?? session.session_id, harness = activity.harness ?? session.harness ?? 'claude-code';
+  if (!sessionId || !quiet) return { why: unknown };
+  if (!rows) try { rows = (await discoverNative(machine, harness, sessionId)).sessions; }
+    catch (error) { return { why: `${unknown}, and its record could not be read just now (${String(error.message).slice(0, 160)})` }; }
+  const record = recordOf(rows, sessionId, harness);
+  if (TURN_IN_PROGRESS.has(record?.activity?.turn)) return inTurn(record.activity.turn);
+  const mark = Math.max(Number(record?.updated_at_ms) || 0, Number(activity.evidence?.native_state_since_ms) || 0);
+  if (!mark) return { why: `${unknown}, and its record shows no write to count from` };
+  const unread = unreadWatch(session.close_unread, mark, gap);
+  if (unread.seen - unread.since >= quiet) return null;
+  return { why: `${unknown}; it closes once it is read idle, or after ${quiet}s watched with nothing written to its record`, unread };
+}
+/** Hold the close of an ended run's session for what `turnAtClose` read, with the watch that reading leaves on the run. */
+async function holdForTurn(session, pane, options) {
+  const held = await turnAtClose(session, pane, options);
+  if (held) throw Object.assign(new Error(`close deferred: ${held.why}`), 'unread' in held ? { closeUnread: held.unread } : {});
 }
 
 /** The closes this process is making now, by run: each one's outcome, for a pass that meets it under way. */
@@ -1230,7 +1301,7 @@ export async function closeRequested(board, report, { taskId = null, caller = nu
     }
     let settle;
     closesUnderway.set(flight, new Promise((resolve) => { settle = resolve; }));
-    let error = null, closed = false;
+    let error = null, closed = false, unread;
     try {
     const claimed = tx(board, (db) => {
       const current = json(db.prepare('SELECT metadata FROM task_runs WHERE id = ?').get(row.id)?.metadata, {})?.supercode;
@@ -1250,7 +1321,7 @@ export async function closeRequested(board, report, { taskId = null, caller = nu
         if (reading.alive) {
           const protectedNow = active.some(r => addressOf(json(r.metadata, {})?.supercode) === addressOf(session));
           if (protectedNow) throw new Error('close deferred: native session is owned by an unended run');
-          if (row.ended_at) { const inTurn = await turnAtClose(session); if (inTurn) throw new Error(`close deferred: ${inTurn}`); }
+          if (row.ended_at) { const { idleQuiet: quiet, interval } = boardSettings(workflowFor(board.root).params); await holdForTurn(session, null, { quiet, gap: Math.max(3 * interval, quiet / 2) }); }
           await stopSession(board, session);
         }
       } else if (!finalFailure) {
@@ -1267,7 +1338,7 @@ export async function closeRequested(board, report, { taskId = null, caller = nu
         if (protectedNow) throw new Error(`close deferred: pane ${session.pane} is owned by an unended run`);
         // An ended run's session is closed only between its turns, read last, after the claim and the pane list (a pane
         // already gone is settled above with no reading; t_f34710bc's coder was cut mid-proof at 15:01:13Z, 2026-10-04).
-        if (row.ended_at) { const inTurn = await turnAtClose(session, observed.live.get(session.pane), { launchWindow: boardSettings(workflowFor(board.root).params).launchWindow }); if (inTurn) throw new Error(`close deferred: ${inTurn}`); }
+        if (row.ended_at) { const { launchWindow, idleQuiet: quiet, interval } = boardSettings(workflowFor(board.root).params); await holdForTurn(session, observed.live.get(session.pane), { launchWindow, quiet, gap: Math.max(3 * interval, quiet / 2) }); }
         await stopSession(board, session); observed.live.delete(session.pane);
       }
       }
@@ -1276,6 +1347,8 @@ export async function closeRequested(board, report, { taskId = null, caller = nu
       // the prefix is decided on the whole message, before it is cut to size
       const message = String(e.message), deferred = Boolean(e.launchDeferred) || /^close deferred: /.test(message);
       error = `${deferred ? 'close deferred: ' : ''}${message.replace(/^close deferred: /, '').slice(-480)}`;
+      // the watch a turn reading left (or ended: a turn read in progress); an attempt that took none keeps the last
+      if ('closeUnread' in e) unread = e.closeUnread;
     }
     tx(board, (db) => {
       const current = json(db.prepare('SELECT metadata FROM task_runs WHERE id = ?').get(row.id)?.metadata, {})?.supercode;
@@ -1285,14 +1358,14 @@ export async function closeRequested(board, report, { taskId = null, caller = nu
       if (error && current.close_confirmed_at) return;
       if (error) {
         const final = !/^close deferred/.test(error);
-        setRunSession(db, row.id, { ...current, close_attempted_at: at, close_attempts: Number(current.close_attempts ?? 0) + 1, close_error: error, ...(final ? { close_failed_at: at } : {}) });
+        setRunSession(db, row.id, { ...current, close_attempted_at: at, close_attempts: Number(current.close_attempts ?? 0) + 1, close_error: error, ...(final ? { close_failed_at: at } : {}), ...(unread !== undefined ? { close_unread: unread } : {}) });
         // Retain every attempt's latest fact, but avoid an unbounded thread of identical failures.
         if (current.close_error !== error) event(db, row.task_id, 'session_close_failed', { session_id: session.session_id, pane: session.pane, error, retry: !final }, row.id);
         if (final && current.close_error !== error) event(db, row.task_id, 'run_incident', { observation: 'close_failed', run: row.id, reason: `the board could not close ${addressOf(session)} and will not try again: ${error}`, session: session.session_id, machine: session.machine, pane: session.pane ?? null, evidence: { error } }, row.id);
       } else if (!current.close_confirmed_at) {
         // a close another closer already confirmed (a claim that expired under it) is said once, by that closer
         const { close_error: _error, ...rest } = current;
-        setRunSession(db, row.id, { ...rest, close_error: null, closed_at: at, close_confirmed_at: at });
+        setRunSession(db, row.id, { ...rest, close_error: null, close_unread: null, closed_at: at, close_confirmed_at: at });
         const address = addressOf(session);
         // The closed session stops hearing every card it heard as their worker: its own and each subtask (a launch
         // subscribes it to all of them), unless another unended run still works in it, read in this transaction.
@@ -2032,7 +2105,7 @@ async function launchPane(board, task, runId, lane, fleet, { input = null, slot
     if (next === 'refuse') throw new Error(`session ${prev.session_id} still has live pane ${prev.pane}; cannot resume or replace it`);
     if (next === 'keep') {
       // the session is kept; the heartbeat's count belongs to the run that ended, so the new run starts it again
-      const { missing_since: _m, goal_turns: _t, goal_nudged_at: _n, idle_since: _is, unknown_since: _us, unknown_notice: _un, work_progress: _wp, idle_observation: _io, idle_below_threshold: _ib, idle_eligible: _ie, close_requested: _q, closed_at: _c, close_confirmed_at: _cc, close_error: _ce, close_attempts: _ca, close_attempted_at: _ct, close_failed_at: _cf, close_claim: _cl, monitor_held: _mh, released: _rl, ...kept } = prev;
+      const { missing_since: _m, goal_turns: _t, goal_nudged_at: _n, idle_since: _is, unknown_since: _us, unknown_notice: _un, work_progress: _wp, idle_observation: _io, idle_below_threshold: _ib, idle_eligible: _ie, close_requested: _q, closed_at: _c, close_confirmed_at: _cc, close_error: _ce, close_attempts: _ca, close_attempted_at: _ct, close_failed_at: _cf, close_unread: _cu, close_claim: _cl, monitor_held: _mh, released: _rl, ...kept } = prev;
       session = { ...kept, mode: 'adopt', launched_at: now(), seen_at: now() };
       // a kept session is told what this run is for (its card came back to it, with what happened since), only while
       // this run is still the card's current one (its pane and native reads were awaited)
@@ -2704,8 +2777,9 @@ async function notify(board, fleet, report, entry) {
     // the card as the workflow names it (its status the workflow's: triaging, reviewing, stopped; `stored_as` kanban.db's)
     const task = view(board, (db) => { const t = getTask(db, sub.task_id); return t ? { ...t, status: statusOf(db, t), stored_as: t.status } : t; });
     // a worker whose run has ended is not woken by a notice (a second session would start working the card beside
-    // the one the next run gets): the notice is filed for its next turn
-    const working = role !== 'worker' || view(board, (db) => addressOf(currentRun(db, sub.task_id)?.metadata?.supercode) === sub.chat_id);
+    // the one the next run gets): the notice is filed for its next turn, and the next run's brief carries the card's
+    // thread. A subtask has no run of its own: its worker works in its arc's run.
+    const working = role !== 'worker' || view(board, (db) => addressOf(currentRun(db, task?.subtask_of ?? sub.task_id)?.metadata?.supercode) === sub.chat_id);
     // a Claude session always starts a turn when mail reaches it, so its mail is always delivered now
     const wake = String(sub.chat_id).includes(':claude-code:') || (working && !(!entry.workflow.run && sub.delivery_mode === 'notify'));
     const where = "WHERE task_id = ? AND platform = 'supercode' AND chat_id = ? AND thread_id = ?";

package/package.json

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