@volter/supercode-orchestrator 0.5.205 → 0.5.206

package/bin/connection-runner.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// The home's installed-app runner owns only children it starts, and every connection keeps separate custody.
+import { existsSync, openSync, closeSync, readFileSync, unlinkSync, renameSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { parseArgs } from 'node:util';
+import { activeAgentAssignments, localAgentConversation } from '../agents.mjs';
+import { connectionCall, connectionCanRun, connectionPath, generateModuleConfig, privateJson } from '../connection.mjs';
+
+const {values}=parseArgs({options:{root:{type:'string'},connection:{type:'string'}}});
+const path=connectionPath(values.root,values.connection),folder=dirname(path),lock=join(folder,'runner.lock');
+let record=JSON.parse(readFileSync(path,'utf8'));
+record.root=values.root;
+if(!connectionCanRun(record))process.exit(0);
+if(existsSync(lock)){
+  const previous=JSON.parse(readFileSync(lock,'utf8'));
+  try{process.kill(previous.pid,0);process.exit(0);}catch(error){if(error.code!=='ESRCH')throw error;}
+  renameSync(lock,`${lock}.stopped-${Date.now()}`);
+}
+const fd=openSync(lock,'wx',0o600);closeSync(fd);privateJson(lock,{pid:process.pid,connection:record.id});
+const children=new Map(),health=record.health??={},raised=record.raised??{};
+let stopped=false;
+const log=(event,data={})=>process.stdout.write(JSON.stringify({t:new Date().toISOString(),event,...data})+'\n');
+const save=()=>{record.health=health;record.raised=raised;privateJson(path,record);};
+const teamPath=`/api/v1/teams/${encodeURIComponent(record.teams.team)}`;
+const issue=(name,reason)=>{health[name]={state:'unavailable',reason,at:new Date().toISOString()};save();};
+const recover=name=>{health[name]={state:'current',at:new Date().toISOString()};save();};
+function start(grant){
+  if(stopped||children.has(grant.name)||!existsSync(join(values.root,'apps',`${grant.name}.${record.id}.json`)))return;
+  const config=generateModuleConfig(values.root,record,grant);
+  const child=spawn(process.execPath,[join(record.moduleRoot,grant.name,'main.mjs'),config],{stdio:['ignore','pipe','pipe'],env:{...process.env,SUPERCODE_ORCHESTRATOR_HOME:values.root,HERMES_HOME:values.root}});
+  children.set(grant.name,child);let buffer='';
+  child.stdout.on('data',chunk=>{
+    process.stdout.write(chunk);if(stopped)return;buffer+=chunk.toString();let at;
+    while((at=buffer.indexOf('\n'))>=0){const line=buffer.slice(0,at);buffer=buffer.slice(at+1);let event;try{event=JSON.parse(line);}catch{continue;}
+      if(['read-error','read-failed','tick-failed','event-stream-failed','resync_required','access_revoked'].includes(event.event))issue(grant.name,event.code??event.reason??event.event);
+      if(['source-current','snapshot-read','snapshot-empty','published'].includes(event.event)&&event.current!==false)recover(grant.name);
+      if(['arc-pending','card-pending'].includes(event.event))issue(`obligation.${grant.name}.${event.card}`,`${event.status?'HTTP '+event.status+' ':''}${event.code??event.event}${event.message?' — '+event.message:''}`.slice(0,300));
+      if(event.event==='projection-current')recover(`obligation.${grant.name}.${event.card}`);
+    }
+    if(buffer.length>65536)buffer='';
+  });
+  child.stderr.on('data',chunk=>{process.stderr.write(chunk);if(!stopped)issue(grant.name,'module wrote a startup/runtime error; inspect its runner log');});
+  child.on('error',error=>issue(grant.name,error.code??'start-failed'));
+  child.on('exit',(code,signal)=>{
+    children.delete(grant.name);if(!stopped){issue(grant.name,`module exited (${code??signal})`);setTimeout(()=>start(grant),5000);}
+  });
+  log('module-started',{module:grant.name,pid:child.pid});
+}
+async function stopChild(name){
+  const child=children.get(name);if(!child)return;children.delete(name);
+  child.removeAllListeners('exit');child.kill('SIGTERM');
+  await new Promise(done=>{const timer=setTimeout(()=>{child.kill('SIGKILL');done();},5000);child.once('exit',()=>{clearTimeout(timer);done();});});
+}
+async function syncAlerts(){
+  const grant=record.grants.find(g=>g.manifest.actions.includes('alert.raise')&&existsSync(join(values.root,'apps',`${g.name}.${record.id}.json`)));
+  if(!grant)return;
+  for(const [name,state] of Object.entries(health)){
+    const key=`connection.${record.id}.${name}`.slice(0,200),wanted=state.state==='unavailable'?state.reason:null;
+    if(raised[name]===wanted || (wanted===null && !Object.hasOwn(raised,name)))continue;
+    try{
+      await connectionCall(record,'rh2','POST',`/api/v3/organizations/${encodeURIComponent(record.organization)}/alerts${wanted?'':'/clear'}`,wanted?{key,severity:'warning',reason:wanted,targetRole:record.alertRole}:{key},grant.rh2.accessToken);
+      raised[name]=wanted;save();
+    }catch(error){log('connection-alert-pending',{module:grant.name,code:error.code??error.status??'unavailable'});}
+  }
+}
+function standing(){
+  const assignments=activeAgentAssignments(values.root);
+  const rows=(record.standingSelection??[]).map(selection=>{
+    const own=assignments.filter(row=>row.org===record.teams.team&&row.kind==='profile'&&row.target===selection.profile);
+    if(own.length!==1){issue(`standing.${selection.profile}`,own.length?'profile has multiple active agent owners':'profile has no declared conversation owner');return {...selection,reason:'conversation-owner-unknown'};}
+    const conversation=localAgentConversation(values.root,record.teams.team,own[0].agent_id);
+    if(!conversation){issue(`standing.${selection.profile}`,'the home has no conversation-session receipt for this profile');return {...selection,agent:own[0].agent_id,reason:'conversation-session-unknown'};}
+    recover(`standing.${selection.profile}`);return {...selection,agent:own[0].agent_id,session:conversation.session,startedAt:conversation.started_at,running:conversation.ended_at==null};
+  });
+  const target=join(folder,'standing.json');
+  if(!existsSync(target)||readFileSync(target,'utf8').trim()!==JSON.stringify(rows,null,2))privateJson(target,rows);
+}
+async function renewTeams(value){
+  if(!value.pendingRenewal&&value.credential.expires_at-Date.now()>7*86400000)return false;
+  if(value.pendingRenewal&&value.renewalRetryAt>Date.now())return false;
+  const recovering=typeof value.pendingRenewal==='string';
+  value.pendingRenewal??=`sct_cred_${randomHex(16)}.${randomBase64()}`;
+  value.renewalRetryAt=Date.now()+30000;save();
+  const path=`${teamPath}/app-installations/${value.installation.id}/renew`,body={replacement_token:value.pendingRenewal};
+  let renewed;
+  if(recovering){
+    try{renewed=(await connectionCall(record,'teams','POST',path,body,value.pendingRenewal)).data;}
+    catch(error){if(error.status!==401)throw error;} // No committed replacement yet: use the predecessor below.
+  }
+  renewed??=(await connectionCall(record,'teams','POST',path,body,value.credential.token)).data;
+  if(renewed.credential_id!==value.pendingRenewal.slice(4).split('.')[0]||renewed.installation_id!==value.installation.id||!(renewed.expires_at>Date.now()))throw new Error('renewal metadata does not admit the staged replacement');
+  value.credential={...value.credential,token:value.pendingRenewal,expires_at:renewed.expires_at};delete value.pendingRenewal;delete value.renewalRetryAt;save();return true;
+}
+function randomHex(size){return crypto.getRandomValues(new Uint8Array(size)).reduce((out,n)=>out+n.toString(16).padStart(2,'0'),'');}
+function randomBase64(){return Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString('base64url');}
+async function renew(){
+  for(const grant of record.grants){
+    if(!existsSync(join(values.root,'apps',`${grant.name}.${record.id}.json`)))continue;
+    try{
+      let changed=false;
+      if(Date.parse(grant.rh2.expiresAt)-Date.now()<=7*86400000){grant.rh2={...grant.rh2,...(await connectionCall(record,'rh2','POST',`/api/v3/automation/installations/${grant.rh2.installationId}/renew`,{},grant.rh2.accessToken)).data};changed=true;save();}
+      if(grant.teams)changed=await renewTeams(grant.teams)||changed;
+      if(changed&&existsSync(join(values.root,'apps',`${grant.name}.${record.id}.json`))){await stopChild(grant.name);start(grant);}
+      if(!grant.teams?.pendingRenewal)recover(`expiry.${grant.name}`);
+    }catch(error){issue(`expiry.${grant.name}`,error.code??'renewal-unavailable');}
+  }
+  try{await renewTeams(record.issuerCredential);if(!record.issuerCredential.pendingRenewal)recover('issuer-renewal');}catch(error){issue('issuer-renewal',error.code??'renewal-unavailable');}
+}
+for(const signal of ['SIGTERM','SIGINT'])process.on(signal,()=>void stop());
+for(const grant of record.grants)start(grant);
+let lastRenew=0,lastStanding=0,lastKeys=0;
+async function publishIssuerKeys(results=[]){
+  const keys=(await connectionCall(record,'rh2','GET','/.well-known/jwks.json')).keys;
+  await connectionCall(record,'teams','POST',`${teamPath}/app-installations/${record.issuerCredential.installation.id}/issuer-keyring`,{keys,results},record.issuerCredential.credential.token);
+  lastKeys=Date.now();
+}
+while(!stopped){
+  try{
+    const installed=record.grants.filter(grant=>existsSync(join(values.root,'apps',`${grant.name}.${record.id}.json`)));
+    for(const name of children.keys())if(!installed.some(grant=>grant.name===name))await stopChild(name);
+    if(!installed.length){await stop();break;}
+    const pendingRenewalDue=[record.issuerCredential,...installed.map(grant=>grant.teams)].some(value=>value?.pendingRenewal&&!(value.renewalRetryAt>Date.now()));
+    if(pendingRenewalDue||Date.now()-lastRenew>3600000){await renew();lastRenew=Date.now();}
+    if(Date.now()-lastStanding>15000){standing();lastStanding=Date.now();}
+    // A restart may have outlived the key lease; publish before a twenty-second idle poll can delay admission.
+    if(Date.now()-lastKeys>=30000)await publishIssuerKeys();
+    const pending=(await connectionCall(record,'teams','GET',`${teamPath}/app-installations/${record.issuerCredential.installation.id}/issuer-checks`,undefined,record.issuerCredential.credential.token)).data.checks;
+    const results=await Promise.all(pending.map(async check=>{
+      // Every generation starts its own status read AFTER this poll received it. Never share a token decision,
+      // even if two generations of the same token occur in one batch; only this generation may use this answer.
+      const generation=check.id;
+      const status=(await connectionCall(record,'rh2','POST','/api/v3/delegated/status',{token:check.token})).data;
+      return {id:generation,live:status?.live===true};
+    }));
+    if(results.length||Date.now()-lastKeys>=30000)await publishIssuerKeys(results);
+    recover('issuer');await syncAlerts();
+  }catch(error){issue('issuer',error.code??error.status??'outbound-connection-unavailable');await syncAlerts();}
+  await new Promise(done=>setTimeout(done,2000));
+}
+async function stop(){if(stopped)return;stopped=true;await Promise.all([...children.keys()].map(stopChild));record.stoppedAt=new Date().toISOString();save();unlinkSync(lock);process.exit(0);}

package/bin/orchestrator.mjs

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+// before anything loads node:sqlite: Node's notice that it is experimental is not this command's to print
+try { await import('@volter/supercode-harness-sdk/runtime-warnings'); } catch { /* a harness SDK without it: the notice is printed */ }
 // Check before handing off or importing board/runtime dependencies.
 let lockedNative;
 try { ({ lockedNative } = await import('../source-lock.mjs')); }
@@ -18,7 +20,7 @@ try {
 } catch (error) { process.stderr.write(`${error.message}\n`); process.exit(1); }
 // Board commands do not load daemon transports, platform adapters or the MCP server.
 if (process.argv[2] === 'workflow') {
-  const [{runWorkflow},{timeCommand}]=await Promise.all([import('../board/client.mjs'),import('@volter/supercode-harness-sdk/slow-log')]);
+  const [{runWorkflow},{timeCommand,noteCommandError}]=await Promise.all([import('../board/client.mjs'),import('@volter/supercode-harness-sdk/slow-log')]);
   // A board command is timed into the slow log; `serve` runs until stopped and is not one.
   const verb=process.argv.slice(3).find((arg,index,all)=>!arg.startsWith('-')&&!(index>0&&/^--(root|board|cwd|context|at)$/.test(all[index-1])));
   if(verb!=='serve')timeCommand(`workflow ${verb??''}`.trim(),process.argv.slice(3));
@@ -26,11 +28,18 @@ if (process.argv[2] === 'workflow') {
   try {code=await runWorkflow(process.argv.slice(3));}
   // a store's own error (SQLite's, with its errcode) is no message written for a person: its stack says which statement
   // met it, as a follower's end in the connector's log (board events) otherwise could not
-  catch(error) {process.stderr.write(`supercode workflow: ${error.message??error}\n${error?.errcode!=null&&error.stack?`${error.stack}\n`:''}`);code=1;}
+  catch(error) {noteCommandError(error);process.stderr.write(`supercode workflow: ${error.message??error}\n${error?.errcode!=null&&error.stack?`${error.stack}\n`:''}`);code=1;}
   // the board documents' git work this command queued (a ztrack board's commit and push) is finished before it exits
   try{const{settleDocuments}=await import('../board/git-document.mjs');await settleDocuments();}catch{/* nothing queued */}
   await Promise.all([process.stdout,process.stderr].map(stream=>new Promise(done=>stream.write('',done))));
   process.exit(code);
+} else if (process.argv[2] === 'connect') {
+  const {parseArgs}=await import('node:util');
+  const {connectWorkplace}=await import('../connection.mjs');
+  const options=Object.fromEntries(['root','ticket-file','modules-root','source','context','teams-token-file','teams-url','team','floor','standing-file','alert-role'].map(key=>[key,{type:'string'}]));
+  options['no-start']={type:'boolean'};
+  try{const {values}=parseArgs({args:process.argv.slice(3),options});process.stdout.write(JSON.stringify(await connectWorkplace(values),null,2)+'\n');}
+  catch(error){process.stderr.write(`connect: ${error.message}\n`);process.exitCode=1;}
 } else if (process.argv[2] === 'agent-channel') {
   await import('./agent-channel.mjs');
 } else {

package/bin/runtime.mjs

@@ -70,7 +70,7 @@ import {
   TICK_MS, accessPolicy, applyOperator, performRemoveProfileDir, OPERATOR_OPS,
 } from '../index.mjs';
 import * as events from '../events.mjs';
-import { appView, installAgent, installApp, installedAgentRecord, installedApps, removeApp, rh2AgentEnv, rh2Program } from '../installed-apps.mjs';
+import { appView, installAgent, installApp, installedAgentRecord, installedApps, removeApp, rh2AgentEnv, rh2Program, startInstalledModules } from '../installed-apps.mjs';
 import { httpJobExecutor } from '../hosted.mjs';
 import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
 
@@ -290,6 +290,11 @@ async function runOperator(op, argv) {
     process.stdout.write(`${JSON.stringify({ ...answer, root, door: 'live', context_profile: args.profile })}\n`);
     return answer.ok ? 0 : 1;
   }
+  // A launch is a running loop's act (it starts a runtime); without one there is nothing to start it or read it.
+  if (op.startsWith('sessions.launch')) {
+    process.stdout.write(`${JSON.stringify({ ok: false, error: 'the orchestrator for this home is not running; start it before launching a session' })}\n`);
+    return 1;
+  }
   let state;
   let vault;
   try {
@@ -353,6 +358,7 @@ function buildAdapters(state, vault = new Map(), log = () => {}, root = null) {
       report.push({ platform, profile: profileName, adapter: selector, state: 'connecting' });
     }
   }
+  void startInstalledModules(root).catch(error=>log('installed-modules-unavailable',{message:String(error.message)}));
   // Installed apps (ADR 0017): each attaches its channel with the installation's own token, under the profile it was
   // installed for. Uninstalling on the other side revokes the token and the channel stops.
   for (const app of root ? installedApps(root) : []) {
@@ -456,11 +462,12 @@ const ACCESS_OPS = {
  * Hermes's own pairing store and writers, then the home is loaded again to report what stands.
  */
 /** `apps install NAME --origin URL --client-id ID --client-secret-file FILE --code CODE [--profile P]`,
- * `apps install rh2-agent --origin URL --organization ORG --principal PRN --token-file FILE --profile AGENT`, `apps list`,
+ * `apps install rh2-agent --origin URL --organization ORG --principal PRN --agent AGENT_ID --token-file FILE --profile AGENT`, `apps list`,
  * `apps remove NAME`. */
 async function appsMain(argv) {
   const [verb, ...rest] = argv;
-  // `apps mcp rh2-agent --profile <agent> [--root R]`: `rh2 mcp` as the installed agent, its credential in that one
+  // `apps mcp rh2-agent --agent <its Teams id> [--root R]`: `rh2 mcp` as the agent whose record that id names, its
+  // credential in that one
   // process's environment (rh2AgentEnv) and nowhere else: no config file carries the token, and the command is fixed,
   // so nothing can be run in its place to print the token. It is how an agent's session mounts RH2 (mcp/mount.mjs).
   if (verb === 'mcp') {
@@ -469,13 +476,13 @@ async function appsMain(argv) {
     for (let i = 0; i < rest.length; i += 1) {
       if (rest[i].startsWith('--')) { opts[rest[i].slice(2)] = rest[i + 1]; i += 1; } else words.push(rest[i]);
     }
-    if (words[0] !== 'rh2-agent' || words.length !== 1 || !opts.profile) {
-      process.stderr.write('apps mcp rh2-agent --profile <agent> [--root R]\n');
+    if (words[0] !== 'rh2-agent' || words.length !== 1 || !opts.agent) {
+      process.stderr.write('apps mcp rh2-agent --agent <its Teams id> [--root R]\n');
       process.exit(2);
     }
-    const record = installedAgentRecord(resolve(opts.root ?? defaultRoot()), opts.profile);
+    const record = installedAgentRecord(resolve(opts.root ?? defaultRoot()), opts.agent);
     if (!record) {
-      process.stderr.write(`no rh2-agent is installed for ${opts.profile}: install it with apps install rh2-agent --profile ${opts.profile}\n`);
+      process.stderr.write(`no single rh2-agent record is installed for ${opts.agent}: install it with apps install rh2-agent --agent ${opts.agent}\n`);
       process.exit(1);
     }
     const program = rh2Program();
@@ -498,9 +505,9 @@ async function appsMain(argv) {
     if (verb === 'list') { say('apps', { root, apps: installedApps(root).map(appView) }); return; }
     if (verb === 'remove') { say('apps', { root, removed: removeApp(root, positional[0] ?? '') }); return; }
     if (verb === 'install' && positional[0] === 'rh2-agent') {
-      for (const name of ['origin', 'organization', 'principal', 'token-file', 'profile']) if (!flags[name]) throw new Error(`apps install rh2-agent needs --${name}`);
+      for (const name of ['origin', 'organization', 'principal', 'agent', 'token-file', 'profile']) if (!flags[name]) throw new Error(`apps install rh2-agent needs --${name}`);
       const token = readFileSync(flags['token-file'], 'utf8').trim();
-      say('apps', { root, installed: appView(await installAgent({ root, origin: flags.origin, organization: flags.organization, principal: flags.principal, token, profile: flags.profile })) });
+      say('apps', { root, installed: appView(await installAgent({ root, origin: flags.origin, organization: flags.organization, principal: flags.principal, agent: flags.agent, token, profile: flags.profile })) });
       return;
     }
     if (verb === 'install') {

package/board/args.mjs

@@ -3,7 +3,7 @@ import { resolve } from 'node:path';
 
 export const MULTI = new Set(['parent', 'skill', 'worker', 'child', 'ids', 'rm', 'tag', 'pr', 'pr-head', 'reviewed-sha', 'finding']);
 export const FLAGS = new Set(['json', 'triage', 'no-notify', 'no-start', 'all', 'force', 'help', 'mine', 'archived', 'reclaim', 'dry-run',
-  'once', 'goal', 'no-goal', 'off', 'switch', 'delete', 'no-attachments', 'include-logs', 'verbose', 'commit', 'side']);
+  'once', 'goal', 'no-goal', 'off', 'switch', 'delete', 'no-attachments', 'include-logs', 'verbose', 'side']);
 // flags that take every following word up to the next flag (Hermes's nargs='+')
 export const GREEDY = new Set(['ids', 'rm']);
 
@@ -13,7 +13,8 @@ export function parse(argv) {
     const a = argv[i];
     if (!a.startsWith('--') || a === '--') { out._.push(a); continue; }
     const [key, inline] = a.slice(2).split(/=(.*)/s);
-    if (FLAGS.has(key)) { out[key] = true; continue; }
+    // init toggles document commits; completion/review names a git revision.
+    if (FLAGS.has(key) || (key === 'commit' && out._[0] === 'init')) { out[key] = true; continue; }
     if (GREEDY.has(key)) {
       const values = inline !== undefined ? [inline] : [];
       while (i + 1 < argv.length && !argv[i + 1].startsWith('--')) values.push(argv[++i]);

package/board/attachment-read.mjs

@@ -0,0 +1,77 @@
+import { constants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { isAbsolute, join, relative, sep } from 'node:path';
+
+export const ATTACHMENT_CHUNK_BYTES = 1024 * 1024;
+const OPEN_FLAGS = constants.O_RDONLY | (constants.O_NONBLOCK ?? 0) | (constants.O_NOFOLLOW ?? 0);
+// A failed close is not permission to retry it or forget its exact handle.
+const uncertainHandles = new Map();
+const sameFile = (a, b) => a.dev === b.dev && a.ino === b.ino && a.birthtimeNs === b.birthtimeNs;
+const stamp = (s) => createHash('sha256').update([s.dev, s.ino, s.size, s.mtimeNs, s.ctimeNs].join(':')).digest('hex');
+const inside = (directory, path) => {
+  const r = relative(directory, path);
+  return Boolean(r) && !isAbsolute(r) && r !== '..' && !r.startsWith(`..${sep}`);
+};
+
+/** Read a recorded attachment, never an arbitrary host pathname. `version`
+ * guards subsequent ranges against changed filesystem metadata. */
+export async function readAttachment(root, slug, row, { offset = 0, length = ATTACHMENT_CHUNK_BYTES, version = null } = {}) {
+  if (uncertainHandles.size) throw Object.assign(new Error('attachment reader retains an unconfirmed descriptor close', {
+    cause: uncertainHandles.values().next().value,
+  }), { code: 'attachment_cleanup_unconfirmed' });
+  if (!row) throw new Error('no such attachment on this card');
+  if (!/^[A-Za-z0-9_-]+$/.test(row.task_id)) throw new Error('attachment has an invalid task id');
+  if (!Number.isSafeInteger(offset) || offset < 0) throw new Error('attachment offset must be a nonnegative safe integer');
+  if (!Number.isSafeInteger(length) || length < 1 || length > ATTACHMENT_CHUNK_BYTES) throw new Error(`attachment length must be between 1 and ${ATTACHMENT_CHUNK_BYTES}`);
+  if (offset > 0 && (typeof version !== 'string' || !version)) throw new Error('subsequent attachment ranges need the first response version');
+  const home = await realpath(root);
+  const collection = await realpath(join(home, 'kanban', ...(slug === 'default' ? [] : ['boards', slug]), 'attachments'));
+  const directory = await realpath(join(collection, row.task_id));
+  const path = await realpath(row.stored_path);
+  if (!inside(home, collection) || !inside(collection, directory) || !inside(directory, path)) throw new Error('attachment is outside this card\'s attachment directory');
+  const admitted = await lstat(path, { bigint: true });
+  if (!admitted.isFile()) throw new Error('attachment is not a readable regular file of supported size');
+  // The pathname check alone cannot prevent replacement with a FIFO before open.
+  const handle = await open(path, OPEN_FLAGS);
+  let failure, result;
+  try {
+    const before = await handle.stat({ bigint: true });
+    const size = Number(before.size);
+    if (!before.isFile() || !Number.isSafeInteger(size)) throw new Error('attachment is not a readable regular file of supported size');
+    if (!sameFile(admitted, before)) throw new Error('attachment was replaced before the read; start a new download');
+    const named = await lstat(path, { bigint: true });
+    if (!named.isFile() || !sameFile(before, named) || await realpath(row.stored_path) !== path) throw new Error('attachment pathname changed before the read; start a new download');
+    if (size !== Number(row.size)) throw new Error('attachment size differs from its recorded upload');
+    const currentVersion = stamp(before);
+    if (version !== null && version !== currentVersion) throw new Error('attachment changed since the first range; start a new download');
+    if (offset > size) throw new Error('attachment offset is beyond its end');
+    const bytes = Buffer.alloc(Math.min(length, size - offset));
+    let read = 0;
+    while (read < bytes.length) {
+      const { bytesRead: count } = await handle.read(bytes, read, bytes.length - read, offset + read);
+      if (count <= 0) throw new Error('attachment ended before its recorded extent');
+      read += count;
+    }
+    if (stamp(await handle.stat({ bigint: true })) !== currentVersion) throw new Error('attachment changed during the read; start a new download');
+    const after = await lstat(path, { bigint: true });
+    if (!after.isFile() || !sameFile(before, after) || await realpath(row.stored_path) !== path) throw new Error('attachment pathname changed during the read; start a new download');
+    result = { task_id: row.task_id, attachment_id: row.id, filename: row.filename, content_type: row.content_type,
+      size, version: currentVersion, offset, read, next_offset: offset + read, eof: offset + read === size, content_base64: bytes.toString('base64') };
+  } catch (error) { failure = error; }
+  try { await handle.close(); }
+  catch (cleanup) {
+    const error = Object.assign(new AggregateError([...(failure ? [failure] : []), cleanup], 'attachment descriptor cleanup is unconfirmed', {
+      cause: failure ?? cleanup,
+    }), { code: 'attachment_cleanup_unconfirmed' });
+    uncertainHandles.set(handle, error);
+    throw error;
+  }
+  if (failure) throw failure;
+  return result;
+}
+
+export const attachmentRecord = (db, task, id) => {
+  if (!Number.isSafeInteger(id) || id < 1) throw new Error('attachment id must be a positive safe integer');
+  return db.prepare('SELECT * FROM task_attachments WHERE task_id = ? AND id = ?').get(task, id);
+};

package/board/call.mjs

@@ -11,6 +11,8 @@
 //   cwd        the caller's working directory, against which a path it names is read
 //   stdin      what the caller sent on its standard input, for a `-` it names as a file (null: none)
 //   out, err   where the verb writes its answer
+//   readOnly   a listing answered on the owner's read door (owner-door.mjs): the board is read as one committed state on
+//              a connection of its own (store.mjs openBoard), and nothing is written
 import { readFileSync } from 'node:fs';
 import { AsyncLocalStorage } from 'node:async_hooks';
 
@@ -25,8 +27,8 @@ const own = { kind: 'own', caller: null, facts: process.env, ...fresh(), workflo
 export const current = () => calls.getStore() ?? own;
 
 /** Run `fn` as one caller's call, its answer written through `out` and `err`. */
-export function within({ caller = null, facts = {}, cwd, stdin = null, out, err }, fn) {
-  return calls.run({ kind: 'caller', caller, facts, ...fresh(), cwd, stdin, out, err }, fn);
+export function within({ caller = null, facts = {}, cwd, stdin = null, out, err, readOnly = false }, fn) {
+  return calls.run({ kind: 'caller', caller, facts, ...fresh(), cwd, stdin, out, err, readOnly }, fn);
 }
 
 /** Run `fn` as a unit of the process's own work (a round, a delivery pass): the process's identity and output, with

package/board/capacity.mjs

@@ -3,7 +3,10 @@
 // (`where`, less `unless`) and its `max`. This module counts what a home holds now and answers whether one more card may start.
 
 import { json } from './store.mjs';
+import { detachedSession } from './custody.mjs';
 import { statusOf } from './workflow.mjs';
+import { setImmediate as yieldToOwner } from 'node:timers/promises';
+import { listRevision } from './listing.mjs';
 
 /** The scope's group a counted thing or a card falls in. */
 const GROUP = {
@@ -36,14 +39,45 @@ export function matches(filter, thing) {
 const applies = (cap, thing) => matches(cap.where, thing) && !(Object.keys(cap.unless ?? {}).length && matches(cap.unless, thing));
 
 /** Each slot's latest recorded session on a card (implementer `worker`, `reviewer`, …), newest run first. */
-function sessionsOf(db, taskId) {
+async function sessionsOf(db, taskId, unchanged) {
   const out = new Map();
-  for (const row of db.prepare('SELECT id, metadata FROM task_runs WHERE task_id = ? AND metadata IS NOT NULL ORDER BY id DESC').all(taskId)) {
-    const s = json(row.metadata, {})?.supercode;
-    const slot = s?.slot ?? 'worker';
-    if (s?.session_id && !out.has(slot)) out.set(slot, { ...s, run: row.id });
+  let cursor = null;
+  for (;;) {
+    if (!unchanged()) return null;
+    // Page by the indexed run id, not an offset. Include null metadata so even a long empty history
+    // reads only 64 records per statement. Every page is visited: an older, distinct slot still counts.
+    const rows = db.prepare(`SELECT id, metadata FROM task_runs WHERE task_id = ?${cursor === null ? '' : ' AND id < ?'} ORDER BY id DESC LIMIT 64`)
+      .all(taskId, ...(cursor === null ? [] : [cursor]));
+    for (const row of rows) {
+      const s = json(row.metadata, {})?.supercode;
+      const slot = s?.slot ?? 'worker';
+      if (s?.session_id && !out.has(slot)) out.set(slot, detachedSession(db, s) ? null : { ...s, run: row.id });
+    }
+    if (rows.length < 64) break;
+    cursor = rows.at(-1).id;
+    await yieldToOwner();
+  }
+  return new Map([...out].filter(([, s]) => s));
+}
+
+const sameRevision = (a, b) => Object.keys(a).every(key => a[key] === b[key]);
+
+/** Read a stable board before admitting starts. An unread capacity never becomes an empty board. */
+export async function holdings(board, options) {
+  try {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      // Reuse the listing's guard: own/external commits, TEMP overlays and file projection reloads all count.
+      const before = listRevision(board.db);
+      const unchanged = () => sameRevision(before, listRevision(board.db));
+      const out = await readHoldings(board, options, unchanged);
+      if (out !== null && unchanged()) return out;
+      await yieldToOwner();
+    }
+    throw new Error(`Capacity of board ${board.slug} changed during its reading; this round starts no cards.`);
+  } catch (error) {
+    error.capacityUnread = true;
+    throw error;
   }
-  return out;
 }
 
 /**
@@ -53,10 +87,12 @@ function sessionsOf(db, taskId) {
  * own transcript reports it runs, or null where none can be read; `machineOf` normalises a machine name; `lanes` gives
  * a profile's harness and model.
  */
-export function holdings(board, { lanes, fleetOk, alive, liveRecord, modelOf = () => null, storedOf = null, machineOf, home = null, runLaneOf = null }) {
+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'").all();
+  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) {
+    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),
@@ -76,7 +112,8 @@ export function holdings(board, { lanes, fleetOk, alive, liveRecord, modelOf = (
           : 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 ? sessionsOf(board.db, row.id) : new Map();
+    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) {