@volter/supercode-orchestrator 0.5.219 → 0.5.221

package/board/dispatch.mjs

@@ -52,11 +52,11 @@ import { basename, dirname, join } from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { view, boardCopyOf, boardKey, boardPath, cardHandleOf, readableIdOf, briefPath, claimer, claimHolds, copyRefusal, event, json, listBoards, logsDir, newClaim, now, NOTICE_RUN_IDS, openBoard, openBoardSnapshot, pendingLaunches, sessionBound, setActor, storageFault, tx } from './store.mjs';
-import { doors, fire, loadWorkflow, resumeOf, runSpec, runWorkingSeconds, requestSessionClose, retireSupersededRuns, refreshCardInputs, refreshRelationAnswers, transitionsFor, scopeOf, statusOf, projectStatus, storedStatus, templateValue, workflowFor } from './workflow.mjs';
+import { doors, fire, loadWorkflow, resumeOf, runSpec, runWorkingSeconds, requestSessionClose, retireSupersededRuns, refreshCardInputs, refreshRelationAnswers, unrelayedStateAnswers, transitionsFor, scopeOf, statusOf, projectStatus, storedStatus, templateValue, workflowFor } from './workflow.mjs';
 import { checkWorkspace, assertWorkspaceOwner, notePresence, resolveWorkspace } from './workspace.mjs';
 import { capacity, dispatched, executionHost, harnessDefaults, holdings } from './capacity.mjs';
 import { evaluate, holds, render } from './expr.mjs';
-import { identifyNotice, numbered } from './notices.mjs';
+import { cardNumber, identifyNotice, numbered } from './notices.mjs';
 import { noticeReceiptsInTurns, noticeKey, requireNoticeBasis, noticeWriterBasis } from './notice-receipts.mjs';
 import { pendingRequestMail } from './request-mail.mjs';
 import {
@@ -1939,8 +1939,10 @@ export async function sessionEffect(board, e) {
   if (e.kind === 'send_to_actor') {
     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;
-    if (view(board, db => detachedSession(db, session))) return true;
-    const address = addressOf(session);
+    // an effect may name its recipient (a state request's requester, settleStateRequestAnswers); otherwise it is the
+    // run's actor. A recipient in a person's custody is filed nothing, as the run's own detached session is not.
+    if (view(board, db => e.address ? Boolean(personCustody(db, e.address)) || (addressOf(session) === e.address && detachedSession(db, session)) : detachedSession(db, session))) return true;
+    const address = e.address ?? addressOf(session);
     if (!address) throw new Error('actor session identity unavailable');
     // filed in the actor's mailbox, which delivers it
     const card = view(board, (db) => getTask(db, e.id));
@@ -3171,6 +3173,55 @@ function ensureSubscriptions(board, entry) {
   });
 }
 
+/**
+ * Whether the session at `address` is known to have ended: one of card `taskId`'s runs carried it, and no run (of any
+ * card) carrying it is unended or keeps it open after its run (retain_after_run, not since closed or handed on). One
+ * session carries many runs and a kept session goes on asking after its run ends, so an ended run alone says nothing.
+ */
+function sessionEnded(db, taskId, address) {
+  const runs = db.prepare("SELECT task_id, ended_at, metadata FROM task_runs WHERE json_extract(metadata, '$.supercode.address') = ? OR json_extract(metadata, '$.supercode.session_id') = ?")
+    .all(address, address.split(':').at(-1)).map((r) => ({ ...r, session: json(r.metadata, {})?.supercode })).filter((r) => addressOf(r.session) === address);
+  return runs.some((r) => r.task_id === taskId) && !runs.some((r) => r.ended_at == null
+    || (r.session.retain_after_run && !r.session.close_requested && !r.session.closed_at && !r.session.close_transferred_to));
+}
+
+/**
+ * The manager's answer to a state request (its reply to the board's "State requests" question), granted or denied,
+ * reaches the session that asked and stays on the card. A denial changes no card state, so before this the answer was
+ * read from the mailbox only into the stall guard (card.state_request) and the requester went on reading its request
+ * as pending. Each answer is recorded once as a `state_request_answered` event (the request, the answering message,
+ * who sent it, its text and the state act the card took after the request, if any) and told to the requester, or the
+ * card's live session (its current, unended run) when the request names none or the requester's session is known to
+ * have ended (sessionEnded: run N asked and died, and the board relaunched the card as N+1), as an actor notice
+ * through the effect queue (sessionEffect files it in that mailbox under a fixed key), queued in the transaction that
+ * records it so neither lands without the other. A closed card with no live session gets the record alone. An answer
+ * older than the workflow's notice_max_age_seconds, or whose age is unknown (no limit set, no reply time read), is
+ * recorded, not mailed.
+ */
+function settleStateRequestAnswers(board, entry, report) {
+  const maxAge = Number(entry?.params?.notice_max_age_seconds) || null;
+  const self = boardAddress(board.label);
+  tx(board, (db) => {
+    for (const a of unrelayedStateAnswers(db, entry?.params?.notice_max_age_seconds)) {
+      const outcome = a.act ? `the card took ${a.act} after the request` : 'the card\'s state is unchanged';
+      const id = event(db, a.task_id, 'state_request_answered', { request_event: a.request_event, state: a.state, requester: a.requester,
+        question: a.question, answer: a.answer, answered_by: a.answered_by, act: a.act, outcome, decision: String(a.text ?? '').slice(0, 4000) }, a.run_id);
+      (report.state_answers ??= []).push([a.task_id, a.answer]);
+      if (!maxAge || !Number(a.answered_at_ms) || Date.now() - Number(a.answered_at_ms) > maxAge * 1000) continue;
+      const run = a.run_id ? db.prepare('SELECT ended_at, metadata FROM task_runs WHERE id = ?').get(a.run_id) : null;
+      const live = run && run.ended_at == null ? addressOf(json(run.metadata, {})?.supercode) : null;
+      const requester = String(a.requester ?? '').startsWith('sc:') ? a.requester : null;
+      const to = requester && (requester === live || !sessionEnded(db, a.task_id, requester)) ? requester : live;
+      if (!to || to === self || to === a.answered_by) continue;
+      const text = `${a.task_id}: your request-state ${a.state ?? ''} (${a.question}) was answered by ${a.answered_by ?? 'the manager'} in ${a.answer}; ${outcome}.\n${String(a.text ?? '').trim()}\nRead the card: supercode workflow show ${a.task_id} --root ${board.root}`;
+      const effect = { kind: 'send_to_actor', id: a.task_id, runId: a.run_id, address: to, sourceEvent: id, verb: 'state_request_answered',
+        messageKey: `board-state-answer-${a.task_id}-${id}`,
+        text: identifyNotice({ id, kind: 'state_request_answered', run_id: a.run_id, created_at: now() }, numbered(boardKey(board.root, board.slug), cardNumber(db, a.task_id), text)) };
+      db.prepare('INSERT INTO supercode_effects (effect) VALUES (?)').run(JSON.stringify(effect));
+    }
+  });
+}
+
 /** The event kinds an audience hears (the workflow's notify). */
 const heardBy = (entry, audience) => Object.keys(entry.workflow.notify?.[audience] ?? {});
 
@@ -4040,7 +4091,7 @@ export async function tick({ root, lanes, settings, only = null, slugs = null, d
       const phase = (name) => { const t = Date.now(); report.ms[name] = t - mark; mark = t; };
 
       await readMailbox(board, boardAddress(board.label), report); phase('mailbox');
-      await refreshRelationAnswers(board); phase('answers');
+      await refreshRelationAnswers(board); settleStateRequestAnswers(board, entry, report); phase('answers');
       const effects = [];
       await completeAdoptions(board, fleet, settings, report, lanes); await reconnectContinuedSessions(board, fleet, entry, report); await reconcileLaunches(board, fleet, report, entry, effects, settings, lanes); await recordBounces(board, fleet, entry, report); await supervise(board, fleet, settings, report, entry, effects); queueEffects(board, effects.splice(0)); await closeRequested(board, report, { ttl: settings.ttl, fleet }); phase('supervise');
       report.unsettled = [];

package/board/listing.mjs

@@ -103,11 +103,16 @@ export async function listCardsInTurns(db, options = {}) {
     const cards = await readCardsInTurns(db, options, revision);
     if (cards !== null) return cards;
   }
-  throw Object.assign(new Error('board changed during both listing reads; run list again'), { code: 'board_listing_changed' });
+  // Both reads saw a write land between their turns: a burst, as the round a generation switch wakes makes. The third
+  // reads every batch in one turn, so a write by this process (the board's one writer) cannot land inside it; it still
+  // validates, so a writer outside this process is still refused. It holds the loop for one listing, and only here.
+  const cards = await readCardsInTurns(db, options, measured('read revision', () => listRevision(db)), { inTurns: false });
+  if (cards !== null) return cards;
+  throw Object.assign(new Error('board changed during all three listing reads; run list again'), { code: 'board_listing_changed' });
 }
 
 async function readCardsInTurns(db, { detailed = false, status = null, assignee = null, machine = null, includeArchived = false, includeSubtasks = false,
-  tenant = null, session = null, workflowTemplateId = null, stepKey = null, tags = [], nativeHolds = false }, revision) {
+  tenant = null, session = null, workflowTemplateId = null, stepKey = null, tags = [], nativeHolds = false }, revision, { inTurns = true } = {}) {
   const out = [];
   const page = prepared(db, listPageSql(detailed, tags.length, { nativeHolds })), candidates = prepared(db, LIST_CANDIDATES_SQL);
   const ceiling = measured('last candidate', () => prepared(db, "SELECT COALESCE(MAX(id), '') AS cursor FROM tasks").get().cursor);
@@ -135,7 +140,7 @@ async function readCardsInTurns(db, { detailed = false, status = null, assignee
       }
     });
     cursor = range.last;
-    await nextTurn();
+    if (inTurns) await nextTurn();
   }
   if (!measured('validate revision', () => sameRevision(revision, listRevision(db)))) return null;
   // The candidate index uses id order; restore the original task row order for tied sorts.

package/board/workflow.mjs

@@ -342,11 +342,15 @@ export async function refreshRelationAnswers(board) {
   for (const row of board.db.prepare("SELECT e.payload FROM task_events e JOIN (SELECT task_id, MAX(id) id FROM task_events WHERE kind IN ('blocked','unblocked') GROUP BY task_id) last ON e.id=last.id JOIN tasks t ON t.id=e.task_id WHERE e.kind='blocked' AND t.status='blocked'").all()) {
     const id = json(row.payload, {})?.waiting_on; if (id) ids.add(id);
   }
-  // State requests stay live while the card runs, independently of a blocker.
-  // Read their exact question ids through the same mailbox receipt door.
-  for (const row of board.db.prepare("SELECT id FROM tasks WHERE current_run_id IS NOT NULL AND status NOT IN ('done','cancelled','archived')").all()) {
-    const request = stateRequestOf(board.db, row.id);
+  // State requests stay live while the card runs, independently of a blocker, and a card's latest request is read
+  // until its answer has been relayed (granted or denied, settleStateRequestAnswers), on a closed card too while the
+  // request is recent (stateRequestCards). Read the ids the questions were mailed under through the same mailbox
+  // receipt door.
+  for (const row of stateRequestCards(board.db, entry?.params?.notice_max_age_seconds)) {
+    const request = row.current_run_id != null && !row.closed ? stateRequestOf(board.db, row.id) : null;
     if (request?.message_id) ids.add(request.message_id);
+    const latest = latestStateRequest(board.db, row.id);
+    if (latest?.question && !latest.relayed) ids.add(latest.question);
   }
   const list = [...ids];
   if (!list.length) return;
@@ -356,8 +360,9 @@ export async function refreshRelationAnswers(board) {
     if (!Array.isArray(rows)) throw new Error('the mail door returned no message list');
     for (const id of list) {
       const row = rows.find((item) => item?.id === id);
+      const reply = row?.replies?.[0] ?? null;
       mailboxAnswers.set(id, row?.found === true
-        ? { answer: row.replies?.[0]?.id ?? null, askedOf: row.session ?? null }
+        ? { answer: reply?.id ?? null, askedOf: row.session ?? null, by: reply?.from ?? null, at_ms: reply?.created_at_ms ?? null, text: reply?.body ?? null }
         : { error: `the mailbox did not find question ${id}; its answer is unknown` });
     }
   } catch (error) { for (const id of list) mailboxAnswers.set(id, { error: `the answer to ${id} could not be read: ${String(error.message).slice(0, 200)}` }); }
@@ -370,16 +375,66 @@ function answerTo(id) {
 
 // A manager's state act settles the request; a mailbox reply answers it without
 // changing the card. Unknown mailbox reads never assert an unanswered question.
-function stateRequestOf(db, id) {
+const STATE_ACTS = "('paused','resumed','blocked','unblocked','completed','cancelled','review_pass','reopened')";
+// A card's latest state request and the id its question was mailed under. Requests asked within one batch window are
+// mailed as one message under the batch's first id (request-mail.mjs), so a later member's own id was never sent and
+// its answer lands under the batch's: board_message_sent records which (`request_id` the member's, `message_id` the
+// sent one). `relayed` once its answer is on the card (state_request_answered).
+function latestStateRequest(db, id) {
   const row = one(db, "SELECT id,payload,created_at FROM task_events WHERE task_id=? AND kind='state_requested' ORDER BY id DESC LIMIT 1", id);
-  if (!row || one(db, "SELECT 1 FROM task_events WHERE task_id=? AND id>? AND kind IN ('paused','resumed','blocked','unblocked','completed','cancelled','review_pass','reopened') LIMIT 1", id, row.id)) return null;
+  if (!row) return null;
   const payload = json(row.payload, {}) ?? {};
-  const question = payload.message_id ?? json(one(db, "SELECT payload FROM task_events WHERE task_id=? AND id<? AND kind='board_message' AND json_extract(payload,'$.batch') IS NOT NULL ORDER BY id DESC LIMIT 1", id, row.id)?.payload, {})?.message_id;
+  const asked = payload.message_id ?? json(one(db, "SELECT payload FROM task_events WHERE task_id=? AND id<? AND kind='board_message' AND json_extract(payload,'$.batch') IS NOT NULL ORDER BY id DESC LIMIT 1", id, row.id)?.payload, {})?.message_id;
+  const sent = asked ? one(db, "SELECT json_extract(payload,'$.message_id') AS id FROM task_events WHERE task_id=? AND id>? AND kind='board_message_sent' AND json_extract(payload,'$.request_id')=? ORDER BY id DESC LIMIT 1", id, row.id, asked)?.id : null;
+  const relayed = Boolean(one(db, "SELECT 1 FROM task_events WHERE task_id=? AND id>? AND kind='state_request_answered' AND json_extract(payload,'$.request_event')=? LIMIT 1", id, row.id, row.id));
+  return { row, payload, question: sent ?? asked ?? null, relayed };
+}
+function stateRequestOf(db, id) {
+  const latest = latestStateRequest(db, id);
+  if (!latest || one(db, `SELECT 1 FROM task_events WHERE task_id=? AND id>? AND kind IN ${STATE_ACTS} LIMIT 1`, id, latest.row.id)) return null;
+  const { row, payload, question } = latest;
   const receipt = question ? mailboxAnswers.get(question) : null;
-  return { id: row.id, created_at: row.created_at, state: payload.state, reason: payload.reason, message_id: question ?? null,
+  return { id: row.id, created_at: row.created_at, state: payload.state, reason: payload.reason, message_id: question,
     answer_known: Boolean(receipt && !receipt.error), answer: receipt?.answer ?? null, error: receipt?.error ?? null };
 }
 
+/**
+ * The cards whose latest state request is still read: every open card, and a closed card (done, cancelled or archived:
+ * the manager may close it before a round reads the reply) whose latest request is younger than the workflow's
+ * notice_max_age_seconds, or STATE_ANSWER_WINDOW_SECONDS when it sets none, until its answer is recorded. A closed
+ * card's request older than that is no longer read, so an unanswered one is not read every round forever.
+ */
+const STATE_ANSWER_WINDOW_SECONDS = 3600;
+function stateRequestCards(db, maxAgeSeconds) {
+  const since = now() - (Number(maxAgeSeconds) || STATE_ANSWER_WINDOW_SECONDS);
+  return all(db, `SELECT t.id, t.current_run_id, t.status IN ('done','cancelled','archived') AS closed FROM tasks t
+    LEFT JOIN (SELECT task_id, MAX(id) id, MAX(created_at) at FROM task_events WHERE kind = 'state_requested' GROUP BY task_id) r ON r.task_id = t.id
+    WHERE t.status NOT IN ('done','cancelled','archived')
+      OR (r.id IS NOT NULL AND r.at >= ?
+        AND NOT EXISTS (SELECT 1 FROM task_events a WHERE a.task_id = t.id AND a.id > r.id AND a.kind = 'state_request_answered' AND json_extract(a.payload,'$.request_event') = r.id))`, since);
+}
+
+/**
+ * Each card's latest state request (stateRequestCards) whose answer the mailbox has read and the card does not yet
+ * record: the manager's reply to the board's question, granted or denied, with who sent it, its text and the state
+ * act (if any) the card took after the request. The dispatcher records it and tells the requester (dispatch.mjs
+ * settleStateRequestAnswers); a denial changes no card state, so this reply is the only trace it leaves.
+ */
+export function unrelayedStateAnswers(db, maxAgeSeconds) {
+  const out = [];
+  for (const task of stateRequestCards(db, maxAgeSeconds)) {
+    const latest = latestStateRequest(db, task.id);
+    if (!latest?.question || latest.relayed) continue;
+    const receipt = mailboxAnswers.get(latest.question);
+    if (!receipt?.answer) continue;
+    const act = one(db, `SELECT kind FROM task_events WHERE task_id=? AND id>? AND kind IN ${STATE_ACTS} ORDER BY id LIMIT 1`, task.id, latest.row.id)?.kind ?? null;
+    out.push({ task_id: task.id, run_id: task.current_run_id ?? null, request_event: latest.row.id,
+      state: latest.payload.state ?? null, requester: latest.payload.requester ?? null, question: latest.question,
+      answer: receipt.answer, answered_by: receipt.by ?? null, answered_at_ms: receipt.at_ms ?? null, text: receipt.text ?? null, act });
+  }
+  return out;
+}
+
 const OPEN_OUTCOME = /^(\s*[-*] )\[ \] (.+)$/;
 const TICKED_OUTCOME = /^\s*[-*] \[[xX]\] .+$/;
 /** Card bodies use Markdown headings and standalone labels such as `Acceptance:` and `Tasks:`. Every label ends

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.219",
+  "version": "0.5.221",
   "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": {
@@ -36,7 +36,7 @@
     "check-types": "node scripts/generate-types.mjs --check"
   },
   "dependencies": {
-    "@volter/supercode-teams": "^0.3.373",
+    "@volter/supercode-teams": "^0.3.377",
     "@volter/supercode-terminal": "^0.3.12",
     "@volter/supercode-harness-sdk": "^0.3.106",
     "@volter/teams": "0.2.104",