@volter/supercode-orchestrator 0.5.210 → 0.5.212

package/README.md

@@ -19,6 +19,16 @@ stage's own transition, which ends the run in the default workflow. See the
 [private manual reading](../../docs/evidence/board-manual-claim-2026-10-09.md)
 for scope and limits; existing inconsistent claims are not repaired automatically.
 
+Completing a task with `--commit` inherits its arc's workspace when the task is
+scratch. When that workspace belongs to another machine, the board verifies the
+commit against the declared repository's pushed branch head through GitHub,
+without requiring the checkout on the board host. A legacy directory path is
+resolved through its own machine's workspace door to obtain that identity.
+Remote commits take a full SHA or at least seven hexadecimal characters; a
+different head or an unread remote refuses completion. Local checkouts keep
+their existing Git commit resolution. This source check does not replace the
+arc's independent review.
+
 The orchestrator's runtime over the ontology: one typed operational model
 (`OrchestratorState` = an orchestration value plus a runtime half) whose folder is its serialization.
 `docs/ORCHESTRATOR-IR.md` is normative. The orchestration value and every codec are the ontology's, in
@@ -125,7 +135,11 @@ redacted refusal even when a failed call is fast. See
 Board discovery caches advisory reads while waiting. Review requests, verdicts
 and acceptance refresh the complete source set, including previously draft or
 closed declared sources, and validate its current heads. An unread set defers
-the action. Unread commit dates also defer eligibility and are never cached as
+the action. Before the dispatcher spends those validation reads, it checks the
+advisory candidate against its local worktrees. A mismatched HEAD or uncommitted
+work refuses that attempt locally. Each later round rechecks the checkout, so
+a repair wakes it; a successful preflight still needs the fresh complete-source,
+local and pushed-head checks before review is recorded. Unread commit dates also defer eligibility and are never cached as
 old work. Merge validation still reads the current head. Every request page, retry, redirect and merge PUT
 reserves its own attempt. All processes and credentials sharing this supercode
 home share a rolling-hour ceiling of 1,200 attempts, including at most 600

package/agents.mjs

@@ -232,8 +232,17 @@ export function localAgentRecord(root,org,id){
 /** Rename only identities this card role declared; a reassigned standing agent keeps its own name. */
 export function renameCardAgent(root, assignment, readableId) {
   const intent=agentIntent(root,assignment.org,assignment.agent_id);
-  if(!intent?.declaration_json)return false;
-  const declaration=JSON.parse(intent.declaration_json);
+  if(!intent||assignment.state!=='active')return false;
+  let declaration=intent.declaration_json?JSON.parse(intent.declaration_json):null;
+  if(!declaration){
+    // Older declared intents kept only their stable key. Recover this role's own current identity, never an agent
+    // reassigned from another card or a standing profile. The existing Teams identity keeps its lineage and sessions.
+    const suffix=`/card/${assignment.target}/${assignment.role}`,base=intent.key.replace(/\/generation\/\d+$/,'');
+    if(!base.endsWith(suffix)||declarationHead(root,assignment.org,base)!==assignment.agent_id)return false;
+    const parent=declarationHead(root,assignment.org,`${base.slice(0,-suffix.length)}/root`);
+    if(!parent)return false;
+    declaration={kind:'card',card:assignment.target,role:assignment.role,profile:intent.profile_ref,parent};
+  }
   if(declaration.kind!=='card'||declaration.card!==assignment.target||declaration.role!==assignment.role)return false;
   const name=`${assignment.role}-${readableId}`;
   if(declaration.name===name&&declaration.readableId===readableId)return false;

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/agent-declarations.mjs

@@ -1,7 +1,7 @@
 // Consume the card-creation intent after the board transaction; retries reuse the daemon-minted id. The card's agent is
 // minted and recorded here, and its declaration handed to this machine's daemon, which declares it in Teams: whoever ran
 // the effect (the creating command, or a delivery pass retrying it) makes no Teams call (D137).
-import { agentScope, localCardAgent, finishAgentAssignment, cardAgentAssignments, cardAgentScopeTransition, pendingCardAgentChanges, acknowledgeCardAgentChanges, handOffAgents } from '../agents.mjs';
+import { agentScope, localCardAgent, renameCardAgent, finishAgentAssignment, cardAgentAssignments, cardAgentScopeTransition, pendingCardAgentChanges, acknowledgeCardAgentChanges, handOffAgents } from '../agents.mjs';
 import { cardHandleOf, readableIdOf, event, json, tx, view } from './store.mjs';
 import { workflowFor } from './workflow.mjs';
 import { cardAgentFacts, cardAgentReceiptRecorded, syncCardAgentScope } from './published.mjs';
@@ -47,6 +47,23 @@ export async function declareCardAgentEffect(board,effect) {
   }
 }
 
+/** A readable-id edit carries every live role's retained declaration through the existing machine identity door.
+ * No assignment is created or revived here; an ended or reassigned agent keeps its own identity and history. */
+export async function renameCardAgentsEffect(board,effect) {
+  const task=view(board,db=>db.prepare('SELECT t.readable_id,t.status,c.subtask_of,c.archived FROM tasks t JOIN supercode_cards c ON c.task_id=t.id WHERE t.id=?').get(effect.id));
+  if(!task?.readable_id||task.subtask_of||task.archived||['done','cancelled','archived'].includes(task.status))return true;
+  const agents=new Set();
+  for(const assignment of cardAgentAssignments(board.root,effect.id)) {
+    if(assignment.state!=='active'||!admitsScope(board,effect.id,assignment.org))continue;
+    renameCardAgent(board.root,assignment,task.readable_id);
+    agents.add(assignment.agent_id);
+  }
+  if(!agents.size)return true;
+  const pending=(await handOffAgents(board.root)).filter(item=>item.agent==='*'||agents.has(item.agent));
+  if(pending.length)throw new Error(pending.map(item=>item.error).join('; '));
+  return true;
+}
+
 /** A failed board write leaves the owner's receipt pending. A failed acknowledgement repeats no board event. */
 export function recordCardAgentChanges(board,target){
   const changes=pendingCardAgentChanges(board.root,target);

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/call.mjs

@@ -15,6 +15,7 @@
 //              a connection of its own (store.mjs openBoard), and nothing is written
 import { readFileSync } from 'node:fs';
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { withCredentialGuard } from './credential-guard.mjs';
 
 const calls = new AsyncLocalStorage();
 // what a call learns as it runs, and the workflow it read (pinned: a reload while it runs does not change its basis)
@@ -34,7 +35,7 @@ export function within({ caller = null, facts = {}, cwd, stdin = null, out, err,
 /** Run `fn` as a unit of the process's own work (a round, a delivery pass): the process's identity and output, with
  *  what it learns and the workflow it read kept to itself. */
 export function ownCall(fn) {
-  return calls.run({ kind: 'own', caller: null, facts: process.env, ...fresh(), get cwd() { return process.cwd(); }, stdin: null, out: own.out, err: own.err }, fn);
+  return withCredentialGuard(() => calls.run({ kind: 'own', caller: null, facts: process.env, ...fresh(), get cwd() { return process.cwd(); }, stdin: null, out: own.out, err: own.err }, fn));
 }
 
 /** The caller as its address names it, or null. */

package/board/capacity.mjs

@@ -89,50 +89,63 @@ export async function holdings(board, options) {
  */
 async function readHoldings(board, { lanes, fleetOk, alive, liveRecord, modelOf = () => null, storedOf = null, machineOf, home = null, runLaneOf = null }, unchanged) {
   const out = [];
-  const rows = board.db.prepare("SELECT t.id, t.status, t.assignee, t.current_run_id, t.model_override, c.machine, c.subtask_of FROM tasks t LEFT JOIN supercode_cards c ON c.task_id = t.id WHERE t.status != 'archived' AND c.detached IS NULL").all();
-  for (const row of rows) {
+  let cursor = '';
+  const high = board.db.prepare('SELECT MAX(id) AS id FROM tasks').get()?.id ?? '';
+  for (;;) {
     await yieldToOwner();
     if (!unchanged()) return null;
-    const lane = lanes[row.assignee] ?? {};
-    const card = {
-      card: row.id, board: board.slug, assignee: row.assignee ?? null, status: statusOf(board.db, row),
-      // what the board stores for an arc is read through its workflow's stored_as rules now, never the column a write has
-      // not yet brought up to date (a paused card counted as running until its row caught up)
-      stored: !row.subtask_of && storedOf ? storedOf(row.id) : row.status,
-      // a card that names no machine runs on this home's: a cap on this machine counts it
-      machine: row.machine ? machineOf(row.machine) : home,
-      model: row.model_override ?? lane.model ?? null, harness: lane.harness ?? null,
-    };
-    // a session's model: what its transcript reports, else what its launch resolved, else the card's
-    const sessionOf = (s, slot) => {
-      const configured = s.model ?? card.model;
-      return { ...card, counts: 'sessions', slot, session: s.session_id ?? null, unconfigured: !configured,
-        dispatch: dispatched(s), run: s.run ?? null,
-        machine: s.surface === 'headless' ? home : s.machine || s.surface ? machineOf(s.machine ?? row.machine ?? home)
-          : executionHost(runLaneOf ? runLaneOf(row) : lane, row.machine, home, machineOf), harness: s.harness ?? card.harness ?? 'claude-code',
-        model: (s.session_id ? modelOf(s) : null) ?? configured };
-    };
-    const sessions = fleetOk ? await sessionsOf(board.db, row.id, unchanged) : new Map();
-    if (sessions === null) return null;
-    const held = [];
-    let current = null;
-    if (row.current_run_id) {
-      current = { ...json(board.db.prepare('SELECT metadata FROM task_runs WHERE id = ?').get(row.current_run_id)?.metadata, {})?.supercode, run: row.current_run_id };
-      out.push({ ...sessionOf(current, current.slot ?? 'worker'), session: undefined, slot: undefined, counts: 'runs' });
-    }
-    for (const [slot, s] of sessions) {
-      if (!alive(s)) continue;
-      const session = sessionOf(s, slot);
-      held.push(session);
-      if (IN_TURN.has(liveRecord(s)?.status)) out.push({ ...session, counts: 'turns' });
+    // Limit candidates before filtering or joining: even a page containing only archived/detached cards is bounded.
+    const candidates = board.db.prepare('SELECT id FROM tasks WHERE id>? AND id<=? ORDER BY id LIMIT 32').all(cursor, high);
+    if (!candidates.length) break;
+    cursor = candidates.at(-1).id;
+    const rows = board.db.prepare(`SELECT t.id,t.status,t.assignee,t.current_run_id,t.model_override,c.machine,c.subtask_of
+      FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id
+      WHERE t.id IN (SELECT value FROM json_each(?)) AND t.status!='archived' AND c.detached IS NULL`)
+      .all(JSON.stringify(candidates.map(row => row.id)));
+    for (const row of rows) {
+      await yieldToOwner();
+      if (!unchanged()) return null;
+      const lane = lanes[row.assignee] ?? {};
+      const card = {
+        card: row.id, board: board.slug, assignee: row.assignee ?? null, status: statusOf(board.db, row),
+        // what the board stores for an arc is read through its workflow's stored_as rules now, never the column a write has
+        // not yet brought up to date (a paused card counted as running until its row caught up)
+        stored: !row.subtask_of && storedOf ? storedOf(row.id) : row.status,
+        // a card that names no machine runs on this home's: a cap on this machine counts it
+        machine: row.machine ? machineOf(row.machine) : home,
+        model: row.model_override ?? lane.model ?? null, harness: lane.harness ?? null,
+      };
+      // a session's model: what its transcript reports, else what its launch resolved, else the card's
+      const sessionOf = (s, slot) => {
+        const configured = s.model ?? card.model;
+        return { ...card, counts: 'sessions', slot, session: s.session_id ?? null, unconfigured: !configured,
+          dispatch: dispatched(s), run: s.run ?? null,
+          machine: s.surface === 'headless' ? home : s.machine || s.surface ? machineOf(s.machine ?? row.machine ?? home)
+            : executionHost(runLaneOf ? runLaneOf(row) : lane, row.machine, home, machineOf), harness: s.harness ?? card.harness ?? 'claude-code',
+          model: (s.session_id ? modelOf(s) : null) ?? configured };
+      };
+      const sessions = fleetOk ? await sessionsOf(board.db, row.id, unchanged) : new Map();
+      if (sessions === null) return null;
+      const held = [];
+      let current = null;
+      if (row.current_run_id) {
+        current = { ...json(board.db.prepare('SELECT metadata FROM task_runs WHERE id = ?').get(row.current_run_id)?.metadata, {})?.supercode, run: row.current_run_id };
+        out.push({ ...sessionOf(current, current.slot ?? 'worker'), session: undefined, slot: undefined, counts: 'runs' });
+      }
+      for (const [slot, s] of sessions) {
+        if (!alive(s)) continue;
+        const session = sessionOf(s, slot);
+        held.push(session);
+        if (IN_TURN.has(liveRecord(s)?.status)) out.push({ ...session, counts: 'turns' });
+      }
+      // a live run whose session the fleet does not list yet (launching) holds a session's place already
+      if (current && !held.some((x) => x.slot === (current.slot ?? 'worker'))) held.unshift(sessionOf(current, current.slot ?? 'worker'));
+      out.push(...held);
+      // the card itself, whatever its runs and sessions: a cap says which by its status (a started card holds its slot
+      // until it is done); its model and harness are its run's session's, else its newest live session's, else its own
+      // a subtask is a task of its arc: it never runs or holds a slot of its own
+      if (!row.subtask_of) out.push({ ...(held[0] ?? { ...card, unconfigured: !card.model }), session: undefined, slot: undefined, counts: 'cards' });
     }
-    // a live run whose session the fleet does not list yet (launching) holds a session's place already
-    if (current && !held.some((x) => x.slot === (current.slot ?? 'worker'))) held.unshift(sessionOf(current, current.slot ?? 'worker'));
-    out.push(...held);
-    // the card itself, whatever its runs and sessions: a cap says which by its status (a started card holds its slot
-    // until it is done); its model and harness are its run's session's, else its newest live session's, else its own
-    // a subtask is a task of its arc: it never runs or holds a slot of its own
-    if (!row.subtask_of) out.push({ ...(held[0] ?? { ...card, unconfigured: !card.model }), session: undefined, slot: undefined, counts: 'cards' });
   }
   return out;
 }

package/board/ci.mjs

@@ -291,13 +291,15 @@ async function repositoryWorkspace(board, id) {
   // the worktree's folder, when it is still to be made, is named for its card (workspace.mjs worktreeFolder)
   const workspace = { ...owner, handle: cardHandleOf(board, owner.id) };
   const here = isLocalWorkspace(workspace);
+  if (!here) {
+    const identity = workspace.workspace_anchor ?? workspace.workspace_path;
+    if (!identity) return null;
+    // A portable remote declaration supplies the source identity. Legacy paths
+    // are resolved by their own machine, never read as paths on the board host.
+    const resolved = plainWorkspace(workspace.workspace_kind, identity, workspace.branch_name) ?? await resolveWorkspace(workspace, false);
+    return { ...resolved, branch: workspace.branch_name ?? resolved.branch, here: false };
+  }
   if (workspace.workspace_anchor) {
-    // A portable remote declaration supplies the source identity. Reviewing
-    // its pushed head does not require that machine to keep the old checkout.
-    if (!here) {
-      const declared = plainWorkspace(workspace.workspace_kind, workspace.workspace_anchor, workspace.branch_name);
-      if (declared) return { ...declared, here: false };
-    }
     const resolved = await resolveWorkspace(workspace, false);
     // Resolution without create names a solo worktree even before it exists on
     // this machine. Its portable repository and branch still identify the
@@ -305,7 +307,24 @@ async function repositoryWorkspace(board, id) {
     if (here && !checkoutPresent(resolved.path)) return { ...resolved, here: await recreatedWorktree(workspace, resolved) };
     return { ...resolved, here };
   }
-  return workspace.workspace_path ? { path: workspace.workspace_path, here: here && checkoutPresent(workspace.workspace_path) } : null;
+  return workspace.workspace_path ? { path: workspace.workspace_path, here: checkoutPresent(workspace.workspace_path) } : null;
+}
+
+/** A supplied completion commit belongs to the workspace's machine. Local Git
+ *  keeps its existing semantics; a remote declaration is read at its pushed head. */
+async function completionSource(workspace, supplied) {
+  if (workspace?.here && workspace.path) {
+    return { repository: await originOf(workspace.path), commit: await run('git', ['rev-parse', '--verify', `${supplied}^{commit}`], workspace.path) };
+  }
+  if (!workspace?.repository || !workspace.branch) throw new Error('The named commit needs a declared repository and branch, resolved through the workspace machine when only a path is recorded.');
+  if (typeof supplied !== 'string' || !/^[a-f0-9]{7,40}$/i.test(supplied)) throw new Error('Name the remote completion commit with its full SHA or an abbreviation of at least seven hexadecimal characters.');
+  // Read the declared branch, not an arbitrary commit that merely exists in
+  // the repository. No checkout or daemon upgrade on the board host is needed.
+  const pushed = await github(`/repos/${workspace.repository}/git/ref/heads/${encodeURIComponent(workspace.branch)}`);
+  const head = pushed?.object?.type === 'commit' ? pushed.object.sha : null;
+  if (typeof head !== 'string' || !/^[a-f0-9]{40}$/.test(head)) throw new Error(`The declared remote ${workspace.repository}:${workspace.branch} answered no commit head.`);
+  if (!head.startsWith(supplied.toLowerCase())) throw new Error(`The named commit ${supplied} must be the pushed head of ${workspace.repository}:${workspace.branch}, currently ${head}.`);
+  return { repository: workspace.repository, branch: workspace.branch, commit: head, source_sha: head };
 }
 
 /** A card's declared solo worktree that is missing here (deleted, or never made on this machine) while its branch is on
@@ -383,7 +402,7 @@ function registeredBranches(board, id) {
  *  declaration (engine.comment), the arc's complete set. A multi-repository arc carries them on the arc card, and its
  *  review discovers and accepts PRs from them with no subtask registered in that repository (VO-2858, VO-2860). */
 export function arcSources(db, id) {
-  const row = db.prepare("SELECT payload FROM task_events WHERE task_id=? AND kind='commented' AND json_type(payload,'$.branches')='array' ORDER BY id DESC LIMIT 1").get(id);
+  const row = db.prepare("SELECT payload FROM task_events WHERE task_id=? AND kind='commented' AND json_valid(payload) AND json_type(payload,'$.branches')='array' ORDER BY id DESC LIMIT 1").get(id);
   let declared = [];
   try { declared = row ? JSON.parse(row.payload).branches : []; } catch { /* an unreadable declaration names none */ }
   return declared.filter((b) => typeof b?.repository === 'string' && typeof b?.branch === 'string').map((b) => ({ repository: b.repository, branch: b.branch }));
@@ -396,8 +415,9 @@ export const namedWorkBranch = (id, head) => [`wt/${id}`, `wt/${id.replace(/^t_/
 /** The branch names an arc declares as its work: its own and its subtasks' `--branch`, the branches it declares as its
  *  sources (arcSources), and each branch its latest review request covered. With `namedWorkBranch`, these are the branches its PRs are opened from. */
 export function declaredWorkBranches(db, id) {
-  const declared = db.prepare(`SELECT t.branch_name FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id
-    WHERE (t.id=? OR c.subtask_of=?) AND t.status != 'cancelled' AND t.branch_name IS NOT NULL`).all(id, id).map((r) => r.branch_name);
+  const declared = db.prepare(`SELECT branch_name FROM tasks WHERE id=? AND status!='cancelled' AND branch_name IS NOT NULL
+    UNION SELECT t.branch_name FROM supercode_cards c CROSS JOIN tasks t ON t.id=c.task_id
+    WHERE c.subtask_of=? AND t.status!='cancelled' AND t.branch_name IS NOT NULL`).all(id, id).map((r) => r.branch_name);
   declared.push(...arcSources(db, id).map((b) => b.branch));
   const row = db.prepare("SELECT payload FROM task_events WHERE task_id=? AND kind='review_requested' ORDER BY id DESC LIMIT 1").get(id);
   let reviewed = [];
@@ -410,7 +430,7 @@ export function declaredWorkBranches(db, id) {
  *  of, or a sibling checkout the arc registered (`registeredBranches`). The repository's default branch, declared or
  *  checked out (or no branch), is not a work branch: such a card's PRs are only its `wt/<card>` and registered ones, and with none it
  *  answers `{ waits }` saying so. One review covers them all; the caller decides the transition. */
-export async function openReviewPullRequests(board, id, { fresh = false } = {}) {
+export async function openReviewPullRequests(board, id, { fresh = false, checkWorkspaces = false } = {}) {
   const own = await repositoryWorkspace(board, id);
   const registered = registeredBranches(board, id);
   if (!own && !registered.length) return null;
@@ -450,7 +470,7 @@ export async function openReviewPullRequests(board, id, { fresh = false } = {})
       if (branch === list.defaultBranch) branch = null;
     }
     // a draft is not handed over yet: its review starts when it is marked ready; a PR to another base (main→prod) is a release, not the arc's work
-    for (const pr of list.items) if (!pr.isCrossRepository && !pr.isDraft && pr.baseRefName === pr.defaultBranch && mine(repository, pr.headRefName)) prs.push({ url: pr.url, head: pr.headRefOid });
+    for (const pr of list.items) if (!pr.isCrossRepository && !pr.isDraft && pr.baseRefName === pr.defaultBranch && mine(repository, pr.headRefName)) prs.push({ url: pr.url, head: pr.headRefOid, observed: pr });
     // A manual review and merge during a dispatcher outage may predate any
     // board request. The source-review door already accepts merged heads; make
     // them discoverable so the ordinary independent verdict can be retained.
@@ -467,7 +487,7 @@ export async function openReviewPullRequests(board, id, { fresh = false } = {})
         && pr.baseRefName === pr.defaultBranch && (answered || !judgedHead(board, id, pr.headRefOid)));
     });
     for (const history of histories) for (const pr of history) {
-      if (!prs.some(known => known.url === pr.url)) prs.push({ url: pr.url, head: pr.headRefOid });
+      if (!prs.some(known => known.url === pr.url)) prs.push({ url: pr.url, head: pr.headRefOid, observed: pr });
     }
     return prs;
   });
@@ -481,9 +501,13 @@ export async function openReviewPullRequests(board, id, { fresh = false } = {})
   const sources = (declaration ? JSON.parse(declaration.payload).sources : []).filter(source => repositories.has(repositoryOf(source.url).toLowerCase()) && !prs.some(known => known.url === source.url));
   for (const pr of await readTogether(sources, source => fresh ? readPullRequest(source.url) : discoverPullRequest(source.url))) {
     if (pr.isCrossRepository || !['OPEN', 'MERGED'].includes(pr.state) || (pr.state === 'OPEN' && pr.isDraft)) continue;
-    if (!prs.some((known) => known.url === pr.url)) prs.push({ url: pr.url, head: pr.headRefOid });
+    if (!prs.some((known) => known.url === pr.url)) prs.push({ url: pr.url, head: pr.headRefOid, observed: pr });
   }
   if (!prs.length) return branch || !ownRepository ? null : { waits: `the card has no work branch (${task?.branch_name ? `it declares ${task.branch_name}, its repository's default` : current ? `its checkout ${own.path} is on ${current}, its repository's default` : `its checkout ${own.path} is on no branch`}): give it one with --branch, or open its PR from a wt/${id} branch` };
+  // Advisory facts can refuse an attempt before its authoritative REST scan. Recheck the local checkout each
+  // round, so a repaired HEAD or clean worktree wakes it without caching the refusal. This is never evidence
+  // for a transition: verifyPullRequest repeats the checks against fresh metadata and the pushed head below.
+  if (checkWorkspaces) await readTogether(prs, pr => requireReviewWorkspaceHead(board, id, own, pr.observed, pr.head));
   return { pr: prs.map((p) => p.url), pr_head: prs.map((p) => p.head), branch };
 }
 
@@ -636,9 +660,7 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
     if (stage === 'completion' || stage === 'acceptance') {
       const supplied = payload.commit ?? payload.metadata?.commit;
       if (supplied) {
-        const path = (await repositoryWorkspace(board, id))?.path;
-        if (!path) throw new Error('The named commit needs a resolved repository workspace.');
-        Object.assign(state, { repository: await originOf(path), commit: await run('git', ['rev-parse', '--verify', `${supplied}^{commit}`], path) });
+        Object.assign(state, await completionSource(await repositoryWorkspace(board, id), supplied));
       }
       const candidate = stage === 'acceptance' ? reviewCandidate(board, id) : null;
       if (candidate) {
@@ -712,14 +734,28 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
   return state;
 }
 
-/** One PR of an arc review, read from GitHub and, for a review request, from the card branch's checkout. */
-async function verifyPullRequest(board, id, entry, own, url, supplied, stage, observed) {
-  if (typeof url !== 'string' || !/^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/[1-9][0-9]*\/?$/.test(url)) throw new Error('Name the opened PR URL with --pr.');
-  const repository = new URL(url).pathname.split('/').slice(1, 3).join('/');
+/** Local review readiness, also usable with advisory metadata to refuse before spending REST admission. */
+async function requireReviewWorkspaceHead(board, id, own, observed, head, { pushed = false } = {}) {
+  const url = observed.url, repository = repositoryOf(url), branch = observed.headRefName;
   // An arc may change several repositories. A PR is read from GitHub; its pushed head is the reviewed one. The
   // card's own checkout, and this machine's checkout of the PR's branch when it keeps one, must also hold that head
   // with nothing uncommitted. A card on another machine is reviewed at its pushed head: its checkout is not read from here.
   const path = observed.state === 'MERGED' || (own && !own.here) ? null : !own ? await branchCheckout(board, id, repository, observed.headRefName) : await originOf(own.path) === repository && await run('git', ['branch', '--show-current'], own.path) === observed.headRefName ? own.path : await branchCheckout(board, id, repository, observed.headRefName);
+  if (!path) return;
+  await run('git', ['check-ref-format', '--branch', branch], path);
+  if (await run('git', ['rev-parse', 'HEAD'], path) !== head) throw new Error(`The head named for ${url} must be its worktree head.`);
+  const uncommitted = (await run('git', ['status', '--porcelain', '--untracked-files=normal'], path)).split('\n').filter(Boolean);
+  if (uncommitted.length) throw new Error(`Commit the work in ${path} before requesting review: ${uncommitted.length} uncommitted path(s): ${uncommitted.slice(0, 5).map((l) => l.replace(/^\s*\S+\s+/, '')).join(', ')}${uncommitted.length > 5 ? ', …' : ''}`);
+  if (pushed) {
+    const remote = (await run('git', ['ls-remote', '--heads', 'origin', `refs/heads/${branch}`], path)).split(/\s+/)[0];
+    if (remote !== head) throw new Error(`Push the exact head of ${url} before requesting review.`);
+  }
+}
+
+/** One PR of an arc review, read from GitHub and, for a review request, from the card branch's checkout. */
+async function verifyPullRequest(board, id, entry, own, url, supplied, stage, observed) {
+  if (typeof url !== 'string' || !/^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/[1-9][0-9]*\/?$/.test(url)) throw new Error('Name the opened PR URL with --pr.');
+  const repository = new URL(url).pathname.split('/').slice(1, 3).join('/');
   // A PR merged before its review (an outage fix landed first) is still reviewed: its head is fixed for good, so the
   // verdict is recorded on that head, and nothing about a worktree or its base can move under it any more.
   const merged = observed.state === 'MERGED';
@@ -732,14 +768,7 @@ async function verifyPullRequest(board, id, entry, own, url, supplied, stage, ob
   const mainBranch = observed.defaultBranch ?? 'main';
   // A merged hotfix may have landed on another base (prod); a PR from the main branch itself is a release, never arc work.
   if (branch === mainBranch || (!merged && observed.baseRefName !== mainBranch)) throw new Error(`${url} must propose its worktree branch to the repository main branch.`);
-  if (stage === 'request_review' && path && !merged) {
-    await run('git', ['check-ref-format', '--branch', branch], path);
-    if (await run('git', ['rev-parse', 'HEAD'], path) !== head) throw new Error(`The head named for ${url} must be its worktree head.`);
-    const uncommitted = (await run('git', ['status', '--porcelain', '--untracked-files=normal'], path)).split('\n').filter(Boolean);
-    if (uncommitted.length) throw new Error(`Commit the work in ${path} before requesting review: ${uncommitted.length} uncommitted path(s): ${uncommitted.slice(0, 5).map((l) => l.replace(/^\s*\S+\s+/, '')).join(', ')}${uncommitted.length > 5 ? ', …' : ''}`);
-    const pushed = (await run('git', ['ls-remote', '--heads', 'origin', `refs/heads/${branch}`], path)).split(/\s+/)[0];
-    if (pushed !== head) throw new Error(`Push the exact head of ${url} before requesting review.`);
-  }
+  if (stage === 'request_review') await requireReviewWorkspaceHead(board, id, own, observed, head, { pushed: true });
   return { repository, branch, commit: head, source_sha: head, pr: { url: observed.url, number: observed.number, head, branch, base: observed.baseRefName } };
 }
 

package/board/cli.mjs

@@ -15,8 +15,9 @@ 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 { redactText } from '@volter/teams/redact';
+import { redactGuardText as redactText, withCredentialGuard } from './credential-guard.mjs';
 import { openOwnerDoor } from './owner-door.mjs';
 import { existsSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, copyFileSync, readFileSync, appendFileSync, writeFileSync } from 'node:fs';
 import { notRuntime, ownHome } from './owner-files.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';
@@ -1749,8 +1760,11 @@ async function answerVerbs(root, log) {
  * absence from a slow-only log cannot prove those calls met the time bound. */
 export async function answerOne(root, line, { readOnly = false } = {}) {
   const scoped = typeof slowLog.withStepScope === 'function';
+  // The owner's receipt includes asynchronous custody preparation too: it is part of the caller's wait.
+  const began = performance.now(), before = slowLog.processCounters?.() ?? null;
+  let prepared = false;
   const run = async () => {
-    const began = performance.now(), before = slowLog.processCounters?.() ?? null;
+    prepared = true;
     let named = null, by = null, answer = null, outcome = 'error';
     try {
       answer = await answerRequest(root, line, (verb, caller) => { named = verb; by = caller; }, { readOnly });
@@ -1769,7 +1783,23 @@ export async function answerOne(root, line, { readOnly = false } = {}) {
       }
     }
   };
-  return scoped ? slowLog.withStepScope(run) : run();
+  const guarded = async () => {
+    try { return await withCredentialGuard(run); }
+    catch (error) {
+      if (!prepared) {
+        const ended = performance.now(), ms = ended - began;
+        const code = error?.code === 'custody_unreadable' ? 'custody_unreadable' : 'custody_preparation_failed';
+        // No request, caller payload or error text is inspected before custody is available. Fixed metadata needs
+        // no redaction read and still records the failed preparation in this request's own step scope.
+        recordSlow({ kind: 'call', name: 'owner verb custody preparation', args: [], ms, outcome: code,
+          slowest: null, force: true, includeFast: true,
+          extra: { failure: { code, phase: 'custody preparation' }, step_scope: scoped ? 'request' : 'process_interval',
+            steps: scoped ? takeSteps() : slowLog.stepsWithin?.(began, ended) ?? null } });
+      }
+      throw error;
+    }
+  };
+  return scoped ? slowLog.withStepScope(guarded) : guarded();
 }
 
 /** One request answered in a call of its own; on the read door (`readOnly`) a listing only, and `{ byOwner: true }` for
@@ -1949,7 +1979,20 @@ async function serve(root, args = {}) {
   let listenerRecords = {}, listenerReloading = null, listenerReloadDue = false, listenerReading = null;
   const listenerErrors = new Set();
   const listenerLog = text => { if (!listenerErrors.has(text)) { if (listenerErrors.size >= 128) listenerErrors.clear(); listenerErrors.add(text); log(text); } };
-  const scanListeners = ({ waiting = true } = {}) => listenerBootstrapped && fleetRecordsCurrent() && ownCall(() => observeRoleFleet(root, fleetListeners, listenerRecords, listenerLog, { waiting }));
+  const scanListeners = async ({ waiting = true } = {}) => {
+    if (stopped || !fleetListeners.enabled || !listenerBootstrapped || !fleetRecordsCurrent()) return;
+    const revision = listenerRevision;
+    try {
+      await ownCall(() => {
+        if (stopped || revision !== listenerRevision || !fleetListeners.enabled || !fleetRecordsCurrent()) return;
+        observeRoleFleet(root, fleetListeners, listenerRecords, listenerLog, { waiting });
+      });
+    } catch {
+      // Every caller may schedule this without awaiting it. Preparation refusal leaves source cursors untouched;
+      // the next admitted scan retries the retained observations, while the owner's public door stays available.
+      listenerLog('fleet listener scan refused; retained observations wait for a prepared owner call');
+    }
+  };
   const readListenerRecords = () => {
     if (!fleetListeners.enabled || stopped || listenerReading) return listenerReading;
     const revision = listenerRevision;
@@ -1964,7 +2007,9 @@ async function serve(root, args = {}) {
   };
   fleetListeners = new FleetListenerRouter({ root, log: listenerLog,
     file: (to, body, key) => ownCall(() => fileFleetNotice(root, to, body, key)),
-    enrich: event => ownCall(() => enrichFleetEvent(root, event)),
+    // The scan/flush prepares custody once; enqueue needs the event synchronously before committing its cursor.
+    enrich: event => enrichFleetEvent(root, event),
+    work: ownCall,
     retry: () => scanListeners({ waiting: false }),
   });
   const unfollowRecords = onRecordsChanged(records => { listenerRecords = records; scanListeners(); });

package/board/credential-guard.mjs

@@ -3,7 +3,20 @@
 // gitleaks' rule set and this machine's custody values), plus the shape of an environment listing: several NAME=value
 // lines in a row. A shell that expanded `$(env)` or a pasted .env into a comment once put live keys on a card, where
 // every reader, every launch prompt and the board's own remote received them.
-import { redactText } from '@volter/teams/redact';
+import { redactText, redactionSnapshotAsync, withRedactionSnapshot } from '@volter/teams/redact';
+import { noteStep } from '@volter/supercode-harness-sdk/slow-log';
+
+/** One fresh, fail-closed custody observation per call/round, read before its synchronous guards. No role decision
+ * is kept here, and a concurrent caller cannot replace this call's redaction basis. */
+export async function withCredentialGuard(fn) {
+  const began = performance.now();
+  let snapshot;
+  try { snapshot = await redactionSnapshotAsync(process.env, { fresh: true }); }
+  finally { noteStep('custody observation', performance.now() - began); }
+  return withRedactionSnapshot(process.env, snapshot, fn);
+}
+
+export const redactGuardText = text => redactText(text);
 
 const ENV_LINE = /^\s*(?:export\s+|declare\s+-x\s+)?[A-Z][A-Z0-9_]{2,}=\S/;
 const ENV_LINES = 5;
@@ -13,7 +26,7 @@ export function credentialDumpIn(text) {
   if (typeof text !== 'string' || text.length < 8) return null;
   const lines = text.split('\n').filter((line) => ENV_LINE.test(line)).length;
   if (lines >= ENV_LINES) return `${lines} NAME=value lines, the shape of an environment listing`;
-  const redacted = redactText(text);
+  const redacted = redactGuardText(text);
   if (redacted === text) return null;
   const before = new Set(text.match(/\[redacted:[^\]]+\]/g) ?? []);
   const found = [...new Set((redacted.match(/\[redacted:[^\]]+\]/g) ?? []).filter((marker) => !before.has(marker)))]