@volter/supercode-orchestrator 0.5.211 → 0.5.212

package/bin/orchestrator.mjs

@@ -53,6 +53,11 @@ if (process.argv[2] === 'workflow') {
   const {disconnectWorkplace}=await import('../connection.mjs');
   try{const {values}=parseArgs({args:process.argv.slice(3),options:{root:{type:'string'},connection:{type:'string'}}});process.stdout.write(JSON.stringify(await disconnectWorkplace(values),null,2)+'\n');}
   catch(error){process.stderr.write(`disconnect: ${error.message}\n`);process.exitCode=1;}
+} else if (process.argv[2] === 'mcp-server') {
+  // a session's orchestrator tools on stdio, bound by its environment (mcp/mount.mjs mounts this through the stable
+  // supercode)
+  const {serveStdio,bindingFromEnv}=await import('../mcp/server.mjs');
+  serveStdio(bindingFromEnv());
 } else if (process.argv[2] === 'agent-channel') {
   await import('./agent-channel.mjs');
 } else {

package/board/attachment-write.mjs

@@ -0,0 +1,68 @@
+// Upload staging belongs to the board, beneath the authorized card, and to one caller.
+// No attachment record exists until all bytes and their digest have been verified.
+import { closeSync, fstatSync, linkSync, mkdirSync, openSync, readFileSync, readSync, rmSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { basename, join } from 'node:path';
+
+const CHUNK = 1024 * 1024;
+const safeName = name => basename(String(name)).replace(/[^A-Za-z0-9._ -]/g, '_').replace(/^\.+$/, '') || 'attachment';
+
+export function receiveAttachment({ directory, upload, caller, input, add }) {
+  if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(upload) || !caller)
+    throw new Error('attachment upload needs its identifier and an admitted caller');
+  let body;
+  try { body = JSON.parse(input); } catch { throw new Error('attachment upload needs JSON input'); }
+  const staging = join(directory, '.uploads', upload), metadata = join(staging, 'upload.json'), path = join(staging, 'bytes');
+  if (body?.action === 'begin') {
+    if (!Number.isSafeInteger(body.size) || body.size < 0 || typeof body.name !== 'string') throw new Error('invalid attachment extent or name');
+    mkdirSync(join(directory, '.uploads'), { recursive: true });
+    mkdirSync(staging, { mode: 0o700 });
+    try {
+      writeFileSync(path, '', { flag: 'wx', mode: 0o600 });
+      writeFileSync(metadata, JSON.stringify({ caller, size: body.size, name: safeName(body.name) }), { flag: 'wx', mode: 0o600 });
+    } catch (error) { rmSync(staging, { recursive: true, force: true }); throw error; }
+    return { ok: true, upload, received: 0 };
+  }
+  const held = JSON.parse(readFileSync(metadata, 'utf8'));
+  if (held.caller !== caller) throw new Error('attachment upload belongs to another caller');
+  if (body?.action === 'abort') { rmSync(staging, { recursive: true }); return { ok: true, upload, aborted: true }; }
+  if (body?.action === 'append') {
+    const bytes = typeof body.bytes === 'string' && body.bytes.length <= Math.ceil(CHUNK / 3) * 4 ? Buffer.from(body.bytes, 'base64') : null;
+    if (!bytes?.length || bytes.length > CHUNK || bytes.toString('base64') !== body.bytes
+      || !Number.isSafeInteger(body.offset) || body.offset < 0 || body.offset + bytes.length > held.size)
+      throw new Error('invalid attachment chunk');
+    const file = openSync(path, 'r+');
+    try {
+      if (fstatSync(file).size !== body.offset) throw new Error('attachment chunk is not at its next offset');
+      for (let written = 0; written < bytes.length;) {
+        const count = writeSync(file, bytes, written, bytes.length - written, body.offset + written);
+        if (count <= 0) throw new Error('attachment chunk write stopped');
+        written += count;
+      }
+    } finally { closeSync(file); }
+    return { ok: true, upload, received: body.offset + bytes.length };
+  }
+  if (body?.action !== 'commit' || !/^[a-f0-9]{64}$/.test(body.sha256)) throw new Error('invalid attachment upload action or digest');
+  const file = openSync(path, 'r'), hash = createHash('sha256'), buffer = Buffer.alloc(CHUNK);
+  try {
+    if (fstatSync(file).size !== held.size) throw new Error('attachment upload is incomplete');
+    for (let offset = 0; offset < held.size;) {
+      const count = readSync(file, buffer, 0, Math.min(CHUNK, held.size - offset), offset);
+      if (count <= 0) throw new Error('attachment upload ended before its extent');
+      hash.update(buffer.subarray(0, count)); offset += count;
+    }
+    if (hash.digest('hex') !== body.sha256) throw new Error('attachment upload digest does not match the source');
+  } finally { closeSync(file); }
+  let target;
+  for (let n = 0;; n++) {
+    target = join(directory, n ? `${n}-${held.name}` : held.name);
+    try { linkSync(path, target); break; } catch (error) { if (error.code !== 'EEXIST') throw error; }
+  }
+  let id;
+  try { id = add({ path: target, size: held.size }, held.name); }
+  catch (error) { unlinkSync(target); throw error; }
+  // The committed record is authoritative; failed staging cleanup must not turn success into an ambiguous retry.
+  let cleanup = null;
+  try { rmSync(staging, { recursive: true }); } catch { cleanup = staging; }
+  return { ok: true, id, path: target, size: held.size, sha256: body.sha256, name: held.name, ...(cleanup ? { cleanup } : {}) };
+}

package/board/cli.mjs

@@ -15,6 +15,7 @@ import { detachSession } from './custody.mjs';
 import { taskStatusOf } from './published.mjs';
 import { executionOf } from './session-work.mjs';
 import { attachmentRecord, readAttachment } from './attachment-read.mjs';
+import { receiveAttachment } from './attachment-write.mjs';
 import { listCardsInTurns, READ_BY_OWNER, writeCardList } from './listing.mjs';
 import { redactGuardText as redactText, withCredentialGuard } from './credential-guard.mjs';
 import { openOwnerDoor } from './owner-door.mjs';
@@ -112,13 +113,14 @@ The board's verbs, with their flags:
   comment <id> (<text> | --file PATH|-) [--author] [--max-len] [(--pr URL --pr-head SHA)...] [--source owner/repo:branch]...   attach <id> <path> [--name] [--content-type]   attachments <id>   attach-rm <n>
   attachment-read <id> <attachment-id> [--offset N --length N --version V]   bounded base64/metadata JSON, including through --at
   complete <id>... [--result] [--summary] [--metadata JSON] [--commit SHA]   edit <id> --result [--summary] [--metadata]
+  finish <id> --result TEXT   (when declared: end your completed attempt; the board selects review)
   block <id> [reason] (--on <card> | --waiting-on <message id>) [--ids ...]   schedule <id> [reason] [--ids ...]
   pause <id> --reason <why>   resume <id>   cancel <id> --reason <why>
   request-state <id> --state block|pause|done|cancelled --reason <why> [--on <card>|--waiting-on <message>] [--evidence <pointers>]
   unblock <id>... --on <blocker> --reason <what arrived>   request-review <id> (--pr URL --pr-head SHA)... [--summary] [--reviewer] [--force] [--commit SHA]   request-changes <id> <reason> [--finding <finding>]...   reopen-review <id>...   reopen <id>... [--reason]
   promote <id> [reason] [--ids ...] [--force] [--dry-run]   archive <id>... --reason <why> [--rm <id>...]
   specify <id> [--readable-id ID] [--title --body | --body-file PATH|-] [--workspace scratch|worktree:<repository>|dir:<repository>] [--branch NAME] [--machine M|none] [--all]
-  decompose <id> [--child "<title>[@<profile>]"]... [--all]
+  decompose <id> [--child "<title>[@<profile>]"]... [--all]  file the card's subtasks atomically, if its workflow allows
   diagnostics [--task] [--severity]   stats   assignees   log <id> [--tail N]   tail <id>   watch [--assignee] [--kinds]
   github-usage [--since 1h]          local REST attempts by caller/endpoint; no GitHub read
   notify-subscribe <id> --platform P --chat-id C [--thread-id]   notify-list [<id>]   notify-unsubscribe <id> --platform P --chat-id C
@@ -833,6 +835,15 @@ export async function runVerb(argv) {
     }
     case 'attach': {
       need(2, 'a card id and a file');
+      if (args.upload !== undefined) {
+        if (rest[1] !== '-') throw new Error('attachment upload reads its carried stdin');
+        withBoard(b => { if (!engine.getTask(b.db, id)) throw new Error(`no card ${id}`); });
+        const directory = join(slug === DEFAULT_BOARD ? join(root, 'kanban', 'attachments') : join(boardDir(root, slug), 'attachments'), id);
+        const result = receiveAttachment({ directory, upload: args.upload, caller: callerAddress() ?? actorOf(), input: current().stdin,
+          add: (file, name) => withBoard(b => engine.addAttachment(b, id, { file, name, contentType: args['content-type'] ?? null, author: args.author ?? callerName() })) });
+        say(args, result.id ? `Attached ${result.name} to ${id} (#${result.id}, sha256 ${result.sha256})` : `Upload ${args.upload}: ${result.received ?? 'aborted'}`, result);
+        return 0;
+      }
       const source = callerPath(rest[1]);
       if (!existsSync(source) || !statSync(source).isFile()) throw new Error(`no file ${rest[1]}`);
       const name = basename(args.name ?? source).replace(/[^A-Za-z0-9._ -]/g, '_') || 'attachment';

package/board/dispatch.mjs

@@ -27,7 +27,7 @@ import { readMachineFleet } from './machine-fleet.mjs';
 import { homeFleetMachines } from './fleet-targets.mjs';
 import { delegatedWork, idleInterval } from './session-work.mjs';
 import { localSessionDelegations } from '../agents.mjs';
-import { creatorOf, sessionProgress } from './workflow.mjs';
+import { cardSectionHeading, creatorOf, sessionProgress } from './workflow.mjs';
 import { boardLabel, boardName } from '@volter/teams/board-name';
 let fleetRoot = null;
 import { inspectCompletionEvidence, noCodeChange, openReviewPullRequests, reviewDue, withCompletionEvidence, withFreshReviewReads, reviewCandidate, workflowRevision, retainWorkflowTick } from './ci.mjs';
@@ -51,7 +51,7 @@ import { homedir, hostname, tmpdir, totalmem } from 'node:os';
 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, pendingLaunches, sessionBound, setActor, storageFault, tx } from './store.mjs';
+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 { checkWorkspace, assertWorkspaceOwner, notePresence, resolveWorkspace } from './workspace.mjs';
 import { capacity, dispatched, executionHost, harnessDefaults, holdings } from './capacity.mjs';
@@ -830,7 +830,14 @@ async function homeHoldings(root, slugs, lanes, fleet, entry) {
   const out = [];
   for (const slug of slugs) {
     try {
-      const b = openBoard(root, slug);
+      // Capacity spans awaits. It needs its own committed snapshot, not the shared writer's total_changes counter:
+      // unrelated owner calls and delivery writes used to invalidate all three attempts at this read.
+      let b;
+      try { b = openBoardSnapshot(root, slug); }
+      catch (error) {
+        if (error.code !== 'board_read_by_owner') throw error;
+        b = openBoard(root, slug); // files/non-WAL backings retain their guarded optimistic read
+      }
       try {
         b.slug ??= slug; b.label ??= boardLabel(root, slug);
         // each run's session read before it is counted live or not (unknown stays unknown)
@@ -840,7 +847,7 @@ async function homeHoldings(root, slugs, lanes, fleet, entry) {
           runLaneOf: row => runLane(b.db, b, entry, getTask(b.db, row.id), lanes) }));
       }
       finally { b.close(); }
-    } catch (error) { if (error.capacityUnread) throw error; /* its own tick reports other board errors */ }
+    } catch (error) { error.capacityUnread = true; throw error; }
   }
   out.defaults = harnessDefaults(out);
   return out;
@@ -927,6 +934,9 @@ async function startCards(board, fleet, lanes, settings, report, entry, effects,
     if (task.subtask_of || task.current_run_id) continue;
     const state = scopeFor(task).card;
     if (state.archived || ['done', 'cancelled'].includes(state.status)) continue;
+    if (state.status === 'running' && completedWork(board.db, task.id)) {
+      waiting(task, 'work is complete; the board must select its independent review before another implementer run'); continue;
+    }
     if (state.detached) { waiting(task, `session belongs to ${state.detached.person}; verified adoption is required`); continue; }
     if (state.dispatch_hold) { waiting(task, 'dispatch held: an explicit start or verified adoption must release it'); continue; }
     if (workflow.run && state.paused) { waiting(task, `paused: ${state.paused.reason ?? 'manager pause'}`); continue; }
@@ -991,7 +1001,7 @@ async function startCards(board, fleet, lanes, settings, report, entry, effects,
         const refused = caps.admit(waitingEntries[i], scope, waitingEntries);
         if (refused) throw Object.assign(new Error(refused.why), { claimedElsewhere: true });
         assertWorkspaceOwner(db, task, checked);
-        if (checked) db.prepare('UPDATE supercode_cards SET workspace_root=? WHERE task_id=?').run(checked.mainRoot, task.id);
+        if (checked) db.prepare('UPDATE supercode_cards SET workspace_root=? WHERE task_id=?').run(checked.workspaceRoot, task.id);
         if (!task.assignee && plan.profile) {
           db.prepare('UPDATE tasks SET assignee = ? WHERE id = ?').run(plan.profile, task.id);
           event(db, task.id, 'assigned', { assignee: plan.profile, source: 'workflow role' });
@@ -1076,7 +1086,7 @@ async function launchAttempt(board, entry, id, lane, fleet, settings, runId) {
   const checked = await checkWorkspace(board, task);
   if (checked) runTx(board, id, runId, (db) => {
     assertWorkspaceOwner(db, task, checked);
-    db.prepare('UPDATE supercode_cards SET workspace_root=? WHERE task_id=?').run(checked.mainRoot, id);
+    db.prepare('UPDATE supercode_cards SET workspace_root=? WHERE task_id=?').run(checked.workspaceRoot, id);
   });
   const status = view(board, (db) => statusOf(db, task));
   const spec = runSpec(entry, status, task);
@@ -1209,7 +1219,7 @@ export async function startCard(board, id, { roles = ['manager'], lanes, setting
   const moved = tx(board, (db) => {
     if (detachedCard(db, id)) throw new Error(`${id} is detached to a person; request and verify adoption before starting it`);
     assertWorkspaceOwner(db, before, checked);
-    if (checked) db.prepare('UPDATE supercode_cards SET workspace_root=? WHERE task_id=?').run(checked.mainRoot, id);
+    if (checked) db.prepare('UPDATE supercode_cards SET workspace_root=? WHERE task_id=?').run(checked.workspaceRoot, id);
     if (!roles.some(role => ['manager', 'creator'].includes(role))) throw new Error('Only the manager or creator starts a held card; request its decision.');
     event(db, id, 'dispatch_released', { reason: 'explicit start' });
     requestSessionClose(db,id);
@@ -1450,7 +1460,7 @@ export async function closeRequested(board, report, { taskId = null, caller = nu
         continue;
       }
     }
-    if (session?.monitor_held && !session.close_requested) continue; // only an explicit close action ends this process
+    if ((session?.monitor_held || session?.retain_after_run) && !session.close_requested) continue; // only an explicit close action ends this process
     if ((!session?.pane && session?.surface !== 'native') || session.close_transferred_to || session.close_confirmed_at || (!row.ended_at && !session.close_requested)) continue;
     if (caller && session.session_id === caller) continue; // let the command that ended its own run return
     // The board closes only what it launched. An adopted session (a person's own thread, a hook session the card was
@@ -1617,7 +1627,18 @@ async function observeIdle(board, fleet, settings, report, entry, effects) {
     return Number(rows?.find((row) => row.locator?.session_id === session.session_id)?.updated_at_ms) || null;
   };
   const managers = [].concat(entry.params.managers ?? []).filter(Boolean);
-  const delegations = localSessionDelegations(board.root, localMachine());
+  const running = board.db.prepare(entry.workflow.run ? "SELECT id FROM tasks WHERE current_run_id IS NOT NULL" : "SELECT id FROM tasks WHERE status = 'running'").all();
+  const edges = localSessionDelegations(board.root, localMachine());
+  const reached = new Set(running.map(({ id }) => addressOf(currentRun(board.db, id)?.metadata?.supercode)).filter(Boolean));
+  const delegations = [];
+  const pending = [...reached];
+  const byStarter = new Map();
+  for (const edge of edges) { const children = byStarter.get(edge.starter) ?? []; children.push(edge); byStarter.set(edge.starter, children); }
+  while (pending.length) for (const edge of byStarter.get(pending.pop()) ?? []) {
+    delegations.push(edge);
+    if (!reached.has(edge.session)) { reached.add(edge.session); pending.push(edge.session); }
+  }
+  report.idle_delegations = { recorded: edges.length, reachable: delegations.length };
   const delegatedReadings = [...fleet.sessions];
   // Forks and concurrent sessions need not have a pane. Read only the exact
   // native identities this home's starter receipts name, before any write.
@@ -1633,7 +1654,6 @@ async function observeIdle(board, fleet, settings, report, entry, effects) {
       if (row?.activity) delegatedReadings.push({ address, state: row.activity.presence, turn: row.activity.turn });
     } catch { /* an unread child is never called working */ }
   }
-  const running = board.db.prepare(entry.workflow.run ? "SELECT id FROM tasks WHERE current_run_id IS NOT NULL" : "SELECT id FROM tasks WHERE status = 'running'").all();
   // every running card a session is on: a session waiting on its user is told once, naming them all
   const cardsOf = new Map();
   for (const { id } of running) {
@@ -2284,6 +2304,10 @@ async function launchPane(board, task, runId, lane, fleet, { input = null, slot
   const pending = view(board, (db) => db.prepare('SELECT id, ended_at, metadata FROM task_runs WHERE task_id = ? AND id != ?').all(task.id, runId))
     .map((r) => ({ ...r, session: json(r.metadata, {})?.supercode }))
     .find((r) => (r.session?.pane || r.session?.launch_key || r.session?.surface === 'native') && !r.session.close_transferred_to && (r.session.slot ?? 'worker') === slot && (r.ended_at || r.session.close_requested) && !r.session.close_confirmed_at
+      // Deliberate retention owes no close. Only this slot's latest identity may reach the liveness/continuation
+      // checks below; an explicit close or another unresolved identity still holds the slot.
+      && !(r.session.retain_after_run && !r.session.close_requested && !r.session.forgotten && last?.session_id
+        && r.session.session_id === last.session_id && r.session.pane === last.pane && r.session.machine === machine && (r.session.harness ?? 'claude-code') === harness)
       && !(closeRefused(r.session) && last?.session_id && r.session.session_id === last.session_id));
   if (pending) throw unavailable(`slot ${slot} still owns pane ${pending.session.pane} from run ${pending.id}; closure must be confirmed before another session starts: ${pending.session.close_error ?? 'close pending'}`);
   let prev = view(board, (db) => lastSession(db, task.id, slot));
@@ -2431,13 +2455,14 @@ 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, idle_notice: _in, 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, review_held: _rh, ...kept } = prev;
+      const { missing_since: _m, goal_turns: _t, goal_nudged_at: _n, idle_since: _is, idle_notice: _in, 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, review_held: _rh, retain_after_run: _rr, ...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)
       tx(board, (db) => {
         if (!runCurrent(db, task.id, runId)) throw Object.assign(new Error(`run ${runId} of ${task.id} ended or was replaced while its session was read; nothing was told to it`), { launchSuperseded: true });
         setRunSession(db, runId, { ...session, ...meta });
+        transferRetainedSession(db, task.id, runId, session);
         // an earlier run's close of this pane is this run's now: the pane is the kept session's, not a close to retry
         if (prev.pane) for (const r of db.prepare('SELECT id, metadata FROM task_runs WHERE task_id = ? AND id != ?').all(task.id, runId)) {
           const s = json(r.metadata, {})?.supercode;
@@ -2506,6 +2531,7 @@ async function launchPane(board, task, runId, lane, fleet, { input = null, slot
     const saved = json(row?.metadata, {})?.supercode;
     if (saved?.address === session.address && !saved.launch_pending) return true;
     setRunSession(db, runId, session);
+    transferRetainedSession(db, task.id, runId, session);
     event(db, task.id, kind, { session_id: session.session_id, machine, pane: session.pane, address: session.address, mode: session.mode, ...(replaced ? { replaced } : {}) }, runId);
     // the working session hears updates to its card; the slot's previous session no longer does (a reviewer starting
     // leaves the implementer's, and a subtask's arc session's, subscription alone)
@@ -2520,6 +2546,19 @@ async function launchPane(board, task, runId, lane, fleet, { input = null, slot
   return session;
 }
 
+/** A continued role identity now belongs to its new attempt. Preserve the completed receipt, and keep an old
+ * retained reference from closing the same native process/pane later. Transfer only after a successful bind. */
+function transferRetainedSession(db, id, runId, session) {
+  if (!session?.session_id) return;
+  for (const row of db.prepare('SELECT id,metadata FROM task_runs WHERE task_id=? AND id<? AND ended_at IS NOT NULL').all(id, runId)) {
+    const old = json(row.metadata, {})?.supercode;
+    if (!old?.retain_after_run || old.close_requested || old.close_confirmed_at || old.close_transferred_to || old.forgotten
+      || old.session_id !== session.session_id || old.machine !== session.machine || (old.slot ?? 'worker') !== (session.slot ?? 'worker')) continue;
+    setRunSession(db, row.id, { close_transferred_to: runId });
+    event(db, id, 'session_transferred', { successor: runId, session_id: old.session_id, pane: old.pane ?? null }, row.id);
+  }
+}
+
 /** The agent a slot's last session belongs to, when it is not the agent this run's `meta` names: the agent store's
  *  owner of the session where it records one in this run's org, else the agent its own run ran as. Null when it is
  *  this run's agent, or no agent is known for it (a session from before card agents). */
@@ -2816,8 +2855,10 @@ async function adoptSession(board, id, who, { request = null, open = request, pr
   // agent store another, and every round after would trip on it.
   const owner = agent ? agentRunForSession(board.root, [`${harness}:${sessionId}`]) : null;
   if (owner && owner.agent_id !== agent.identity.id) throw new Error(`${found.address} already works for agent ${owner.agent_id} (run ${owner.run_id}); it cannot be adopted as ${agent.identity.id}`);
-  // the card's previous session is read before the bind decides whether it is still live
-  await readBefore(fleet, view(board, (db) => lastSession(db, id)));
+  // Each role owns its own slot. A retained worker does not prevent binding the independent reviewer; only this
+  // adoption's slot can conflict with the incoming identity. Independence still reads worker history below.
+  const adoptionSlot = beforeSession?.slot ?? runSpec(entry0, view(board, db => statusOf(db, card0)), card0)?.session ?? 'worker';
+  await readBefore(fleet, view(board, (db) => lastSession(db, id, adoptionSlot)));
   const adopted = tx(board, (db) => {
     const task = getTask(db, id);
     if (!task) throw new Error(`no card ${id}`);
@@ -2826,7 +2867,7 @@ async function adoptSession(board, id, who, { request = null, open = request, pr
     if (changed) throw changed;
     if (beforeRun && assignee && assignee !== task.assignee) throw new Error('rebinding a session does not reassign its active run');
     if (task.machine && normalMachine(task.machine) !== host) throw new Error(`${id} runs on ${task.machine}, and ${found.address} is on ${host}; move the card first`);
-    const was = lastSession(db, id);
+    const was = lastSession(db, id, adoptionSlot);
     // a session whose close the board confirmed is not live, whatever a fleet reading still lists (a released one was
     // left running, and is read)
     if (was && was.session_id !== sessionId && !(was.close_confirmed_at && !was.released) && sessionAlive(fleet, was)) throw new Error(`${id} already has a live session, ${was.address}`);
@@ -3526,14 +3567,37 @@ export async function plan({ root, lanes, settings, slugs = null, params = {} })
   return out;
 }
 
+/** An explicit completion of the latest attempt, after any previous review or reopening. A reclaimed or failed
+ * attempt is not a completed disposition, and a new attempt or returned verdict invalidates the old receipt. */
+function completedWork(db, id) {
+  const last = db.prepare(`SELECT id,kind,run_id FROM task_events WHERE task_id=?
+    AND kind IN ('work_completed','review_requested','changes_requested','review_pass','review_voided','reopened')
+    ORDER BY id DESC LIMIT 1`).get(id);
+  if (last?.kind !== 'work_completed') return null;
+  const attempt = db.prepare('SELECT id,outcome,ended_at FROM task_runs WHERE task_id=? ORDER BY id DESC LIMIT 1').get(id);
+  return attempt?.id === last.run_id && attempt.outcome === 'completed' && attempt.ended_at != null ? last : null;
+}
+
+/** Finish ends the attempt, not its caller's native turn. Keep observing that retained attempt until the board
+ * requests review; the receipt's lifecycle/latest-attempt fence prevents an older session holding later work. */
+function reviewTurnRun(db, id) {
+  const active = currentRun(db, id);
+  if (active) return active;
+  const completed = completedWork(db, id);
+  if (!completed || detachedCard(db, id)) return null;
+  const row = db.prepare('SELECT * FROM task_runs WHERE id=?').get(completed.run_id);
+  const metadata = json(row?.metadata, {}) ?? {}, session = metadata.supercode;
+  return row && session?.retain_after_run && !session.close_transferred_to && !detachedSession(db, session) ? { ...row, metadata } : null;
+}
+
 /** Whether an arc with no open PR may be one that changed no code and is due its review: it has done work, by filing
- *  tasks or by a run that ended with an Acceptance outcome ticked (a fresh arc with neither has not started), and no
+ *  tasks, an explicit completed-work receipt, or a completed run with an Acceptance outcome ticked, and no
  *  review of it is pending or passed (after changes are requested, closing the tasks that own the findings makes it
  *  due again). */
 function noCodeReviewDue(board, id) {
   return view(board, (db) => {
     const filed = db.prepare('SELECT 1 FROM supercode_cards WHERE subtask_of = ? LIMIT 1').get(id);
-    if (!filed && !(db.prepare('SELECT 1 FROM task_runs WHERE task_id = ? AND ended_at IS NOT NULL LIMIT 1').get(id) &&
+    if (!filed && !completedWork(db, id) && !(db.prepare("SELECT 1 FROM task_runs WHERE task_id = ? AND outcome = 'completed' AND ended_at IS NOT NULL LIMIT 1").get(id) &&
       outcomeTicked(db.prepare('SELECT body FROM tasks WHERE id = ?').get(id)?.body))) return false;
     const last = db.prepare("SELECT kind FROM task_events WHERE task_id = ? AND kind IN ('review_requested', 'changes_requested', 'review_pass','review_voided') ORDER BY id DESC LIMIT 1").get(id);
     return !last || ['changes_requested','review_voided'].includes(last.kind);
@@ -3549,8 +3613,8 @@ function passedReview(board, id) {
 function outcomeTicked(body) {
   let acceptance = false;
   return String(body ?? '').split('\n').some((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';
     return acceptance && /^\s*[-*] \[[xX]\] \S/.test(line);
   });
 }
@@ -3571,7 +3635,7 @@ function outcomeTicked(body) {
  *  running a proof, still holds the review. */
 async function turnInFlight(board, id, fleet, heldSince = null) {
   if (!fleet?.ok) return null;
-  const session = currentRun(board.db, id)?.metadata?.supercode;
+  const session = reviewTurnRun(board.db, id)?.metadata?.supercode;
   if (!session?.session_id || session.surface === 'headless' || session.close_requested) return null;
   let live = fleet.sessions?.find((x) => x.address === addressOf(session)) ?? null;
   if (live?.turn == null && session.surface === 'native') try {
@@ -3643,11 +3707,11 @@ async function activatePullRequestReviews(board, entry, report, effects, { only
       }
       // A native turn holds the advisory proposal before authoritative source reads. Retain the proposal on the run
       // (`review_held`) so a goal turn can be told to have started after that work was first observed.
-      const heldRun = currentRun(board.db, id), dueKey = reviewDueKey(board, id, payload);
+      const heldRun = reviewTurnRun(board.db, id), dueKey = reviewDueKey(board, id, payload);
       const held = heldRun?.metadata?.supercode?.review_held?.key === dueKey ? heldRun.metadata.supercode.review_held : null;
       const inTurn = await turnInFlight(board, id, fleet, held ? Number(held.since) : null);
       if (inTurn) {
-        if (!held && !dry && heldRun) tx(board, (db) => { if (currentRun(db, id)?.id === heldRun.id) setRunSession(db, heldRun.id, { review_held: { key: dueKey, since: now() } }); });
+        if (!held && !dry && heldRun) tx(board, (db) => { if (reviewTurnRun(db, id)?.id === heldRun.id) setRunSession(db, heldRun.id, { review_held: { key: dueKey, since: now() } }); });
         report.queued.push([id, `review waits: ${inTurn.why}`]);
         continue;
       }
@@ -3902,7 +3966,7 @@ export async function tick({ root, lanes, settings, only = null, slugs = null, d
       if (dispatch && !only && !report.paused) await observeIdle(board, fleet, settings, report, entry, effects);
       // what the moves asked for is recorded with them; the delivery pass (`deliver`) carries it out, outside the round
       queueEffects(board, effects);
-      phase('goals');
+      phase('idle');
       ensureSubscriptions(board, entry);
       fireHooks(board, settings, report);
       if (String(board.db.prepare('PRAGMA journal_mode').get()?.journal_mode).toLowerCase() === 'wal') board.db.prepare('PRAGMA wal_checkpoint(PASSIVE)').get();

package/board/engine.mjs

@@ -292,7 +292,7 @@ export function createCard(board, spec) {
     const handle = cardHandle(boardKey(board.root, board.slug), numberOf(db, id));
     if (namedBranch) run(db, 'UPDATE tasks SET branch_name = ? WHERE id = ?', handle ? namedBranch(handle) : `wt/${id}`, id);
     const machine = spec.machine ?? arc?.machine ?? null;
-    run(db, 'INSERT OR REPLACE INTO supercode_cards (task_id,machine,subtask_of,workspace_anchor,workspace_root,tags,requested_by_unverified) VALUES (?,?,?,?,?,?,?)', id, machine, arc?.id ?? null, declared.repository, checked?.mainRoot ?? null,
+    run(db, 'INSERT OR REPLACE INTO supercode_cards (task_id,machine,subtask_of,workspace_anchor,workspace_root,tags,requested_by_unverified) VALUES (?,?,?,?,?,?,?)', id, machine, arc?.id ?? null, declared.repository, checked?.workspaceRoot ?? null,
       tags.length ? JSON.stringify(tags) : null, spec.requestedByUnverified ? JSON.stringify(spec.requestedByUnverified) : null);
     for (const p of parents) addDependency(db, entry, id, p);
     // where it starts is the workflow's `initial` (Hermes: triage, blocked, todo behind open parents, else ready)
@@ -740,17 +740,26 @@ export const editResult = (board, id, { result, summary = null, metadata = undef
 export const heartbeat = (board, id, note = null, { roles, until = null } = {}) => act(board, id, 'heartbeat', { roles, payload: { note, until } });
 export const setGoal = (board, id, { on = true, maxTurns = null, roles } = {}) => act(board, id, 'set_goal', { roles, payload: { goal: Boolean(on), max_turns: on ? maxTurns : null } });
 
-/** A triage card fans out into children it waits on (Hermes's decomposer); answers their ids. */
+/** File the named card's tasks only if its workflow accepts decompose; refusal leaves no cards behind. */
 export async function decompose(board, id, children, { author = 'user', roles } = {}) {
   if (!children.length) throw new Error('decompose names at least one child (--child "<title>[@<assignee>]")');
-  const task = view(board, (db) => must(db, id));
-  const ids = [];
-  for (const c of children) ids.push(createCard(board, await prepareCard(board, {
-    title: c.title, body: c.body ?? null, assignee: c.assignee ?? task.assignee, machine: task.machine,
-    workspace: task.workspace_anchor ? `${task.workspace_kind}:${task.workspace_anchor}` : task.workspace_path ? `${task.workspace_kind}:${task.workspace_path}` : task.workspace_kind, tenant: task.tenant, createdBy: author,
-  })).id);
-  await act(board, id, 'decompose', { roles, payload: { children: ids, author } });
-  return ids;
+  const entry = await loadWorkflow(board.root);
+  await refreshCardInputs(board, id);
+  const result = tx(board, db => {
+    const task = must(db, id), sender = roles ?? callerRoles(db, id);
+    if (task.subtask_of) throw new Error(`${id} is itself a subtask of ${task.subtask_of}; decompose its arc instead`);
+    // Creation and authorization share this transaction. Guards see the actual child ids, and any refusal
+    // (including a later child's invalid spec) rolls back every child, event, subscription and queued effect.
+    const ids = children.map(c => createCard(board, {
+      title: c.title, body: c.body ?? null, assignee: c.assignee ?? task.assignee, machine: task.machine,
+      subtaskOf: id, workspace: 'scratch', tenant: task.tenant, createdBy: author,
+    }).id);
+    const move = fire(db, board, entry, id, 'decompose', { roles: sender, payload: { children: ids, author } });
+    for (const child of ids) settle(db, board, entry, child, move.effects);
+    return { ids, effects: move.effects };
+  });
+  await runEffects(board, result.effects);
+  return result.ids;
 }
 
 /** `child` waits for `parent`. */

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) {

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/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

package/orchestration.mjs

@@ -28,6 +28,7 @@ import { fileURLToPath } from 'node:url';
 import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
 import { emptyRuntime, persistedView } from './ir.mjs';
 import { lockedNative } from './source-lock.mjs';
+import { SESSION_READ_REQUEST_UNITS, stringifySessionWire } from '@volter/supercode-teams/session-read-client';
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -150,7 +151,7 @@ export async function load(root) {
   const { orchestration, vault_keys } = await through((d) => d.orchestrationLoad({ root }));
   let vault = readVault(orchestration);
   if (vault_keys.some((k) => !vault.has(k))) {
-    await through((d) => d.orchestrationSave({ root, orchestration, preserve_workflow: true }));
+    await save(stateOf(orchestration), root);
     vault = readVault(orchestration);
     const missing = vault_keys.filter((k) => !vault.has(k));
     if (missing.length) throw new Error(`${root}: ${missing.join(', ')} referenced but not in .env after normalization`);
@@ -172,10 +173,36 @@ export async function read(root) {
  * written as the home last held it, or left out when it held none, and none refuses the rest of the save.
  */
 export async function save(state, root = state.root) {
-  const saved = await through((d) => d.orchestrationSave({ root, orchestration: persistedView(state), preserve_workflow: true }));
+  const params = boundedRuntimeSave(state, root);
+  const saved = await through((d) => d.orchestrationSave(params));
+  // Apply retention in memory only after the owning door accepted it.
+  for (const [name, profile] of Object.entries(params.orchestration.profiles)) state.profiles[name].fires = profile.fires;
   return { rejected: Array.isArray(saved?.rejected) ? saved.rejected : [] };
 }
 
+// A per-profile row count cannot bound the whole home's request. Keep active fires and all configuration, and
+// remove the oldest terminal history across profiles until the actual native wire value fits, with envelope room.
+export function boundedRuntimeSave(state, root = state.root) {
+  const orchestration = { ...persistedView(state), profiles: Object.fromEntries(Object.entries(state.profiles).map(([name, profile]) => [name, { ...profile, fires: [...profile.fires] }])) };
+  const params = { root, orchestration, preserve_workflow: true };
+  const budget = SESSION_READ_REQUEST_UNITS - 16 * 1024;
+  let units = Buffer.byteLength(stringifySessionWire(params));
+  if (units <= budget) return params;
+  const terminal = Object.entries(orchestration.profiles).flatMap(([name, profile]) => profile.fires
+    .filter(fire => !['claimed', 'running'].includes(fire.status)).map(fire => ({ name, fire })));
+  terminal.sort((a, b) => String(a.fire.claimed_at ?? '').localeCompare(String(b.fire.claimed_at ?? '')) || String(a.fire.id).localeCompare(String(b.fire.id)));
+  const drop = new Set();
+  for (const { fire } of terminal) {
+    if (units <= budget) break;
+    drop.add(fire);
+    units -= Buffer.byteLength(stringifySessionWire(fire)) + 1;
+  }
+  for (const profile of Object.values(orchestration.profiles)) profile.fires = profile.fires.filter(fire => !drop.has(fire));
+  const actual = Buffer.byteLength(stringifySessionWire(params));
+  if (actual > budget) throw new Error(`orchestrator runtime save needs ${actual} bytes after terminal-history retention (limit ${budget}); configuration and active jobs were preserved; no execution was started`);
+  return params;
+}
+
 /** Another harness's home as a state value (no secret value; `vault_keys` names the `.env` keys it would need). */
 export async function compile(from, home) {
   const { orchestration, vault_keys } = await through((d) => d.orchestrationCompile({ from, home }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.211",
+  "version": "0.5.212",
   "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": {
@@ -32,7 +32,7 @@
     "check-types": "node scripts/generate-types.mjs --check"
   },
   "dependencies": {
-    "@volter/supercode-teams": "^0.3.346",
+    "@volter/supercode-teams": "^0.3.347",
     "@volter/supercode-terminal": "^0.3.10",
     "@volter/supercode-harness-sdk": "^0.3.104",
     "@volter/teams": "0.2.99",
@@ -61,6 +61,5 @@
     "board",
     "apply",
     "README.md"
-  ],
-  "gitHead": "38f4a38369c31949d4d81fd3520a6aa678582ead"
+  ]
 }