@volter/supercode-orchestrator 0.5.207 → 0.5.209

package/README.md

@@ -32,7 +32,7 @@ import { join } from 'node:path';
 
 const root = process.env.SUPERCODE_ORCHESTRATOR_HOME || join(homedir(), '.supercode/orchestrator');
 const { state, vault } = await load(root);                        // strict; secrets in `vault`, never `state`
-await save(state, root);                                          // canonical, byte-stable when unchanged
+await save(state, root);                                          // runtime state; preserves workflow.yaml
 
 const { state: hermesState } = await compile('hermes', process.env.HERMES_HOME); // a home as a state value
 await closeWorld();                                              // close the shared door when done
@@ -57,6 +57,14 @@ Rules the codec keeps (enforced in Rust, observed here):
   since import (UNI-22); it copies the store byte for byte when they did not.
 - Files the IR does not model are never touched by `save` and are carried by path on a migration.
 
+Runtime `save` and load-time credential normalization leave `workflow.yaml` untouched,
+including a symlink or an absent file. The board reads policy from the live home;
+an older runtime snapshot cannot replace an edited cap. For intentional full-home
+creation or replacement, use `orchestrationSave` (which writes the workflow by
+default), `supercode orchestration save --from-json`, or `importFrom`.
+Other SDK callers that persist runtime state set `preserve_workflow: true` on
+`orchestrationSave`. See [workflow ownership](../../docs/adr/0067-live-workflow-ownership.md).
+
 ## Board machine-call deadlines
 
 The board owner's machine calls share one timeout budget across channel admission,
@@ -197,7 +205,7 @@ Tiers on the way out:
   too, rather than written as its own reference.
 
 Secrets never enter the model: any string under a credential-shaped key — openclaw's own rule
-(`orchestration/codec/openclaw.rs::is_credential_key`: the lower-cased key ENDS WITH `token|key|secret|password|
+(`sdk/interchange/orchestration-openclaw.mjs`: the lower-cased key ENDS WITH `token|key|secret|password|
 credential`), minus the names it spells that way for non-secrets (`sessionKey`, `store_key`, …) —
 moves to the vault as a `{dotenv}` ref and is re-inlined on export where openclaw reads it.
 
@@ -713,3 +721,23 @@ authority, in-progress-operation refusals and already-issued-request boundaries.
 [Source observations](../../docs/evidence/board-session-detach-2026-10-09.md)
 cover actual help, compilation and read-only retained records. Live handback,
 return through adoption and released availability remain unqualified.
+
+## Readable card ids
+
+Every card has a `readable_id` beside its number and native id. Create one with
+`supercode workflow create "Voice calls" --readable-id voice-calls --root HOME`,
+or let the board derive it from the title. Names use lowercase kebab-case, start
+with a letter, have at most 32 characters and are unique among open cards.
+Automatic collisions gain a numeric suffix; explicit duplicates are refused.
+
+`workflow list` and `show` display the name. `workflow specify CARD --readable-id
+voice-calls --root HOME` changes it; the same `readable_id` property is editable
+in a ztrack card's metadata in `arcs.md`. A title edit keeps its existing id.
+Older boards fill missing names from leading title slugs before other title words.
+
+Generated branches use `vo-42-voice-calls`. Card agents become
+`implementer-voice-calls` or `reviewer-voice-calls`, with the same immutable agent
+id and sessions; the ordinary delivery pass sends existing agents' renames to
+the machine. The Workplace updates its existing principal and spoken name.
+Existing worktrees, explicit branches and personal naming overrides keep their
+normal protections. Merge and release remain separate from this source behavior.

package/agents.mjs

@@ -162,7 +162,7 @@ export function agentRunForKey(root,org,agent,key) {
 const declarationHead=(root,org,key)=>{const db=store(root);try{return db.prepare('SELECT agent_id FROM agent_declaration_heads WHERE org=? AND key=?').get(org,key)?.agent_id??null;}finally{db.close();}};
 const endedHere=(root,org,id)=>{const db=store(root);try{return !!db.prepare('SELECT 1 FROM agent_runs WHERE org=? AND agent_id=? AND end_reason IS NOT NULL LIMIT 1').get(org,id);}finally{db.close();}};
 function recordDeclaration(root,org,id,declaration){
-  const db=store(root);try{db.prepare('UPDATE agent_intents SET declaration_json=? WHERE org=? AND id=? AND declared=0').run(JSON.stringify(declaration),org,id);}finally{db.close();}
+  const db=store(root);try{db.prepare('UPDATE agent_intents SET declaration_json=?,declared=0 WHERE org=? AND id=? AND declaration_json IS NOT ?').run(JSON.stringify(declaration),org,id,JSON.stringify(declaration));}finally{db.close();}
 }
 /** The identity a run starts as, never asking Teams: the daemon-minted id and retained intent. Its declaration is handed
  * to this machine's daemon (handOffAgents), which declares it to Teams under the same id. Nothing is granted from this
@@ -177,9 +177,11 @@ async function localAgent(options,{key,name,declaration,assignment,parent=null,s
   // is minted in its place, with fresh memory.
   if(key!=='root'&&endedHere(root,org,intent.id))intent=await nextAgentGeneration(root,intent,machine);
   const above=parent??(key==='root'?null:{id:rootIntent.id,path:basename(root)});
+  // Standing agents retain their names. Card declarations follow the card's editable readable id.
+  if(key!=='root'&&declaration.kind!=='card'){const held=agentIntent(root,org,intent.id);if(held?.declared){try{name=JSON.parse(held.declaration_json??'{}').name??name;}catch{/* its declaration unread: the name given */}}}
   if(key!=='root')recordDeclaration(root,org,intent.id,{...declaration,name,parent:above?.id??null});
   const identity={id:intent.id,kind:'agent',org,name,path:above?`${above.path}/${name}`:name,parent:above?.id??null,
-    lineage:{starter},sponsor:options.sponsor??null,explicit_sponsor:options.sponsor??null,profile,state:'active',
+    lineage:{starter},profile,state:'active',
     synced:!!intent.declared,main_session:null,revision:0};
   const assigned=assignAgent(root,org,intent.id,assignment);
   return {identity,intended:intent.intended,assignment:assigned,assignments:[assignment],org,synced:false};
@@ -196,11 +198,13 @@ export async function localCardAgent(options){
   if(held&&held.agent_id!==declarationHead(root,org,`${server}/${org}/card/${card}/${role}`)&&!endedHere(root,org,held.agent_id)){
     const record=localAgentRecord(root,org,held.agent_id);
     const identity=record?{...record.identity,synced:true}:{id:held.agent_id,kind:'agent',org,name:held.agent_id,path:held.agent_id,parent:null,
-      lineage:{starter:null},sponsor:options.sponsor??null,explicit_sponsor:options.sponsor??null,profile,state:'active',synced:true,main_session:null,revision:0};
+      lineage:{starter:null},profile,state:'active',synced:true,main_session:null,revision:0};
     return {identity,intended:record?.intended??resolveAgentProfile(profiles,profile),assignment:held.id,assignments:[{kind:'card',target:card,role}],org,synced:false};
   }
-  return localAgent(options,{key:`card/${card}/${role}`,name:`${card}-${role}`,assignment:{kind:'card',target:card,role},
-    declaration:{kind:'card',card,role,profile,sponsor:options.sponsor??null,starterSession:options.starterSession??null},
+  // The immutable card/role key keeps the same identity when its readable name changes.
+  const handle=options.handle??null,readableId=options.readableId??null;
+  return localAgent(options,{key:`card/${card}/${role}`,name:`${role}-${readableId??handle??card}`,assignment:{kind:'card',target:card,role},
+    declaration:{kind:'card',card,...(handle?{handle}:{}),...(readableId?{readableId}:{}),role,profile,starterSession:options.starterSession??null},
     starter:options.starterSession?{kind:'session',id:options.starterSession}:{kind:'automation',id:`board:${basename(options.root)}`}});
 }
 export async function localProfileAgent(options){
@@ -208,7 +212,7 @@ export async function localProfileAgent(options){
   const starter={kind:'automation',id:`orchestrator:${basename(root)}`};
   if(declared&&declared!==profile){
     const decl=declarations[declared]??{};
-    return localAgent({...options,sponsor:decl.sponsor??null},{key:`agent/${declared}`,name:declared,assignment:{kind:'agent',target:declared,role:'declared'},
+    return localAgent(options,{key:`agent/${declared}`,name:declared,assignment:{kind:'agent',target:declared,role:'declared'},
       declaration:{kind:'declared',agent:declared,profile},starter});
   }
   if(profile===rootProfile)return localAgent(options,{key:'root',name:basename(root),assignment:{kind:'profile',target:profile,role:'profile'},declaration:{kind:'root',profile},starter});
@@ -220,11 +224,22 @@ export async function localProfileAgent(options){
 export function localAgentRecord(root,org,id){
   const intent=agentIntent(root,org,id);if(!intent)return null;
   const declaration=intent.declaration_json?JSON.parse(intent.declaration_json):{};
-  const name=declaration.kind==='card'?`${declaration.card}-${declaration.role}`:declaration.kind==='profile'?declaration.profile:declaration.kind==='declared'?declaration.agent:basename(root);
+  const name=declaration.name??(declaration.kind==='card'?`${declaration.role}-${declaration.readableId??declaration.handle??declaration.card}`:declaration.kind==='profile'?declaration.profile:declaration.kind==='declared'?declaration.agent:basename(root));
   return {identity:{id,kind:'agent',org,name,path:declaration.kind==='root'?name:`${basename(root)}/${name}`,parent:null,lineage:{starter:null},
-    sponsor:declaration.sponsor??null,profile:intent.profile_ref,state:'active',synced:!!intent.declared,main_session:null,revision:0},
+    profile:intent.profile_ref,state:'active',synced:!!intent.declared,main_session:null,revision:0},
     intended:intent.profile,assignments:intent.assignments,org,synced:!!intent.declared};
 }
+/** 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(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;
+  recordDeclaration(root,assignment.org,assignment.agent_id,{...declaration,name,readableId});
+  return true;
+}
 /** The id a home's mail agent runs as, read and never minted: its own declared identity (`agent/<name>`) where the home
  * holds one, else its profile's (`profile/<profile>`), as localProfileAgent keys them, each at its current generation.
  * Null when the home holds neither, or has no agent store. A channel names its agent by this id (agent-channel). */
@@ -315,7 +330,7 @@ export async function localForkAgent(options){
   const db=store(root);try{db.prepare('UPDATE agent_intents SET profile_json=? WHERE org=? AND id=?').run(JSON.stringify(intended),org,intent.id);}finally{db.close();}
   recordDeclaration(root,org,intent.id,{kind:'fork',profile:parentIntent.profile_ref,name,parent,starterSession:session});
   const assignment=assignAgent(root,org,intent.id,{kind:'fork',target:session,role:key});
-  const identity={id:intent.id,kind:'agent',org,name,path:name,parent,lineage:{starter:{kind:'session',id:session}},sponsor:null,explicit_sponsor:null,
+  const identity={id:intent.id,kind:'agent',org,name,path:name,parent,lineage:{starter:{kind:'session',id:session}},
     profile:parentIntent.profile_ref,state:'active',synced:!!intent.declared,main_session:null,revision:0};
   return {identity,intended,assignment,assignments:[{kind:'fork',target:session,role:key}],org,synced:false};
 }
@@ -369,11 +384,11 @@ async function handOffOrg(root,scope,waiting){
   for(const row of rows){
     const declaration=JSON.parse(row.declaration_json);
     const body={org:scope.org,id:row.id,name:declaration.name??declaration.profile,parent:declaration.parent??null,profile:declaration.profile,
-      ...(declaration.kind==='root'?{root:true}:{}),...(declaration.sponsor?{sponsor:declaration.sponsor}:{}),
+      ...(declaration.kind==='root'?{root:true}:{}),
       ...(declaration.starterSession?{starter_session:declaration.starterSession}:{}),key:digest(row.key)};
     const reply=await runtimeDoor(null,'harness.v1.agents.declare',body,{timeout:15_000});
     if(reply.code!==0){waiting.push({agent:row.id,error:`not handed to this machine's daemon: ${reply.stderr.trim().split('\n').at(-1)}`});break;}
-    db=store(root);try{db.prepare('UPDATE agent_intents SET declared=1 WHERE org=? AND id=?').run(scope.org,row.id);}finally{db.close();}
+    db=store(root);try{db.prepare('UPDATE agent_intents SET declared=1 WHERE org=? AND id=? AND declaration_json=?').run(scope.org,row.id,row.declaration_json);}finally{db.close();}
   }
   for(const row of ends){
     db=store(root);let active;
@@ -469,7 +484,7 @@ export function runBudgetRefusal(root,agent,budgets,now){
 }
 export function agentPreamble(agent,{main=true,previous=[]}={}){
   const {identity:a,intended,assignments=[]}=agent;
-  return `You are agent ${a.path} (${a.id}), ${main?'its main session':'a concurrent session'}.${a.synced===false?' This identity was minted on this machine and is not yet declared on a Teams server; it keeps this id when it is.':''}\nSponsor: ${a.sponsor??'none yet'}; parent: ${a.parent??'none'}; lineage: ${JSON.stringify(a.lineage)}.\nAssignments: ${assignments.map(value=>`${value.kind} ${value.target}, role ${value.role}`).join("; ")}; profile: ${a.profile}; permission layers: ${JSON.stringify(intended.resolved.permissions.layers)}.\nAsk again with supercode agent whoami. List your sessions with supercode agent sessions; read a transcript only when needed.${previous.length?'\nEarlier sessions:\n'+previous.map(s=>`${s.session} · ${s.machine??'unknown machine'} · ended ${s.ended_at??'live'} · ${s.end_reason??''}`).join('\n'):''}`;
+  return `You are agent ${a.path} (${a.id}), ${main?'its main session':'a concurrent session'}.${a.synced===false?' This identity was minted on this machine and is not yet declared on a Teams server; it keeps this id when it is.':''}\nParent: ${a.parent??'none'}; lineage: ${JSON.stringify(a.lineage)}.\nAssignments: ${assignments.map(value=>`${value.kind} ${value.target}, role ${value.role}`).join("; ")}; profile: ${a.profile}; permission layers: ${JSON.stringify(intended.resolved.permissions.layers)}.\nAsk again with supercode agent whoami. List your sessions with supercode agent sessions; read a transcript only when needed.${previous.length?'\nEarlier sessions:\n'+previous.map(s=>`${s.session} · ${s.machine??'unknown machine'} · ended ${s.ended_at??'live'} · ${s.end_reason??''}`).join('\n'):''}`;
 }
 /** The agent's reader context this home already holds (a session of it was bound here before), read from the contexts
  * file without a request, or null. A launch on this machine hands it to the session, so its Teams verbs run delegated

package/bin/connection-runner.mjs

@@ -5,7 +5,7 @@ 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';
+import { SERVICE_APPS, SERVICE_PROGRAM, 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');
@@ -25,10 +25,15 @@ const save=()=>{record.health=health;record.raised=raised;privateJson(path,recor
 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();};
+// The child a grant runs in: a module its own program; a Workplace service registration the one service, which the agents
+// registration hosts (cards and machines start nothing of their own).
+const childOf=grant=>SERVICE_APPS.includes(grant.name)?'agents':grant.name;
 function start(grant){
+  if(SERVICE_APPS.includes(grant.name)&&grant.name!=='agents')return;
   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}});
+  const program=SERVICE_APPS.includes(grant.name)?SERVICE_PROGRAM:join(record.moduleRoot,grant.name,'main.mjs');
+  const child=spawn(process.execPath,[program,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;
@@ -101,7 +106,8 @@ async function renew(){
       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);}
+      // A renewed credential reaches its program by a restart with a regenerated config (the service's, for its registrations).
+      if(changed){const host=record.grants.find(g=>g.name===childOf(grant));if(host&&existsSync(join(values.root,'apps',`${host.name}.${record.id}.json`))){await stopChild(host.name);start(host);}}
       if(!grant.teams?.pendingRenewal)recover(`expiry.${grant.name}`);
     }catch(error){issue(`expiry.${grant.name}`,error.code??'renewal-unavailable');}
   }
@@ -109,12 +115,8 @@ async function renew(){
 }
 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();
-}
+let lastRenew=0,lastStanding=0;
+// Teams verifies the Workplace's tokens against its own JWKS (ADR 0070): nothing is relayed for them here.
 while(!stopped){
   try{
     const installed=record.grants.filter(grant=>existsSync(join(values.root,'apps',`${grant.name}.${record.id}.json`)));
@@ -123,19 +125,8 @@ while(!stopped){
     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();}
+  }catch(error){issue('issuer',error.code??error.status??'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,7 @@
 #!/usr/bin/env node
+// A reader such as `head` may close its pipe before the final flush. Finish the command and its document work;
+// a closed output pipe is not an unhandled runtime error. Other stream failures retain their original error.
+for (const stream of [process.stdout, process.stderr]) stream.on('error', error => { if (error.code !== 'EPIPE') throw error; });
 // 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.
@@ -36,10 +39,20 @@ if (process.argv[2] === 'workflow') {
 } 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');}
+  const {SERVICE_REGISTRATIONS}=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','webhook-url','webhook-listen'].map(key=>[key,{type:'string'}]));
+  options['no-start']={type:'boolean'};options.registrations={type:'boolean'};
+  try{
+    const {values}=parseArgs({args:process.argv.slice(3),options});
+    if(values.registrations)process.stdout.write(`${SERVICE_REGISTRATIONS}\n`);
+    else 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] === 'disconnect') {
+  const {parseArgs}=await import('node:util');
+  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] === 'agent-channel') {
   await import('./agent-channel.mjs');
 } else {

package/board/agent-declarations.mjs

@@ -2,7 +2,7 @@
 // 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 { event, json, tx, view } from './store.mjs';
+import { cardHandleOf, readableIdOf, event, json, tx, view } from './store.mjs';
 import { workflowFor } from './workflow.mjs';
 import { cardAgentFacts, cardAgentReceiptRecorded, syncCardAgentScope } from './published.mjs';
 
@@ -13,7 +13,7 @@ function admitsScope(board,target,org){
 }
 
 export async function declareCardAgentEffect(board,effect) {
-  const task=view(board,db=>db.prepare('SELECT t.*,c.subtask_of,c.archived,c.sponsor FROM tasks t JOIN supercode_cards c ON c.task_id=t.id WHERE t.id=?').get(effect.id));
+  const task=view(board,db=>db.prepare('SELECT t.*,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||task.subtask_of)return true;
   const entry=workflowFor(board.root),profile=task.assignee??effect.profile??entry.params.default_assignee;
   // The reasons already told since the card's last declaration: each is recorded once, so a retry that alternates
@@ -28,7 +28,7 @@ export async function declareCardAgentEffect(board,effect) {
     org=scope.org;
     if(!admitsScope(board,effect.id,org))return true;
     const options={root:board.root,org:scope.org,server:scope.server,profiles:entry.profiles,
-      profile,card:effect.id,role:effect.role,sponsor:task.sponsor??null,context,starterSession:effect.starter_session};
+      profile,card:effect.id,handle:cardHandleOf(board,effect.id),readableId:readableIdOf(board,effect.id),role:effect.role,context,starterSession:effect.starter_session};
     const agent=await localCardAgent(options);
     if(task.archived||['done','cancelled','archived'].includes(task.status))finishAgentAssignment(board.root,scope.org,agent.assignment,`card ${effect.id} ${task.status}`);
     // A daemon not running keeps the declaration here; every delivery pass hands it on again.

package/board/args.mjs

@@ -1,8 +1,8 @@
 // A workflow verb's arguments, as the CLI and the board's owner both read them.
 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',
+export const MULTI = new Set(['parent', 'skill', 'worker', 'child', 'ids', 'rm', 'tag', 'pr', 'pr-head', 'reviewed-sha', 'finding', 'source']);
+export const FLAGS = new Set(['json', 'triage', 'no-notify', 'no-start', 'all', 'force', 'help', 'mine', 'archived', 'subtasks', 'reclaim', 'dry-run',
   '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']);

package/board/card-state.mjs

@@ -0,0 +1,29 @@
+// Native workflows declare orthogonal holds; Hermes declares lifecycle blocks.
+// Readers must use the declaring workflow, including for legacy stored rows.
+const parse = (value, fallback) => {
+  if (typeof value !== 'string') return value ?? fallback;
+  try { return JSON.parse(value) ?? fallback; } catch { return fallback; }
+};
+
+// The aliases belong to the board's task listings. Use the same hold precedence
+// in SQL filters as in row projection, including a legacy blocked storage row.
+export const cardStateSql = ({ nativeHolds = false } = {}) => nativeHolds ? `CASE
+  WHEN COALESCE(c.stage,t.status) IN ('done','cancelled','archived') OR t.status = 'archived' THEN t.status
+  WHEN c.paused IS NOT NULL AND c.paused != 'null' THEN 'paused'
+  WHEN CASE WHEN json_valid(c.blocked_by) THEN json_array_length(c.blocked_by) ELSE 0 END > 0 THEN 'blocked'
+  WHEN t.status IN ('paused','blocked') THEN CASE WHEN COALESCE(c.stage,t.status) IN ('paused','blocked') THEN 'todo' ELSE COALESCE(c.stage,t.status) END
+  ELSE t.status END` : 't.status';
+
+export function cardState(task, { nativeHolds = false } = {}) {
+  const paused = parse(task.paused, null);
+  const blocked_by = parse(task.blocked_by, []);
+  const lane = task.stage ?? task.workflow_status ?? task.status;
+  const ended = ['done', 'cancelled', 'archived'].includes(lane) || task.status === 'archived';
+  const status = !nativeHolds ? task.status : ended ? task.status : paused ? 'paused' : blocked_by.length ? 'blocked'
+    : task.status === 'blocked' || task.status === 'paused' ? (['blocked', 'paused'].includes(lane) ? 'todo' : lane) : task.status;
+  return { ...task, status, paused, blocked_by };
+}
+
+export const holdDescription = (task) => task.status === 'paused' && task.paused
+  ? `paused by ${task.paused.by ?? 'unknown'}: ${task.paused.reason ?? 'reason not recorded'}`
+  : task.status === 'blocked' && task.blocked_by?.length ? `blocked by ${task.blocked_by.map(b => `${b.id}${b.reason ? `: ${b.reason}` : ''}`).join(', ')}` : null;

package/board/ci.mjs

@@ -8,6 +8,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import { branchCheckouts, checkoutOf, isLocalWorkspace, resolveWorkspace, plainWorkspace } from './workspace.mjs';
 import { noteStep } from '@volter/supercode-harness-sdk/slow-log';
 import { githubFetch } from './github-rest.mjs';
+import { cardHandleOf } from './store.mjs';
 
 // GitHub is read through its REST API with Node's own fetch, in this process and awaited (never a child the caller
 // waits on synchronously): Node takes a World's trust bundle and injector (NODE_EXTRA_CA_CERTS, NODE_OPTIONS), so a
@@ -285,8 +286,10 @@ const originOf = async (path) => /(?:github\.com[:/])([^/]+\/[^/]+?)(?:\.git)?$/
 async function repositoryWorkspace(board, id) {
   const task = board.db.prepare('SELECT t.*,c.subtask_of,c.workspace_anchor,c.machine FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.id=?').get(id);
   const parent = task?.subtask_of && board.db.prepare('SELECT t.*,c.workspace_anchor,c.machine FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.id=?').get(task.subtask_of);
-  const workspace = task?.workspace_kind === 'scratch' ? parent : task;
-  if (!workspace || workspace.workspace_kind === 'scratch') return null;
+  const owner = task?.workspace_kind === 'scratch' ? parent : task;
+  if (!owner || owner.workspace_kind === 'scratch') return null;
+  // 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 (workspace.workspace_anchor) {
     // A portable remote declaration supplies the source identity. Reviewing
@@ -371,17 +374,31 @@ function registeredBranches(board, id) {
     if (!row.workspace_anchor || /^(\/|~|[A-Za-z]:[\\/])/.test(row.workspace_anchor)) continue;
     out.push({ repository: row.workspace_anchor.replace(/^github\.com\//i, '').replace(/\.git$/, ''), branch: row.branch_name });
   }
+  // and each repository and branch the arc declared as its own (arcSources)
+  for (const declared of arcSources(board.db, id)) if (!out.some((r) => r.repository.toLowerCase() === declared.repository.toLowerCase() && r.branch === declared.branch)) out.push(declared);
   return out;
 }
 
-/** Whether `head` is a branch named for card `id`: `wt/<id>` (or `wt/t-…`), alone or with a `-…`/`/…` suffix. */
+/** The repositories and branches the arc itself declares it changes: its latest `comment --source owner/repo:branch`
+ *  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);
+  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 }));
+}
+
+/** Legacy branches carry the globally unique native id. Keyed handles are local to a board, so their branches
+ *  count only by exact recorded repository/branch identity (openReviewPullRequests), never by a handle prefix. */
 export const namedWorkBranch = (id, head) => [`wt/${id}`, `wt/${id.replace(/^t_/, 't-')}`].some((prefix) => head === prefix || head.startsWith(`${prefix}-`) || head.startsWith(`${prefix}/`));
 
-/** The branch names an arc declares as its work: its own and its subtasks' `--branch`, and each branch its latest
- *  review request covered. With `namedWorkBranch`, these are the branches its PRs are opened from. */
+/** 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);
+  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 = [];
   try { reviewed = candidatePullRequests(row && JSON.parse(row.payload)?.ci).map((p) => p.branch); } catch { /* an unreadable payload names none */ }
@@ -405,6 +422,7 @@ export async function openReviewPullRequests(board, id, { fresh = false } = {})
   const mine = (repository, head) => (repository === ownRepository && head === branch) || namedWorkBranch(id, head)
     || registered.some((r) => r.repository === repository && r.branch === head);
   const repositoriesToRead = [...new Set([ownRepository, ...registered.map((r) => r.repository), ...(await knownRepositories({ fresh }))].filter(Boolean))];
+  const answered = answeredChanges(board, id);
   const groups = await readTogether(repositoriesToRead, async repository => {
     const prs = [];
     const hasWorkBranches = repository === ownRepository || registered.some(r => r.repository === repository);
@@ -441,11 +459,12 @@ export async function openReviewPullRequests(board, id, { fresh = false } = {})
       ...(repository === ownRepository ? branch ? [branch] : [`wt/${id}`, `wt/${id.replace(/^t_/, 't-')}`] : []),
       ...registered.filter(r => r.repository === repository).map(r => r.branch),
     ])];
+    // A judged merged head is passed over, except while an answered changes-requested verdict makes it due again.
     const histories = await readTogether(historical, async headBranch => {
       if (headBranch === list.defaultBranch || list.items.some(pr => pr.headRefName === headBranch)) return [];
       return (await mergedBranchPullRequests(repository, headBranch, { fresh })).filter(pr =>
         !pr.isCrossRepository && pr.headRefName === headBranch && pr.headRefName !== pr.defaultBranch
-        && pr.baseRefName === pr.defaultBranch && !judgedHead(board, id, pr.headRefOid));
+        && 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 });
@@ -454,8 +473,8 @@ export async function openReviewPullRequests(board, id, { fresh = false } = {})
   });
   const prs = groups.flat();
   // A source declaration (an implementer's or manager's card comment, engine.comment) adds merged or moved PRs that
-  // discovery cannot see; it never hides what discovery found. Only repositories the card's workspace or registered
-  // branches name count, and each declared PR is followed at its current head (GitHub's), never pinned to the
+  // discovery cannot see; it never hides what discovery found. Only repositories the card's workspace, its declared
+  // sources or its tasks' registered branches name count, and each declared PR is followed at its current head (GitHub's), never pinned to the
   // declared one, so a push after the declaration is reviewed instead of failing every tick.
   const declaration = board.db.prepare("SELECT payload FROM task_events WHERE task_id=? AND kind='commented' AND json_type(payload,'$.sources')='array' ORDER BY id DESC LIMIT 1").get(id);
   const repositories = new Set([ownRepository, ...registered.map((r) => r.repository)].filter(Boolean).map((r) => r.toLowerCase()));
@@ -475,6 +494,8 @@ export async function noCodeChange(board, id) {
   const taskRow = board.db.prepare('SELECT workspace_kind FROM tasks WHERE id=?').get(id);
   if (taskRow?.workspace_kind === 'scratch') {
     if (board.db.prepare("SELECT 1 FROM tasks t JOIN supercode_cards c ON c.task_id=t.id WHERE c.subtask_of=? AND t.workspace_kind!='scratch' AND t.status!='cancelled' LIMIT 1").get(id)) return null;
+    // a scratch arc that declares repositories it changes carries code, never a disposition
+    if (arcSources(board.db, id).length) return null;
     // Scratch declares an operational disposition rather than repository code.
     // Closed tasks/results and the retained card thread are the review source;
     // this does not invent a verdict or assert that an external act succeeded.
@@ -509,14 +530,24 @@ async function knownRepositories({ fresh = false } = {}) {
   catch (error) { if (fresh) throw error; return []; }
 }
 
-/** Whether the arc's open PRs (`[{ url, head }]`) call for its review: some head no verdict judged that is new work.
- *  Before any verdict every unjudged head is. After a verdict, a PR it judged with a new head is, and so is a head
- *  committed after that verdict (a new PR carrying the fixes, or any PR after a verdict that named none). After changes
- *  are requested, a PR that joins with a head committed before the verdict is not: the next run is the implementer's
- *  until it pushes. After a pass nothing is owed by the implementer, so a PR that verdict's request did not name is due
- *  at whatever head it has: one that was a draft or stacked on another PR's branch when the request was made, and
- *  became the arc's once that PR merged (t_bbbd2086's #1355, committed 2 h before the pass that named only #1353). */
+/** Whether the arc's open PRs (`[{ url, head }]`) call for its review: its last verdict's findings are answered, or
+ *  some head no verdict judged is new work.
+ *  After changes are requested, the verdict is answered once every task it owns has been closed (`answeredChanges`):
+ *  its review is due again at whatever heads the PRs have, the same ones included, since a finding about evidence (a
+ *  recording, a card comment) is answered without a commit (VO-2858 t_cc590655: its one finding, t_95c21edb, was closed
+ *  at 22:08Z on 2026-10-17 with all three heads unchanged, and the arc waited on "push a commit" until the manager's
+ *  reopen_review).
+ *  Before any verdict every unjudged head is new work. After a verdict, a PR it judged with a new head is, and so is a
+ *  head committed after that verdict (a new PR carrying the fixes, or any PR after a verdict that named none). After
+ *  changes are requested, a judged PR's new head whose source tree is the one the verdict judged is not new work (an
+ *  empty commit answers nothing: VO-2858's 59f38683 carried db7d19a0's tree and was requested at once), and a PR that
+ *  joins with a head committed before the verdict is not: the next run is the implementer's until it answers. After a
+ *  pass nothing is owed by the implementer, so any new head of a PR it judged is due (acceptance needs the verdict on
+ *  the current heads), and a PR that verdict's request did not name is due at whatever head it has: one that was a draft
+ *  or stacked on another PR's branch when the request was made, and became the arc's once that PR merged (t_bbbd2086's
+ *  #1355, committed 2 h before the pass that named only #1353). */
 export async function reviewDue(board, id, prs) {
+  if (prs.length && answeredChanges(board, id)) return true;
   const unjudged = prs.filter((p) => !judgedHead(board, id, p.head));
   if (!unjudged.length) return false;
   const voided = board.db.prepare("SELECT r.payload FROM task_events v JOIN task_events r ON r.id=json_extract(v.payload,'$.review_request') AND r.task_id=v.task_id WHERE v.task_id=? AND v.kind='review_voided' ORDER BY v.id DESC LIMIT 1").get(id);
@@ -530,23 +561,50 @@ export async function reviewDue(board, id, prs) {
     ORDER BY r.id DESC LIMIT 1`).get(id);
   if (!last) return true;
   const judged = candidatePullRequests(JSON.parse(last.payload)?.ci);
-  if (judged.some((j) => prs.some((p) => p.url === j.pr.url && p.head !== j.commit))) return true;
-  if (last.verdict === 'review_pass' && unjudged.some((p) => !judged.some((j) => j.pr.url === p.url))) return true;
-  for (const p of unjudged) if ((await commitTime(p)) > Number(last.verdict_at)) return true;
+  const judgedOf = (p) => judged.find((j) => j.pr.url === p.url) ?? null;
+  for (const p of prs) {
+    const j = judgedOf(p);
+    if (!j || p.head === j.commit) continue;
+    if (last.verdict === 'review_pass' || !await sameTree(p, j.commit)) return true;
+  }
+  if (last.verdict === 'review_pass' && unjudged.some((p) => !judgedOf(p))) return true;
+  // a PR the verdict judged was answered above, by its tree; any other is new work when committed after the verdict
+  for (const p of unjudged) if (!judgedOf(p) && (await commitTime(p)) > Number(last.verdict_at)) return true;
   return false;
 }
 
-const commitTimes = new Map();
-/** Cache successful immutable commit dates only. An unread date is unknown, never evidence of old work. */
-async function commitTime({ url, head }) {
-  const key = `${githubBase()}\0${repositoryOf(url)}\0${head}`;
-  if (commitTimes.has(key)) return commitTimes.get(key);
-  const at = Math.floor(Date.parse((await github(`/repos/${repositoryOf(url)}/commits/${head}`)).commit?.committer?.date) / 1000);
-  if (!Number.isFinite(at)) throw new Error(`GitHub commit date for ${url} at ${head} is unreadable; review eligibility is unknown`);
-  commitTimes.set(key, at);
-  return at;
+/** Whether the arc's last review event is changes requested and every task that verdict owns is closed now. A verdict
+ *  owns the tasks filed or reopened between the request it answered and itself (`request-changes --finding` files each
+ *  finding as a task just before the verdict; a reviewer may reopen one instead). A verdict that owns no task is never
+ *  answered this way: only a new head is. Task state is read as every board reader reads it (statusOf: the card's
+ *  workflow stage over its stored status). */
+export function answeredChanges(board, id) {
+  const db = board.db;
+  const verdict = db.prepare("SELECT id, 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);
+  if (verdict?.kind !== 'changes_requested') return false;
+  const asked = db.prepare("SELECT MAX(id) AS id FROM task_events WHERE task_id = ? AND kind = 'review_requested' AND id < ?").get(id, verdict.id)?.id ?? 0;
+  const owned = db.prepare(`SELECT COALESCE(c.stage, t.status) AS status FROM supercode_cards c JOIN tasks t ON t.id = c.task_id
+    WHERE c.subtask_of = ? AND EXISTS (SELECT 1 FROM task_events e WHERE e.task_id = c.task_id AND e.kind IN ('created', 'reopened') AND e.id > ? AND e.id < ?)`).all(id, asked, verdict.id);
+  return owned.length > 0 && owned.every((t) => ['done', 'cancelled', 'archived'].includes(t.status));
 }
 
+const commitReads = new Map();
+/** A commit's date and source tree, read once: both are immutable. Only a successful read is cached; an unread commit
+ *  is unknown, never evidence of old work or of a changed tree. */
+async function commitRead({ url, head }) {
+  const key = `${githubBase()}\0${repositoryOf(url)}\0${head}`;
+  if (commitReads.has(key)) return commitReads.get(key);
+  const commit = (await github(`/repos/${repositoryOf(url)}/commits/${head}`)).commit;
+  const at = Math.floor(Date.parse(commit?.committer?.date) / 1000), tree = commit?.tree?.sha;
+  if (!Number.isFinite(at) || typeof tree !== 'string' || !tree) throw new Error(`GitHub commit ${head} of ${url} is unreadable; review eligibility is unknown`);
+  const read = { at, tree };
+  commitReads.set(key, read);
+  return read;
+}
+const commitTime = async (p) => (await commitRead(p)).at;
+/** Whether the PR's head carries the same source tree as `commit` of the same PR. */
+const sameTree = async (p, commit) => (await commitRead(p)).tree === (await commitRead({ url: p.url, head: commit })).tree;
+
 /** A cached exclusion must never hide a newly ready/reopened source from a committed review or acceptance. */
 async function requireCurrentReviewSet(board, id, urls) {
   const current = await openReviewPullRequests(board, id, { fresh: true });
@@ -620,7 +678,7 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
       const registered = registeredBranches(board, id);
       const declared = (pr) => namedWorkBranch(id, pr.headRefName) || registered.some((r) => r.branch === pr.headRefName && r.repository.toLowerCase() === repositoryOf(pr.url).toLowerCase());
       const stray = read.find((pr) => pr.state !== 'MERGED' && !declared(pr));
-      if (stray) throw new Error(`An unmerged PR candidate needs a repository workspace: ${stray.url} (${stray.headRefName}) is on no branch the card or its tasks declare; register it with create "<what>" --subtask-of ${id} --workspace worktree:${repositoryOf(stray.url)} --branch ${stray.headRefName}`);
+      if (stray) throw new Error(`An unmerged PR candidate needs a repository workspace: ${stray.url} (${stray.headRefName}) is on no branch the card or its tasks declare; declare it on the arc: comment ${id} "<why>" --source ${repositoryOf(stray.url)}:${stray.headRefName} (with every other source the arc changes)`);
     }
     // A verdict with no requested PR (a scratch arc) keeps its own contract. An arc's review
     // always names every opened PR it changed, independent of deployment.
@@ -635,7 +693,7 @@ async function inspectCurrentCompletionEvidence(board, id, entry, payload, stage
     const prs = await mapGithubSources(urls, (url, index) => verifyPullRequest(board, id, entry, own, url, stage === 'request_review' ? named[index] : null, stage, read[index]));
     if (stage === 'request_review') {
       // A review is asked for only while some PR has a head no verdict has judged.
-      if (!await reviewDue(board, id, prs.map((p) => ({ url: p.pr.url, head: p.commit })))) throw new Error('The PRs the last verdict judged have no new head; push a new head before requesting review.');
+      if (!await reviewDue(board, id, prs.map((p) => ({ url: p.pr.url, head: p.commit })))) throw new Error('Every PR head has a verdict, carries the source tree its verdict judged, or predates it: push a commit that changes the source, or close the tasks that own the last verdict\'s findings, before requesting review.');
     } else if (asked) {
       const requested = candidatePullRequests(asked);
       if (requested.length !== prs.length || requested.some((r) => !prs.some((p) => p.pr.url === r.pr.url && p.commit === r.commit))) throw new Error('The verdict covers the requested PRs at their requested heads; a PR whose head moved needs a new review request.');