@volter/supercode-orchestrator 0.5.211 → 0.5.213

package/board/github-rest.mjs

@@ -26,10 +26,77 @@ function connection() {
       resource TEXT, used INTEGER, remaining INTEGER, reset_at INTEGER, retry_after INTEGER);
     CREATE INDEX IF NOT EXISTS github_attempts_window ON github_attempts(credential,started_at,purpose);
     CREATE INDEX IF NOT EXISTS github_attempts_home_window ON github_attempts(started_at,purpose);
-    CREATE TABLE IF NOT EXISTS github_cooldown (credential TEXT PRIMARY KEY, until_at INTEGER NOT NULL, reason TEXT NOT NULL);`);
+    CREATE TABLE IF NOT EXISTS github_cooldown (credential TEXT PRIMARY KEY, until_at INTEGER NOT NULL, reason TEXT NOT NULL);
+    CREATE TABLE IF NOT EXISTS github_discovery (
+      key TEXT PRIMARY KEY, observed_at INTEGER NOT NULL, until_at INTEGER NOT NULL,
+      value TEXT, error TEXT, claim TEXT, claim_until INTEGER NOT NULL DEFAULT 0);
+    CREATE TABLE IF NOT EXISTS github_refusals (
+      id TEXT PRIMARY KEY, started_at INTEGER NOT NULL, credential TEXT NOT NULL, machine TEXT NOT NULL,
+      pid INTEGER NOT NULL, caller TEXT NOT NULL, purpose TEXT NOT NULL, method TEXT NOT NULL,
+      endpoint TEXT NOT NULL, code TEXT NOT NULL, reason TEXT NOT NULL);
+    CREATE INDEX IF NOT EXISTS github_refusals_window ON github_refusals(started_at,purpose);
+    CREATE TABLE IF NOT EXISTS github_observation_meta (key TEXT PRIMARY KEY, value INTEGER NOT NULL);`);
+  db.prepare("INSERT OR IGNORE INTO github_observation_meta(key,value) VALUES('refusals_since',?)").run(Date.now());
   connections.set(path, db);
   return db;
 }
+
+const discoveryReads = new Map();
+const discoveryPending = () => Object.assign(new Error('GitHub discovery is already being read by another process; no duplicate read was started'), { code: 'github_discovery_pending', deferred: true });
+/** Advisory observations survive command/owner restarts. Fresh transition reads never consume a cached value,
+ * but publish their successful observation for discovery. A short transaction claims each advisory read; no
+ * transaction spans I/O and a different process defers rather than waiting or duplicating its wire attempts. */
+export async function githubDiscovery(identity, ttl, read, { fresh = false, ttlOf = () => ttl, cacheErrors = true } = {}) {
+  const key = createHash('sha256').update(identity).digest('hex');
+  const localKey = `${pathOf()}\0${key}`;
+  if (!fresh && discoveryReads.has(localKey)) return discoveryReads.get(localKey);
+  const work = async () => {
+    const db = connection(), began = Date.now(), claim = randomUUID();
+    if (!fresh) {
+      let cached = null;
+      db.exec('BEGIN IMMEDIATE');
+      try {
+        const held = db.prepare('SELECT * FROM github_discovery WHERE key=?').get(key);
+        if (held && held.until_at > began && (held.value != null || held.error != null)) {
+          cached = held;
+        } else {
+          if (held?.claim_until > began) throw discoveryPending();
+          db.prepare(`INSERT INTO github_discovery(key,observed_at,until_at,claim,claim_until) VALUES(?,0,0,?,?)
+            ON CONFLICT(key) DO UPDATE SET claim=excluded.claim,claim_until=excluded.claim_until`).run(key, claim, began + 360_000);
+        }
+        db.exec('COMMIT');
+      } catch (error) { db.exec('ROLLBACK'); throw error; }
+      if (cached) {
+        if (cached.error) { const failure = JSON.parse(cached.error); throw Object.assign(new Error(failure.message), failure); }
+        return JSON.parse(cached.value);
+      }
+    }
+    const retain = (value, error, duration = ttl) => {
+      db.prepare(`INSERT INTO github_discovery(key,observed_at,until_at,value,error) VALUES(?,?,?,?,?)
+        ON CONFLICT(key) DO UPDATE SET observed_at=excluded.observed_at,until_at=excluded.until_at,
+          value=excluded.value,error=excluded.error,claim=NULL,claim_until=0
+        WHERE github_discovery.observed_at<=excluded.observed_at`).run(key, began, Date.now() + duration, value, error);
+    };
+    try {
+      const value = await read();
+      retain(JSON.stringify(value), null, ttlOf(value));
+      return value;
+    } catch (error) {
+      if (!fresh && cacheErrors) retain(null, JSON.stringify({ message: String(error.message).slice(0, 1000), code: error.code, deferred: error.deferred, retry_at: error.retry_at }));
+      throw error;
+    } finally {
+      db.prepare('UPDATE github_discovery SET claim=NULL,claim_until=0 WHERE key=? AND claim=?').run(key, claim);
+      // Retain only live observations/claims. Expired advisory data has no evidentiary role.
+      db.prepare('DELETE FROM github_discovery WHERE until_at<=? AND claim_until<=?').run(Date.now(), Date.now());
+    }
+  };
+  const pending = work();
+  if (!fresh) {
+    discoveryReads.set(localKey, pending);
+    try { return await pending; } finally { if (discoveryReads.get(localKey) === pending) discoveryReads.delete(localKey); }
+  }
+  return pending;
+}
 const refusal = (message) => Object.assign(new Error(message), { code: 'GITHUB_BUDGET' });
 const integer = (value) => value != null && /^\d+$/.test(value) && Number.isSafeInteger(Number(value)) ? Number(value) : null;
 function endpointOf(url) {
@@ -63,7 +130,15 @@ async function issue(url, options, { purpose }) {
     db.prepare('INSERT INTO github_attempts(id,credential,started_at,machine,pid,caller,purpose,method,endpoint) VALUES(?,?,?,?,?,?,?,?,?)')
       .run(id, credential, at, hostname(), process.pid, caller, purpose, method, endpoint);
     db.exec('COMMIT');
-  } catch (error) { db.exec('ROLLBACK'); throw error; }
+  } catch (error) {
+    db.exec('ROLLBACK');
+    // A refused action made no wire attempt. Keep its receipt separately so a full-hour qualification can read
+    // actual budget refusals as well as usage, without inflating the allowance or inferring success from silence.
+    if (error.code === 'GITHUB_BUDGET') db.prepare(`INSERT INTO github_refusals
+      (id,started_at,credential,machine,pid,caller,purpose,method,endpoint,code,reason) VALUES(?,?,?,?,?,?,?,?,?,?,?)`)
+      .run(id, at, credential, hostname(), process.pid, caller, purpose, method, endpoint, error.code, error.message);
+    throw error;
+  }
   let response, outcome = 'unknown';
   try { response = await fetch(url, { ...options, redirect: 'manual' }); outcome = response.ok ? 'ok' : `HTTP_${response.status}`; return response; }
   catch (error) { outcome = error.code ?? error.name ?? 'transport_error'; throw error; }
@@ -109,7 +184,14 @@ export function githubUsage({ since = Date.now() - HOUR } = {}) {
   if (!existsSync(path)) return { path, recorded: false, callers: [], endpoints: [] };
   const db = new DatabaseSync(path, { readOnly: true });
   try {
+    const hasRefusals = Boolean(db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='github_refusals'").get());
+    const hasMeta = Boolean(db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='github_observation_meta'").get());
+    const refusalsSince = hasMeta ? db.prepare("SELECT value FROM github_observation_meta WHERE key='refusals_since'").get()?.value ?? null : null;
     return { path, recorded: true, since, limits: { hourly: GITHUB_HOURLY_ATTEMPTS, discovery: GITHUB_DISCOVERY_ATTEMPTS },
+      refusals_recorded: hasRefusals, refusals_since: refusalsSince, refusals_complete: refusalsSince != null && refusalsSince <= since,
+      refusals: hasRefusals ? db.prepare(`SELECT credential,machine,pid,caller,purpose,method,endpoint,code,COUNT(*) refusals,
+        MIN(started_at) first_at,MAX(started_at) last_at FROM github_refusals WHERE started_at>=?
+        GROUP BY credential,machine,pid,caller,purpose,method,endpoint,code`).all(since).map(r => ({ ...r, caller: JSON.parse(r.caller) })) : [],
       callers: db.prepare(`SELECT credential,machine,pid,caller,purpose,COUNT(*) attempts,SUM(status IS NULL) unanswered
         FROM github_attempts WHERE started_at>=? GROUP BY credential,machine,pid,caller,purpose`).all(since).map(r => ({ ...r, caller: JSON.parse(r.caller) })),
       endpoints: db.prepare(`SELECT credential,machine,pid,caller,purpose,method,endpoint,status,COUNT(*) attempts

package/board/incidents.mjs

@@ -126,6 +126,7 @@ export function auditEndedRuns(db, board, entry) {
     if (decided) continue; // its manager or creator ended it by an explicit act
     const audited = db.prepare("SELECT 1 FROM task_events WHERE task_id=? AND run_id=? AND kind='audited'").get(task.id,task.run_id);
     if (audited) continue; // Every explicitly schedules the next successful audit
+    if (session?.retain_after_run && task.outcome === 'completed') continue; // an explicit finish hands work to review
     if (['blocked','paused','reconfigured','review_passed','review','review_requested','audited'].includes(task.outcome)) continue;
     surfaceIncident(db, board, entry, task.id, 'run_ended', { error: task.error, outcome: task.outcome }, task.run_id);
   }

package/board/machine-fleet.mjs

@@ -112,7 +112,9 @@ export async function readMachineFleet(machines, local) {
         // what a session that needs input says it waits for, what started its open turn (Codex: `goal` for a thread
         // goal's continuation) and since when, where its harness publishes them
         waiting_for: activity.evidence?.waiting_for ?? null, turn_source: activity.evidence?.source ?? null, turn_since_ms: activity.evidence?.native_state_since_ms ?? null,
-        turn_trigger: activity.evidence?.turn_trigger ?? null });
+        turn_trigger: activity.evidence?.turn_trigger ?? null,
+        // the question its pane shows and its options, where its machine read one off the screen (VO-3395)
+        question: activity.evidence?.question ?? null });
     }
   }
   const ok = online.has(local);

package/board/session-work.mjs

@@ -50,3 +50,10 @@ export function idleInterval(session, live, observedAt) {
   const since = Math.min(observedAt, Math.max(read, Number(session.watch_since ?? 0)));
   return { since, quiet: Math.max(0, observedAt - since) };
 }
+
+/** A question a run's session shows on its pane (VO-3395), as one line: its words and each option, numbered. */
+export function questionText(question) {
+  if (!question) return '';
+  const options = (question.options ?? []).map((option) => `[${option.number}] ${option.label}`).join(' ');
+  return `${question.question ? `${question.question} ` : ''}${options}`.trim();
+}

package/board/store.mjs

@@ -516,7 +516,7 @@ export function heldConfigWatched(slug, source, watched) {
 
 export function openBoard(root, slug = DEFAULT_BOARD, options = {}) {
   // a listing on the owner's read door reads on a connection of its own, never the held board's (openReadOnly)
-  if (current().readOnly) return openReadOnly(root, slug);
+  if (current().readOnly) return openBoardSnapshot(root, slug);
   if (holding !== null && !options.create && realRoot(root) === holding && !untrustedConfig.get(slug)?.size) {
     let entry = heldBoards.get(slug);
     if (!entry) {
@@ -553,7 +553,7 @@ function heldHandle(entry, slug) {
  * reader can take; a store not in WAL or not laid out; one it cannot begin reading, `unreadable`) is left to the owner
  * (listing.mjs byOwner).
  */
-function openReadOnly(root, slug) {
+export function openBoardSnapshot(root, slug) {
   const use = backingOf(root, slug);
   if (!use) throw new Error(`no board ${slug} in ${root} (${boardPath(root, slug)})`);
   const path = backingPaths(root, slug)[use];

package/board/workflow.mjs

@@ -382,6 +382,14 @@ function stateRequestOf(db, id) {
 
 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
+ * the preceding section, so a task or another section's checkbox never acquires Acceptance permissions. */
+export function cardSectionHeading(line) {
+  const heading = /^#{1,6}\s+(.+?)\s*$/.exec(line);
+  if (heading) return heading[1].replace(/:$/, '').toLowerCase();
+  const label = /^\s*([A-Za-z][A-Za-z0-9 _-]*):\s*$/.exec(line);
+  return label ? label[1].trim().toLowerCase() : null;
+}
 /** Whether `body` is `was` with only outcomes ticked: each changed line is under the Acceptance heading, was `- [ ] X`
  *  and is now `- [x] X` or `- [x] X: <pointer>`, or was `- [x] X` and is now `- [x] X: <pointer>` (the pointer a tick
  *  needs, added after it); no other line added, removed or changed. */
@@ -393,8 +401,8 @@ function onlyTicks(was, body) {
   // an outcome is a line of the card's Acceptance section (its heading at any level), not a task or any other checkbox
   let section = null;
   return before.every((line, i) => {
-    const heading = /^#{1,6}\s+(.+?)\s*$/.exec(line);
-    if (heading) section = heading[1].toLowerCase();
+    const heading = cardSectionHeading(line);
+    if (heading !== null) section = heading;
     if (line === after[i]) return true;
     if (section !== 'acceptance') return false;
     const pointed = (ticked) => after[i].startsWith(`${ticked}: `) && after[i].trim().length > ticked.trim().length + 1;
@@ -487,8 +495,8 @@ export function scopeOf(db, board, task, { params, event = {}, extra = {}, lazy
       const lines = String(task.body ?? '').split('\n');
       let acceptance = false;
       return lines.every((line) => {
-        const heading = /^#{1,6}\s+(.+?)\s*$/.exec(line);
-        if (heading) acceptance = heading[1].toLowerCase() === 'acceptance';
+        const heading = cardSectionHeading(line);
+        if (heading !== null) acceptance = heading === 'acceptance';
         if (!acceptance || !/^\s*[-*] \[[ xX]\]/.test(line)) return true;
         return /^\s*[-*] \[[xX]\] .+: \S.+$/.test(line);
       });
@@ -1055,7 +1063,7 @@ const ACTIONS = {
       else runSession(ctx, (s) => ({ ...s, [counter]: 0 }));
     }
   },
-  end_run(ctx, { outcome, summary = null, error = null } = {}) {
+  end_run(ctx, { outcome, summary = null, error = null, close_session = true } = {}) {
     const row = one(ctx.db, 'SELECT current_run_id FROM tasks WHERE id = ?', ctx.id);
     const t = now();
     if (row?.current_run_id) {
@@ -1063,10 +1071,15 @@ const ACTIONS = {
       retireSupersededRuns(ctx.db, ctx.id, runId, json(one(ctx.db, 'SELECT metadata FROM task_runs WHERE id = ?', runId)?.metadata, {})?.supercode);
       run(ctx.db, `UPDATE task_runs SET status = ?, outcome = ?, summary = COALESCE(?, summary), error = COALESCE(?, error), ended_at = ?, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL
                WHERE id = ? AND ended_at IS NULL`, outcome, outcome, summary, error ?? ctx.scope.event?.error ?? null, t, runId);
-      requestSessionClose(ctx.db, ctx.id, { runId });
       ctx.runId = runId;
       ctx.lastOutcome = outcome;
-      ctx.effects.push({ kind: 'run_ended', id: ctx.id, runId, outcome });
+      runSession(ctx, session => ({ ...session, retain_after_run: !close_session }));
+      // A declared completion may end the attempt while retaining its role session. In particular, its own caller
+      // must be able to finish and return before the board starts the independent review.
+      if (close_session) {
+        requestSessionClose(ctx.db, ctx.id, { runId });
+        ctx.effects.push({ kind: 'run_ended', id: ctx.id, runId, outcome });
+      }
     } else if (summary || ctx.scope.event?.metadata) {
       // an outcome reached with no run open (a person completing a card nobody claimed)
       const task = one(ctx.db, 'SELECT assignee FROM tasks WHERE id = ?', ctx.id);
@@ -1153,8 +1166,12 @@ const ACTIONS = {
     if (said?.body !== undefined && said?.body !== null) run(ctx.db, 'UPDATE tasks SET body = ? WHERE id = ?', said.body, ctx.id);
   },
   decompose(ctx, said) {
-    // the children are filed by the caller before the event (they are cards of their own); the card waits on them
-    for (const child of said?.children ?? []) run(ctx.db, 'INSERT OR IGNORE INTO task_links (parent_id, child_id) VALUES (?, ?)', child, ctx.id);
+    // Native arc tasks are worked by the arc's session, never dispatched as prerequisite cards of their own.
+    // Retain the older workflow's dependency action only for separately declared cards.
+    for (const child of said?.children ?? []) {
+      if (one(ctx.db, 'SELECT subtask_of FROM supercode_cards WHERE task_id=?', child)?.subtask_of === ctx.id) continue;
+      run(ctx.db, 'INSERT OR IGNORE INTO task_links (parent_id, child_id) VALUES (?, ?)', child, ctx.id);
+    }
   },
   // card ids a handoff names that no card has (Hermes flags them the same way)
   check_references(ctx, said) {
@@ -1239,16 +1256,25 @@ const ACTIONS = {
 /** Binding a newer run transfers ownership; stale run references cannot veto its later stop. */
 export function retireSupersededRuns(db, id, runId, session) {
   if (!session?.session_id && !session?.pane) return;
-  for (const old of all(db, `SELECT id,task_id,metadata FROM task_runs WHERE id IN (
-    SELECT id FROM task_runs WHERE id<? AND ended_at IS NULL AND json_extract(metadata, '$.supercode.machine') IS ?
+  for (const old of all(db, `SELECT id,task_id,ended_at,metadata FROM task_runs WHERE id IN (
+    SELECT id FROM task_runs WHERE id<? AND json_extract(metadata, '$.supercode.machine') IS ?
       AND json_extract(metadata, '$.supercode.session_id')=?
-    UNION SELECT id FROM task_runs WHERE id<? AND ended_at IS NULL AND json_extract(metadata, '$.supercode.machine') IS ?
+    UNION SELECT id FROM task_runs WHERE id<? AND json_extract(metadata, '$.supercode.machine') IS ?
       AND json_extract(metadata, '$.supercode.pane')=?)`,
     runId, session.machine ?? null, session.session_id ?? null, runId, session.machine ?? null, session.pane ?? null)) {
     const whole = json(old.metadata, {}) ?? {}, s = whole.supercode;
     if (!s || detachedSession(db, s) || s.machine !== session.machine || !((session.session_id && s.session_id === session.session_id) || (session.pane && s.pane === session.pane))) continue;
     if (old.task_id !== id && one(db, 'SELECT 1 FROM tasks WHERE current_run_id = ?', old.id)) throw new Error(`session is still owned by active run ${old.id} of ${old.task_id}`);
-    if (s.pane && s.pane === session.pane) whole.supercode = { ...s, close_transferred_to: runId, close_requested: null };
+    const transferred = (s.pane && s.pane === session.pane) || (!s.pane && !session.pane && s.session_id === session.session_id);
+    if (old.ended_at) {
+      if (transferred && s.close_transferred_to !== runId) {
+        whole.supercode = { ...s, close_transferred_to: runId, close_requested: null };
+        run(db, 'UPDATE task_runs SET metadata=? WHERE id=?', JSON.stringify(whole), old.id);
+        record(db, old.task_id, 'session_transferred', { successor: runId, session_id: s.session_id, pane: s.pane ?? null }, old.id);
+      }
+      continue;
+    }
+    if (transferred) whole.supercode = { ...s, close_transferred_to: runId, close_requested: null };
     run(db, "UPDATE task_runs SET status='superseded', outcome='superseded', ended_at=?, claim_lock=NULL, claim_expires=NULL, worker_pid=NULL, metadata=? WHERE id=?", now(), JSON.stringify(whole), old.id);
     record(db, old.task_id, 'run_superseded', { successor: runId, session_id: s.session_id, pane: s.pane }, old.id);
   }

package/board/workspace.mjs

@@ -1,5 +1,5 @@
 // Filesystem/RPC work happens before a board transaction; the ownership check is pure.
-import { existsSync } from 'node:fs';
+import { existsSync, realpathSync } from 'node:fs';
 import { basename, dirname } from 'node:path';
 import { runtimeDoor } from './runtime-door.mjs';
 import { inspectCheckout } from '@volter/teams/checkout';
@@ -130,23 +130,34 @@ export async function checkWorkspace(board, task) {
   if (task.workspace_kind === 'scratch') return null;
   task = { ...task, handle: task.handle ?? cardHandleOf(board, task.id) };
   const facts = await resolveWorkspace(task), peers = [];
-  if (task.workspace_kind === 'dir' && !facts.linked) {
-    for (const row of board.db.prepare(`SELECT t.id,t.workspace_path,t.branch_name,c.workspace_anchor,c.machine FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.current_run_id IS NOT NULL AND t.workspace_kind='dir'`).all()) {
+  const workspaceRoot = task.workspace_kind === 'worktree' ? facts.path : facts.root;
+  // New claims retain their exact checkout receipt before launch. Legacy claims without a receipt are resolved
+  // once for this check, including subdirectories and remote aliases that their retained path alone cannot identify.
+  {
+    for (const row of board.db.prepare(`SELECT t.id,t.workspace_kind,t.workspace_path,t.branch_name,c.workspace_anchor,c.machine FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.current_run_id IS NOT NULL AND t.workspace_kind!='scratch' AND c.workspace_root IS NULL`).all()) {
       if (row.id === task.id || normalMachine(row.machine ?? localMachine()) !== normalMachine(task.machine ?? localMachine())) continue;
       let other;
-      try { other = await resolveWorkspace({ ...row, workspace_kind: 'dir' }); } catch { continue; } // That card's own launch reports its invalid workspace.
-      if (!other.linked && other.root === facts.root) peers.push(row.id);
+      try { other = await resolveWorkspace({ ...row, handle: cardHandleOf(board, row.id) }); } catch { continue; } // Its retained path/reservation is still checked below.
+      if ((row.workspace_kind === 'worktree' ? other.path : other.root) === workspaceRoot) peers.push(row.id);
     }
   }
-  const checked = { ...facts, mainRoot: task.workspace_kind === 'dir' && !facts.linked ? facts.root : null, peers };
+  const checked = { ...facts, workspaceRoot, peers };
   assertWorkspaceOwner(board.db, task, checked);
   return checked;
 }
+const workspacePath = (path, local) => {
+  if (!path) return null;
+  if (local) { try { return realpathSync(path); } catch { /* a pre-launch reservation may not exist yet */ } }
+  return path.replace(/\/+$/, '');
+};
 export function assertWorkspaceOwner(db, task, checked) {
-  if (!checked?.mainRoot) return;
-  const conflict = db.prepare(`SELECT t.id,c.machine,c.workspace_root FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.current_run_id IS NOT NULL AND t.workspace_kind='dir'`).all()
-    .find(row => row.id !== task.id && normalMachine(row.machine ?? localMachine()) === normalMachine(task.machine ?? localMachine()) && (row.workspace_root === checked.mainRoot || checked.peers?.includes(row.id)));
-  if (conflict) throw new Error(`main checkout is already used by running card ${conflict.id}; declare worktree:${checked.repository} for a solo worktree`);
+  if (!checked?.workspaceRoot) return;
+  const machine = normalMachine(task.machine ?? localMachine()), local = machine === localMachine();
+  const path = workspacePath(checked.workspaceRoot, local);
+  const conflict = db.prepare(`SELECT t.id,t.workspace_path,c.machine,c.workspace_root FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.current_run_id IS NOT NULL AND t.workspace_kind!='scratch'`).all()
+    .find(row => row.id !== task.id && normalMachine(row.machine ?? localMachine()) === machine &&
+      (workspacePath(row.workspace_root, local) === path || workspacePath(row.workspace_path, local) === path || checked.peers?.includes(row.id)));
+  if (conflict) throw new Error(`workspace ${checked.path} is already used by running card ${conflict.id}; declare worktree:${checked.repository} for a solo worktree`);
 }
 
 export const isLocalWorkspace = task => !task.machine || normalMachine(task.machine) === localMachine();

package/board-input.d.ts

@@ -1,2 +1,4 @@
 /** Read a remote card write's selected text file (or stdin) on the caller's machine. */
 export function prepareBoardText(argv: string[]): { argv: string[]; stdin: string | null };
+/** Read a caller-local attachment in bounded requests, ending with its digest. */
+export function prepareBoardInputs(argv: string[]): Generator<{ argv: string[]; stdin: string | null }>;

package/board-input.mjs

@@ -1,6 +1,8 @@
 // A remote card write reads its text on the caller's machine, before the board door is called.
 // The board's own argument parser decides which file is used; its last value wins.
-import { readFileSync } from 'node:fs';
+import { closeSync, fstatSync, openSync, readFileSync, readSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { basename } from 'node:path';
 import { parse } from './board/args.mjs';
 
 /** Carry a comment/create/specify text input as the owner's existing `stdin` field. */
@@ -14,3 +16,33 @@ export function prepareBoardText(argv) {
   // reads the carried text at `-`, never an unrelated file at the caller's original path on another machine.
   return { argv: [...argv, `--${key}`, '-'], stdin: readFileSync(file === '-' ? 0 : file, 'utf8') };
 }
+
+/** Each yielded request fits one board frame. Only the last answer is the attachment receipt. */
+export function* prepareBoardInputs(argv) {
+  const args = parse(argv);
+  if (args._[0] !== 'attach' || args.help) { yield prepareBoardText(argv); return; }
+  if (args._.length !== 3 || args.upload !== undefined) throw new Error('attach needs a card id and a local file');
+  const source = openSync(args._[2], 'r');
+  try {
+    const before = fstatSync(source, { bigint: true });
+    if (!before.isFile() || before.size > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error('attach needs a regular file of supported size');
+    const upload = randomUUID(), size = Number(before.size), hash = createHash('sha256');
+    const command = ['attach', args._[1], '-', '--upload', upload];
+    if (args.json) command.push('--json');
+    for (const key of ['name', 'content-type', 'author']) if (args[key] !== undefined) command.push(`--${key}`, args[key]);
+    const input = body => ({ argv: command, stdin: JSON.stringify(body) });
+    yield input({ action: 'begin', size, name: args.name ?? basename(args._[2]) });
+    const buffer = Buffer.alloc(1024 * 1024);
+    for (let offset = 0; offset < size;) {
+      const count = readSync(source, buffer, 0, Math.min(buffer.length, size - offset), offset);
+      if (count <= 0) throw new Error('attachment ended during upload; no attachment was committed');
+      const bytes = buffer.subarray(0, count); hash.update(bytes);
+      yield input({ action: 'append', offset, bytes: bytes.toString('base64') });
+      offset += count;
+    }
+    const after = fstatSync(source, { bigint: true });
+    if (before.size !== after.size || before.mtimeNs !== after.mtimeNs || before.ctimeNs !== after.ctimeNs)
+      throw new Error('attachment changed during upload; no attachment was committed');
+    yield input({ action: 'commit', sha256: hash.digest('hex') });
+  } finally { closeSync(source); }
+}

package/connection.mjs

@@ -38,6 +38,10 @@ export async function connectionCall(record, side, method, path, body, token) {
   if(!response.ok)throw Object.assign(new Error(`${side} ${method} ${path}: ${payload.error?.code??response.status}`),{code:payload.error?.code,status:response.status});
   return payload;
 }
+/** A registration that trusts a Workplace as its issuer trusts this connection's Workplace and organization, never the
+ * one its committed manifest names (agents.teams-app.json names production's): otherwise every connection's agents app
+ * trusted production's tokens, and its own Workplace's notices and views were decided as the issuer app instead. */
+export function trustedIssuer(manifest,record){return manifest.issuer===undefined?{}:{issuer:record.issuer,issuer_organization:record.organization};}
 export function connectionPath(root,id){return join(root,'apps','connections',id,'connection.json');}
 export function generateModuleConfig(root, record, grant) {
   if(SERVICE_APPS.includes(grant.name))return generateServiceConfig(root,record,grant);
@@ -172,7 +176,7 @@ export async function connectWorkplace(flags) {
       grant.rh2=exchanged.data;privateJson(path,record);
     }
     if(selected.teamsManifest&&!grant.teams){
-      if(!grant.registration){grant.stagedSecret??=`sca_${randomBytes(32).toString('base64url')}`;privateJson(path,record);grant.registration=(await connectionCall(record,'teams','POST',`/api/v1/teams/${encodeURIComponent(teams.team)}/apps`,{...selected.teamsManifest,name:`${selected.teamsManifest.name} (${id.slice(0,8)})`,secret:grant.stagedSecret},owner)).data;privateJson(path,record);}
+      if(!grant.registration){grant.stagedSecret??=`sca_${randomBytes(32).toString('base64url')}`;privateJson(path,record);grant.registration=(await connectionCall(record,'teams','POST',`/api/v1/teams/${encodeURIComponent(teams.team)}/apps`,{...selected.teamsManifest,...trustedIssuer(selected.teamsManifest,record),name:`${selected.teamsManifest.name} (${id.slice(0,8)})`,secret:grant.stagedSecret},owner)).data;privateJson(path,record);}
       grant.registration.secret=grant.stagedSecret;
       if(!grant.consent){grant.stagedCode??=`sci_${randomBytes(32).toString('base64url')}`;privateJson(path,record);grant.consent=(await connectionCall(record,'teams','POST',`/api/v1/teams/${encodeURIComponent(teams.team)}/apps/${grant.registration.id}/installations`,{redirect_url:selected.teamsManifest.redirect_urls[0],state:id,actions:selected.teamsManifest.actions,code:grant.stagedCode},owner)).data;privateJson(path,record);}
       grant.consent.code=grant.stagedCode;

package/hermes-cli.mjs

@@ -1,13 +1,14 @@
 // Hermes's own tools beside a worker (docs/plans/hermes-compat.md row 7). A home is a Hermes home, and the
 // skills it carries call Hermes's CLI (`hermes kanban …`, `hermes cron notepad …`, `hermes cron doctor`)
 // against it, so a worker of any harness runs with `HERMES_HOME` set to its profile's folder and the
-// pinned `hermes` on its `PATH`; and what Hermes's scheduler records about a failed run (its incidents,
-// in `cron/executions.db`) the orchestrator records through Hermes's own function.
+// pinned `hermes` on its `PATH`. Native cron incidents use the owning interchange codec, in the same executions store.
 import { spawn, spawnSync } from 'node:child_process';
 import { accessSync, constants, existsSync, readFileSync, statSync } from 'node:fs';
 import { delimiter, dirname, join } from 'node:path';
 import { parseDotenv } from './orchestration.mjs';
 import { locateHermes } from './apply/doors.mjs';
+import { recordCronIncident } from '@volter/supercode-interchange/cron-incidents';
+import { redactText } from '@volter/teams/redact';
 
 /** Hermes's interpreter over `code`, `payload` on stdin, without blocking the daemon: `{ status, stdout, stderr }`. */
 function python(install, code, payload, env, timeout) {
@@ -48,23 +49,10 @@ export function hermesToolEnv(profileDir) {
   return env;
 }
 
-/**
- * Record a failed run as Hermes's scheduler does: `cron.incidents.upsert_incident`, one incident per job
- * and error signature, in the profile's `cron/executions.db`. Answers the incident id, or null (and why)
- * when Hermes is not installed or refused.
- */
-export function recordIncident(profileDir, { job_id, job_name = null, error }) {
-  const install = hermesInstall();
-  if (!install?.python) return { id: null, why: 'no Hermes install on PATH' };
-  const code = 'import json,sys\nfrom cron.incidents import upsert_incident\na=json.loads(sys.stdin.read())\nprint(json.dumps(upsert_incident(a["job_id"], a["error"], job_name=a.get("job_name"))))';
-  const run = spawnSync(install.python, ['-c', code], {
-    input: JSON.stringify({ job_id, job_name, error: String(error ?? 'failed') }),
-    encoding: 'utf8', timeout: 30_000, cwd: install.source,
-    env: { PATH: process.env.PATH ?? '', HOME: process.env.HOME ?? '', HERMES_HOME: profileDir, PYTHONPATH: install.source },
-  });
-  if (run.status !== 0) return { id: null, why: (run.stderr || run.error?.message || '').trim().slice(-300) };
-  const [id] = JSON.parse(run.stdout.trim().split('\n').pop());
-  return { id };
+/** Record native cron failure grouping without requiring a separate Hermes Python installation. */
+export function recordIncident(profileDir, { job_id, error }) {
+  try { return recordCronIncident(profileDir, { job_id, error: String(error ?? 'failed'), redacted_error: redactText(String(error ?? 'failed')) }); }
+  catch (error) { return { id: null, why: error.message }; }
 }
 
 // Access through Hermes's own pairing store and writers (docs/plans/hermes-compat.md row 8): a code is

package/index.d.ts

@@ -443,7 +443,7 @@ export interface McpServerLaunch { name: string; command: string; arguments: str
 export function mountOrchestratorMcp(o: {
   root: Path; profile: Profile; harness: string; surfaceKey?: string | null;
   launch?: { program: string; arguments?: string[]; env?: Record<string, string> };
-  socketPath?: Path; serverPath?: Path; program?: string;
+  socketPath?: Path; program?: string;
   /** The Teams id of the agent the session is; the rh2-agent record installed for that id (`--agent`) is mounted beside
    * the orchestrator server as `rh2-agent`. */
   agentId?: string | null;

package/loop.mjs

@@ -6,6 +6,7 @@
 
 import { mkdirSync, writeFileSync, existsSync, readdirSync, readFileSync, renameSync, unlinkSync, realpathSync } from 'node:fs';
 import { basename, join, dirname } from 'node:path';
+import { parseSessionWire, stringifySessionWire } from '@volter/supercode-teams/session-read-client';
 import { step, leaseId } from './reducer.mjs';
 import * as events from './events.mjs';
 import { read, save, retainWorld, releaseWorld, refreshVault } from './orchestration.mjs';
@@ -278,9 +279,18 @@ export class Orchestrator {
       try {event={...event,identity:await this.identityRecord.observe({observation,location:JSON.stringify(event.key),at:Date.parse(event.at),name:event.sender_name,evidence:{adapter:event.adapter,message_id:event.message_id}})};}
       catch(error){event={...event,identity:{observation,principal:null,classification:'unresolved',label:'unresolved'}};this.log('warn',`identity observation unavailable: ${error.message}`);}
     }
+    const before = parseSessionWire(stringifySessionWire(this.state));
     const effects = step(this.state, event);
-    for (const effect of effects) {
+    const firstSave = effects.findIndex(effect => effect.type === 'save');
+    if (firstSave >= 0) {
+      // Persist the reducer's claims before any external action. A refused save must leave no in-memory gate or
+      // hosted-fire marker behind: otherwise the next tick thinks an execution that never started is still alive.
+      try { await this.save(); }
+      catch (error) { this.state = before; throw error; }
+    }
+    for (const [index, effect] of effects.entries()) {
       this.effectLog.push(effect);
+      if (index === firstSave) continue;
       await this.perform(effect);
     }
     return effects;

package/mcp/mount.mjs

@@ -24,13 +24,19 @@ import { SOCKET_ENV, socketPathFor } from './server.mjs';
 import { mcpServers } from '../hermes-home.mjs';
 import { KANBAN_ENV } from '../hermes-cli.mjs';
 import { installedAgentRecord } from '../installed-apps.mjs';
+import { supercodeHome } from '@volter/teams/home';
 
 export { MCP_DOORS, doorFor } from '@volter/supercode-harness-sdk/mcp-doors';
 
-/** The stdio server this module mounts. */
+/** The stdio server `supercode orchestrator mcp-server` runs (the mount names that door, never this path). */
 export const SERVER_PATH = resolve(dirname(fileURLToPath(import.meta.url)), 'server.mjs');
-/** The orchestrator's CLI, whose `apps mcp` runs `rh2 mcp` as an installed agent. */
-const ORCHESTRATOR_BIN = resolve(dirname(fileURLToPath(import.meta.url)), '../bin/orchestrator.mjs');
+/** The machine's stable `supercode` (the source pin's shim in the supercode home, else the one on PATH), which runs
+ * every program a session mounts (`orchestrator mcp-server`, `orchestrator apps mcp`): a config that names it names no
+ * release, so the pin that retires a tree leaves it working. */
+function stableSupercode() {
+  const shim = join(supercodeHome(), 'bin', process.platform === 'win32' ? 'supercode.cmd' : 'supercode');
+  return existsSync(shim) ? shim : 'supercode';
+}
 /** The MCP server an agent with an installed rh2-agent gets: `rh2 mcp` as that agent (its own name, so the user's own
  * `rh2` server, whatever it holds, is neither replaced nor relied on). */
 export const RH2_AGENT_SERVER = 'rh2-agent';
@@ -40,7 +46,7 @@ export const RH2_AGENT_SERVER = 'rh2-agent';
  * Teams id): a record is found by that id alone, so an agent sharing another's name is never mounted with its record. */
 function rh2AgentServer(root, agentId, program) {
   if (!installedAgentRecord(root, agentId)) return null;
-  return { command: program, args: [ORCHESTRATOR_BIN, 'apps', 'mcp', 'rh2-agent', '--root', root, '--agent', agentId] };
+  return { command: stableSupercode(), args: ['orchestrator', 'apps', 'mcp', 'rh2-agent', '--root', root, '--agent', agentId, '--node', program] };
 }
 
 const slug = (surfaceKey) => (surfaceKey ? String(surfaceKey).replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '') || 'session' : 'session');
@@ -55,13 +61,12 @@ const slug = (surfaceKey) => (surfaceKey ? String(surfaceKey).replace(/[^A-Za-z0
  * @param {string|null} o.surfaceKey  the surface this session is bound to
  * @param {object|undefined} o.launch the launch the loop resolved, if any
  * @param {string} [o.socketPath]   defaults to `<root>/orchestrator.sock`
- * @param {string} [o.serverPath]   defaults to this package's `mcp/server.mjs`
- * @param {string} [o.program]      the interpreter, defaults to this node
+ * @param {string} [o.program]      the node the server runs with, defaults to this node
  * @param {string|null} [o.agentId] the Teams id of the agent whose own session this is, whose installed rh2-agent is
  *                                  mounted beside; null for a worker acting for an agent
  * @returns {{door: string, ran: string, launch: object|undefined, mcp_servers: object[]|null, path: string|null}}
  */
-export function mountOrchestratorMcp({ root, profile, harness, surfaceKey = null, launch, socketPath, serverPath = SERVER_PATH, program = process.execPath, vault = new Map(), task = null, agentId = null }) {
+export function mountOrchestratorMcp({ root, profile, harness, surfaceKey = null, launch, socketPath, program = process.execPath, vault = new Map(), task = null, agentId = null }) {
   const door = doorFor(harness);
   // the profile's own servers (`.mcp.json`, the workers' form; docs/plans/hermes-compat.md row 4), mounted
   // beside this one through the same door, `${VAR}` resolved from the profile's vault
@@ -81,6 +86,9 @@ export function mountOrchestratorMcp({ root, profile, harness, surfaceKey = null
   // board's tools for it (docs/plans/hermes-compat.md row 14)
   const sessionEnv = { ...env, ...(surfaceKey ? { [ORCH_ENV.surface]: surfaceKey } : {}), ...(task ?? {}) };
 
+  // the server through the stable supercode, never this release's server.mjs: a pin that retires this tree leaves the
+  // session's next server start (a resume, a reconnect) working
+  const server = { command: stableSupercode(), args: ['orchestrator', 'mcp-server', '--node', program] };
   switch (door) {
     case 'flag': {
       if (!launch) {
@@ -88,14 +96,14 @@ export function mountOrchestratorMcp({ root, profile, harness, surfaceKey = null
       }
       const file = join(home, `mcp-orchestrator-${slug(surfaceKey)}.json`);
       mkdirSync(home, { recursive: true });
-      writeMcpConfigFile(file, { ...own, [SERVER_NAME]: { command: program, args: [serverPath], env: sessionEnv } });
+      writeMcpConfigFile(file, { ...own, [SERVER_NAME]: { ...server, env: sessionEnv } });
       return { door, ran: `wrote ${file} and passed --mcp-config`, launch: withMcpConfigFlag(launch, file), mcp_servers: null, path: file };
     }
 
     case 'toml': {
       const file = join(home, 'config.toml');
       mkdirSync(home, { recursive: true });
-      const block = tomlBlock(program, serverPath, env);
+      const block = tomlBlock(server, env);
       let text = upsertTomlBlock(existsSync(file) ? readFileSync(file, 'utf8') : '', block, SERVER_NAME);
       const written = ownNames(home);
       for (const name of written) if (!(name in own)) text = removeTomlBlock(text, name);
@@ -115,7 +123,7 @@ export function mountOrchestratorMcp({ root, profile, harness, surfaceKey = null
       for (const name of ownNames(home)) if (!(name in own)) delete config.mcp[name];
       for (const [name, server] of Object.entries(own)) config.mcp[name] = opencodeEntry(server);
       recordOwnNames(home, Object.keys(own));
-      config.mcp[SERVER_NAME] = opencodeEntry({ command: program, args: [serverPath], env });
+      config.mcp[SERVER_NAME] = opencodeEntry({ ...server, env });
       writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
       return { door, ran: `wrote mcp.${SERVER_NAME} into ${file}`, launch, mcp_servers: null, path: file };
     }
@@ -131,7 +139,7 @@ export function mountOrchestratorMcp({ root, profile, harness, surfaceKey = null
         launch,
         mcp_servers: [
           ...Object.entries(own).filter(([, server]) => server.command).map(([name, server]) => acpEntry(name, server)),
-          acpEntry(SERVER_NAME, { command: program, args: [serverPath], env: sessionEnv }),
+          acpEntry(SERVER_NAME, { ...server, env: sessionEnv }),
         ],
         path: null,
       };
@@ -139,11 +147,11 @@ export function mountOrchestratorMcp({ root, profile, harness, surfaceKey = null
 }
 
 /** The orchestrator's own `[mcp_servers.orchestrator]` block. */
-function tomlBlock(program, serverPath, env) {
+function tomlBlock({ command, args }, env) {
   const lines = [
     `[mcp_servers.${SERVER_NAME}]`,
-    `command = ${tomlString(program)}`,
-    `args = [${tomlString(serverPath)}]`,
+    `command = ${tomlString(command)}`,
+    `args = [${args.map(tomlString).join(', ')}]`,
   ];
   for (const [k, v] of Object.entries(env)) lines.push(`env.${k} = ${tomlString(v)}`);
   // The per-session half rides codex's own env allowlist: the server is a child