@volter/supercode-orchestrator 0.5.228 → 0.5.230

package/board/client.mjs

@@ -15,8 +15,10 @@ import { noteCommandError, noteStep } from '@volter/supercode-harness-sdk/slow-l
  * The run-on-the-machine verbs (BOARD_OPERATION_VERBS: the owner itself, its init, repair and housekeeping, and the
  * verbs that hold the call open) and help are acts of their own, run here.
  */
-export async function runWorkflow(argv) {
-  const args = parse(argv);
+export async function runWorkflow(argv, { serveBoardOwner } = {}) {
+  // The owner retains malformed or unsupported requests for its manager. The
+  // client reads only enough context to address that owner, preserving argv.
+  const args = parse(argv, { contextOnly: true });
   const [verb] = args._;
   // This home's REST ledger is a local diagnostic, not a card verb. It needs neither a running board owner nor
   // a workflow/identity/network read just to explain which callers already issued requests.
@@ -29,32 +31,65 @@ export async function runWorkflow(argv) {
     return 0;
   }
   const help = !verb || verb === 'help' || args.help;
+  const service = !help && ['serve', 'daemon'].includes(verb);
   const root = help ? null : homeOf(args);
   if (!help && verb === 'handover') return sendToOwner(root, argv, args);
-  if (!help && ['serve', 'daemon'].includes(verb)) {
+  // Planning reads the admitted owner's card view. A standalone planner has no incumbent-reader grant and must
+  // not open/migrate the backing just to explain eligibility (including a bounded pause or backlog).
+  if (!help && verb === 'dispatch' && args['dry-run']) return sendToOwner(root, argv, args);
+  if (service) {
     const { inBoardGeneration } = await import('./generation.mjs');
     if (inBoardGeneration) {
+      // A generation is its owner's service, never its starter's caller, whichever release's owner started it (ADR 0013,
+      // "A service carries no caller's identity"): what an older owner passed on is dropped here, so a handover to
+      // this code cleans the generation that dispatches.
+      (await import('@volter/supercode-teams/service-environment')).dropOwnCallerIdentity();
       process.send({ type: 'startup-step', step: 'loading the board dispatcher', budget_ms: 8000 });
-      return (await import('./cli.mjs')).serveBoardGeneration(root, args, argv);
+      return (await import('./cli.mjs')).serveBoardGeneration(root, argv);
     }
-    return (await import('./generation-owner.mjs')).serveBoardOwner(root, args);
   }
   if (help || BOARD_OPERATION_VERBS.has(verb)) {
-    // The board has one writer. An operation that writes the boards (exclusive, below) takes the home's lock itself
-    // and so is that writer, refusing while an owner holds it. The rest only read, or are the owner itself (serve), and
-    // run here as their own act.
-    const writes = !help && exclusive(verb, args);
+    // The board has one writer. Writing operations and initial service admission hold its lock; a service then
+    // releases the admission lease so its stable owner can acquire the lifetime lease. Other operations only read.
+    const writes = !help && (service || exclusive(verb, args));
+    // its own process reads and writes the boards on the incumbent's resting-state reader (local-admission.mjs), from
+    // before it takes the lock: taking it fences every board in a transaction (fence.mjs takeEpoch)
+    if (!help) await (await import('./local-admission.mjs')).admitLocalRestingReader(root);
     let lock = null;
     if (writes) {
-      try { lock = await takeHome(root); }
+      try { lock = await takeHome(root, service); }
       catch (error) {
         noteCommandError(error, { phase: 'board ownership' });
-        process.stderr.write(`supercode workflow: ${verb} writes the boards of ${root}, which have a running owner (${error.message}); stop \`supercode workflow serve\` to run it\n`);
-        return 1;
+        if (error?.code === 'EHELD') {
+          if (!service) return sendToOwner(root, argv, args);
+          try { parse(argv); }
+          catch { return sendToOwner(root, argv, args, { preserveArgv: true }); }
+        }
+        throw error;
       }
     }
-    const [{ runVerb }, { closeWorld }] = await Promise.all([import('./cli.mjs'), import('../orchestration.mjs')]);
-    try { return await runVerb(argv); } finally { lock?.release(); await closeWorld(); }
+    const [{ runVerb, admitBoardService }, { closeWorld }] = await Promise.all([import('./cli.mjs'), import('../orchestration.mjs')]);
+    let failure, failed = false, admission = null, code = null;
+    try {
+      if (!service) return await runVerb(help ? ['help'] : argv);
+      admission = await admitBoardService(argv);
+      if (!admission) return 0;
+      const firstReaderEpoch = lock.firstReaderEpoch;
+      await lock.release(); lock = null;
+      code = await serveBoardOwner(admission.root, admission.args, firstReaderEpoch);
+      return code;
+    }
+    catch (error) { failed = true; failure = error; throw error; }
+    finally {
+      const cleanup = await Promise.allSettled([Promise.resolve().then(() => lock?.release()), Promise.resolve().then(() => closeWorld())]);
+      const errors = cleanup.filter(result => result.status === 'rejected').map(result => result.reason);
+      if (errors.length) {
+        const error = new AggregateError([...(failed ? [failure] : []), ...errors], 'board operation cleanup failed', { cause: failed ? failure : errors[0] });
+        admission?.finish(error, 1);
+        throw error;
+      }
+      admission?.finish(failed ? failure : null, code);
+    }
   }
   return sendToOwner(root, argv, args);
 }
@@ -70,22 +105,30 @@ function exclusive(verb, args) {
 }
 
 /** Hold the home's lock and take a fencing epoch, as its owner does; rejects when an owner holds the lock. */
-async function takeHome(root) {
+async function takeHome(root, service) {
   mkdirSync(root, { recursive: true });
   const [{ holdLock }, { takeEpoch }, { listBoards, openBoard }] = await Promise.all([import('./lock-holder.mjs'), import('./fence.mjs'), import('./store.mjs')]);
   const lock = await holdLock(join(boardHome(root), 'board.lock'), { onLost: (error) => { process.stderr.write(`supercode workflow: ${error.message}; stopping\n`); process.exit(1); } });
-  takeEpoch(root, () => listBoards(root).map((slug) => openBoard(root, slug)));
-  return lock;
+  try {
+    const fresh = service && (await import('./resting-admission.mjs')).pristineHome(root);
+    const epoch = takeEpoch(root, () => listBoards(root).map((slug) => openBoard(root, slug)));
+    return { release: lock.release, firstReaderEpoch: fresh ? epoch : null };
+  } catch (error) {
+    try { await lock.release(); }
+    catch (cleanup) { throw new AggregateError([error, cleanup], 'board ownership startup and cleanup failed', { cause: error }); }
+    throw error;
+  }
 }
 
-async function sendToOwner(root, argv, args) {
+async function sendToOwner(root, argv, args, { preserveArgv = false } = {}) {
   const began = performance.now();
   const sid = processSession();
   noteStep('board caller session', performance.now() - began);
   const preparing = performance.now();
   const harness = sid ? (sid === process.env.CODEX_THREAD_ID ? 'codex' : 'claude-code') : null;
-  // a file named `-` is the caller's standard input, read here and sent with the verb
-  const stdin = [args.file, args['body-file']].includes('-') ? readFileSync(0, 'utf8') : null;
+  // Malformed service input travels verbatim for retention; its unsupported file options acquire no stdin.
+  // A file named `-` on an ordinary verb is the caller's standard input, read here and sent with the verb.
+  const stdin = !preserveArgv && [args.file, args['body-file']].includes('-') ? readFileSync(0, 'utf8') : null;
   // The caller's own selections travel with the verb, so the owner never answers it with its own: its board (the
   // board it names, else the one its environment names) and its Teams context (named, else the one selected here).
   const board = args.board ?? process.env.HERMES_KANBAN_BOARD ?? null;
@@ -94,7 +137,7 @@ async function sendToOwner(root, argv, args) {
   const asking = performance.now();
   let answer;
   try {
-    answer = await askBoardOwner(root, { argv: withoutHome(argv), board, caller: null, session: sid ? { id: sid, harness } : null, facts, cwd: process.cwd(), stdin });
+    answer = await askBoardOwner(root, { argv: preserveArgv ? argv : withoutHome(argv), board, caller: null, session: sid ? { id: sid, harness } : null, facts, cwd: process.cwd(), stdin });
   } finally { noteStep('board owner answer', performance.now() - asking); }
   // the owner took the verb and the call ended with no answer: its outcome is unknown, never a plain failure
   if (answer.unanswered === true) {

package/board/close-current.mjs

@@ -0,0 +1,36 @@
+import { claimer, json, now, view } from './store.mjs';
+import { detachedCard, detachedSession } from './custody.mjs';
+import { ACTIVE_RUN_IDS } from './queries.mjs';
+
+const identity = s => [s?.pane ?? null, s?.session_id ?? null, s?.machine ?? null,
+  s?.harness ?? null, s?.surface ?? null, s?.address ?? null, s?.pid ?? null, s?.launch_key ?? null];
+const machineName = name => String(name ?? '').split('.')[0].toLowerCase().replace(/[^a-z0-9_-]/g, '-');
+/** A candidate grants no close authority after an await. This guard runs inside the public
+ * close's reservation, immediately before each physical mutation, and again before confirmation. */
+export function deferredCloseCurrent(board, row, session, claim) {
+  return view(board, db => {
+    const latest = db.prepare('SELECT task_id,ended_at,metadata FROM task_runs WHERE id=?').get(row.id);
+    const current = json(latest?.metadata, {})?.supercode;
+    if (!latest || latest.task_id !== row.task_id || latest.ended_at !== row.ended_at || !current
+      || JSON.stringify(identity(current)) !== JSON.stringify(identity(session))
+      || detachedCard(db, row.task_id) || detachedSession(db, current) || current.close_confirmed_at
+      || current.close_transferred_to || current.released || !current.close_requested
+      || current.close_requested !== claim.requested || current.close_claim?.lock !== claimer()
+      || current.close_claim?.lock !== claim.lock || current.close_claim?.expires !== claim.expires
+      || !(Number(current.close_claim?.expires) > now())
+      || current.monitor_held !== claim.monitor || current.retain_after_run !== claim.retained) return false;
+    return !db.prepare(`SELECT metadata FROM task_runs WHERE id IN (${ACTIVE_RUN_IDS})`).all().some(run => {
+      const s = json(run.metadata, {})?.supercode;
+      if (!s) return false;
+      const sameMachine = machineName(s.machine) === machineName(session.machine);
+      return sameMachine && ((session.pane && s.pane === session.pane)
+        || (session.session_id && s.session_id === session.session_id && (s.harness ?? 'claude-code') === (session.harness ?? 'claude-code'))
+        || (session.surface === 'headless' && session.pid && s.pid === session.pid));
+    });
+  });
+}
+
+export function requireDeferredClose(board, row, session, claim) {
+  if (!deferredCloseCurrent(board, row, session, claim)) throw Object.assign(
+    new Error('close dropped: its run, claim, retention or active session binding changed'), { closeSuperseded: true });
+}

package/board/current-records.mjs

@@ -0,0 +1,44 @@
+// A held connection's current card projection. TEMP triggers identify its own writes, including
+// writes without public events. They persist no state: a foreign commit, reload, lost watermark or
+// overlay/schema change requires a bounded rebuild. Rollback marks are harmless extra refreshes.
+import { LIST_CONNECTION, listRevision, readBoundary } from './listing.mjs';
+
+export const currentRecordConnection = db => db[LIST_CONNECTION] ?? db;
+const tracked = new WeakMap();
+const RETAINED_CARDS = 4096;
+export function trackCurrentRecords(db) {
+  if (tracked.has(db)) return;
+  const state = { epoch: 0, floor: 0, reset: 0, rewritten: 0, cards: new Map() };
+  tracked.set(db, state);
+  db.function('supercode_current_changed', (table, id, rewrite) => {
+    const epoch = ++state.epoch;
+    if (table === 'custody') state.reset = epoch;
+    if (table === 'events' && rewrite) state.rewritten = epoch;
+    if (id != null) { state.cards.delete(id); state.cards.set(id, epoch); }
+    if (state.cards.size > RETAINED_CARDS) {
+      const first = state.cards.keys().next().value;
+      state.floor = state.cards.get(first); state.cards.delete(first);
+    }
+  });
+  const specs = [['tasks', 'id', 'cards'], ['supercode_cards', 'task_id', 'cards'],
+    ['task_runs', 'task_id', 'runs'], ['task_events', 'task_id', 'events'],
+    ['task_links', 'parent_id', 'links'], ['supercode_session_custody', 'task_id', 'custody']];
+  for (const [table, key, kind] of specs) for (const [verb, rows] of [['INSERT', ['NEW']], ['UPDATE', ['OLD', 'NEW']], ['DELETE', ['OLD']]]) {
+    const calls = rows.flatMap(row => [key, ...(table === 'task_links' ? ['child_id'] : [])]
+      .map(column => `SELECT supercode_current_changed('${kind}',${row}.${column},${verb === 'INSERT' ? 0 : 1});`)).join(' ');
+    db.exec(`CREATE TEMP TRIGGER IF NOT EXISTS supercode_current_${table}_${verb.toLowerCase()} AFTER ${verb} ON main.${table} BEGIN ${calls} END`);
+  }
+}
+
+/** Snapshot changes at one read boundary; never trust row hints across a foreign commit. */
+export function currentRecordChanges(db, previous = null) {
+  return readBoundary(db, () => {
+    const revision = listRevision(db), connection = currentRecordConnection(db), state = tracked.get(connection);
+    const token = { ...revision, epoch: state?.epoch ?? null, rewritten: state?.rewritten ?? null };
+    const reset = !previous || !state || previous.connection !== token.connection || previous.data !== token.data
+      || previous.mainSchema !== token.mainSchema || previous.tempSchema !== token.tempSchema
+      || previous.epoch == null || previous.epoch < state.floor || previous.epoch < state.reset;
+    const cards = reset ? null : previous.epoch === state.epoch ? [] : [...state.cards].filter(([, epoch]) => epoch > previous.epoch).map(([id]) => id);
+    return { token, reset, cards, eventsRewritten: reset || previous.rewritten !== token.rewritten };
+  });
+}

package/board/custody.mjs

@@ -1,3 +1,4 @@
+import { latestEvent } from './queries.mjs';
 // Native identity survives a handback. Custody decides what this board may do with it.
 import { randomUUID } from 'node:crypto';
 import { hostname } from 'node:os';
@@ -73,7 +74,7 @@ export function detachSession(board, id, person) {
       return sessionAddress(s) && sessionAddress(s) !== address && s.close_requested && !s.close_confirmed_at && !s.close_transferred_to && !s.detached_at;
     })) throw new Error('another native session on this card has an unresolved close; settle that receipt before detaching');
     assertNoSessionOperation(db, id, address);
-    const adoption = db.prepare("SELECT id,kind,payload FROM task_events WHERE task_id=? AND kind IN ('dispatch_held','dispatch_released','session_adopted','adoption_failed','adoption_claimed') ORDER BY id DESC LIMIT 1").get(id);
+    const adoption = latestEvent(db, id, ['dispatch_held','dispatch_released','session_adopted','adoption_failed','adoption_claimed'], 'id,kind,payload');
     const request = json(adoption?.payload, {});
     if (adoption?.kind === 'adoption_claimed' && request.lock && operationAlive({ owner: request.lock })) throw new Error('an adoption is already being bound; wait for its answer before detaching');
     for (const other of 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 t.id<>?').all(id)) {