@volter/supercode-orchestrator 0.5.228 → 0.5.230

package/bin/connection-runner.mjs

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import { registerWorkService, closeWorkLedger, stopWorkChild } from '@volter/supercode-harness-sdk/work-ledger';
+import { registerWorkOperations, measureWork } from "@volter/supercode-harness-sdk/work-ledger";
+registerWorkOperations([{"kind":"pass","operation":"connection.alerts"},{"kind":"pass","operation":"connection.renew"}]);
 // The home's installed-app runner owns only children it starts, and every connection keeps separate custody.
 import { existsSync, openSync, closeSync, readFileSync, realpathSync, rmSync, unlinkSync, renameSync } from 'node:fs';
 import { dirname, join } from 'node:path';
@@ -6,7 +9,7 @@ import { fileURLToPath } from 'node:url';
 import { spawn } from 'node:child_process';
 import { parseArgs } from 'node:util';
 import { readSourceLock, sourceRoot } from '@volter/supercode-teams/source-lock';
-import { SERVICE_APPS, SERVICE_PROGRAM, connectionCall, connectionCanRun, connectionPath, generateModuleConfig, privateJson, runnerStopPath, stopConnectionRunner } from '../connection.mjs';
+import { boardAppPrincipals, SERVICE_APPS, SERVICE_PROGRAM, connectionCall, connectionCanRun, connectionPath, generateModuleConfig, privateJson, runnerStopPath, stopConnectionRunner } from '../connection.mjs';
 
 const {values}=parseArgs({options:{root:{type:'string'},connection:{type:'string'}}});
 const path=connectionPath(values.root,values.connection),lock=join(dirname(path),'runner.lock'),stopFile=runnerStopPath(lock);
@@ -21,8 +24,10 @@ function serving(){
   if(!declared)return true;
   try{return realpathSync(declared.root)===tree;}catch{return false;}
 }
-let record=JSON.parse(readFileSync(path,'utf8'));
+// The record's text as this runner last read or wrote it: a save that would write the same text writes nothing.
+let written=readFileSync(path,'utf8'),record=JSON.parse(written);
 record.root=values.root;
+registerWorkService({role:'connection-runner',scope:{kind:'install',id:`${values.root}\0${record.id}`}});
 if(!connectionCanRun(record))process.exit(0);
 if(existsSync(lock)){
   const previous=JSON.parse(readFileSync(lock,'utf8'));
@@ -35,23 +40,38 @@ if(existsSync(lock)){
     log('runner-handover',{predecessor:previous.pid,from:previous.tree??null,to:tree});
     // Never ended alone: its modules would outlive it with nobody stopping them. The next gateway start asks again.
     if(!await stopConnectionRunner(lock,previous)){log('runner-handover-refused',{predecessor:previous.pid,reason:'predecessor did not stop within 20s'});process.exit(1);}
-    record=JSON.parse(readFileSync(path,'utf8'));record.root=values.root;
+    written=readFileSync(path,'utf8');record=JSON.parse(written);record.root=values.root;
     if(!connectionCanRun(record))process.exit(0);
   }
   if(existsSync(lock))renameSync(lock,`${lock}.stopped-${Date.now()}`);
 }
 const fd=openSync(lock,'wx',0o600);closeSync(fd);privateJson(lock,{pid:process.pid,connection:record.id,tree});
 rmSync(stopFile,{force:true});
-const children=new Map(),health=record.health??={},raised=record.raised??{};
+// The record keeps live alert state only (ADR 0032: conditions are raised and cleared as RH2 alerts). `raised` holds an
+// alert this runner raised and has not yet cleared (its reason a string or an HTTP status). `health` holds a condition
+// that is unavailable, from the event that issues it, with its reason and the time it was first issued for that reason,
+// and a recovered one (`state:'current'`) only while its alert is still up, so any runner that walks `health` (as
+// earlier ones do) clears it; once the clear is answered both leave (syncAlerts). A card's obligation is so kept exactly
+// while its projection is pending or its alert is up. What an earlier runner kept beyond that (a recovered condition
+// with no alert up, a cleared null alert) is dropped as read.
+const children=new Map(),
+  raised=Object.fromEntries(Object.entries(record.raised??{}).filter(([,reason])=>reason!=null)),
+  health=Object.fromEntries(Object.entries(record.health??{}).filter(([name,state])=>state?.state==='unavailable'||state?.state==='current'&&Object.hasOwn(raised,name)));
 let stopped=false;
-const save=()=>{record.health=health;record.raised=raised;privateJson(path,record);};
+const save=()=>{record.health=health;record.raised=raised;written=privateJson(path,record,written);};
 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();};
+const issue=(name,reason)=>{if(health[name]?.reason===reason)return;health[name]={state:'unavailable',reason,at:new Date().toISOString()};save();};
+const recover=name=>{
+  if(Object.hasOwn(raised,name)){if(health[name]?.state==='current')return;health[name]={state:'current',at:new Date().toISOString()};}
+  else if(Object.hasOwn(health,name))delete health[name];
+  else return;
+  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(grant.disabled)return;
   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);
@@ -79,21 +99,29 @@ function start(grant){
 }
 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();});});
+  child.removeAllListeners('exit');stopWorkChild(child, () => child.kill('SIGTERM'), { signal: 'SIGTERM' });
+  await new Promise(done=>{const timer=setTimeout(()=>{stopWorkChild(child, () => child.kill('SIGKILL'), { signal: 'SIGKILL' });done();},5000);child.once('exit',()=>{clearTimeout(timer);done();});});
 }
 async function syncAlerts(){
+    return measureWork("pass", "connection.alerts", async () => {
   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;
+  // Every condition still unavailable and every alert still up: an alert whose condition recovered is cleared.
+  for(const name of new Set([...Object.keys(health),...Object.keys(raised)])){
+    const key=`connection.${record.id}.${name}`.slice(0,200),wanted=health[name]?.state==='unavailable'?health[name].reason:null;
+    if((raised[name]??null)===wanted)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();
+      // A clear answered retires both; a raise whose condition recovered while it was asked keeps a current entry beside it.
+      if(wanted===null){delete raised[name];if(health[name]?.state==='current')delete health[name];}
+      else{raised[name]=wanted;health[name]??={state:'current',at:new Date().toISOString()};}
+      save();
     }catch(error){log('connection-alert-pending',{module:grant.name,code:error.code??error.status??'unavailable'});}
   }
-}
+
+
+    });
+  }
 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;
@@ -113,16 +141,21 @@ async function renewTeams(value){
 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(){
+    return measureWork("pass", "connection.renew", async () => {
   const restart=new Set();
   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(Date.parse(grant.rh2.expiresAt)-Date.now()<=7*86400000){
+        const renewed=(await connectionCall(record,'rh2','POST',`/api/v3/automation/installations/${grant.rh2.installationId}/renew`,{},grant.rh2.accessToken)).data;
+        if(renewed.installationId!==grant.rh2.installationId||renewed.principalId!==grant.rh2.principalId)throw new Error('renewal changed its consented installation or principal');
+        grant.rh2={...grant.rh2,...renewed};delete grant.disabled;changed=true;save();
+      }
       if(grant.teams)changed=await renewTeams(grant.teams)||changed;
       if(changed)restart.add(childOf(grant));
       if(!grant.teams?.pendingRenewal)recover(`expiry.${grant.name}`);
-    }catch(error){issue(`expiry.${grant.name}`,error.code??'renewal-unavailable');}
+    }catch(error){if(error.status===401||error.code==='installation-unknown'){grant.disabled=true;await stopChild(childOf(grant));save();}issue(`expiry.${grant.name}`,error.code??'renewal-unavailable');}
   }
   // A renewed credential reaches its program by a restart with a regenerated config (the service's, for its registrations):
   // once per pass, however many of the program's registrations renewed in it.
@@ -131,12 +164,15 @@ async function renew(){
   // deployment's (connection.mjs adoptWorkplaceService).
   if(!record.issuerCredential)return;
   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());
 // Windows delivers no SIGTERM to a handler: a successor or a disconnect asks this runner to stop through its stop file.
 setInterval(()=>{try{if(JSON.parse(readFileSync(stopFile,'utf8')).pid===process.pid)void stop();}catch{}},500).unref();
 for(const grant of record.grants)start(grant);
-let lastRenew=0;
+let lastRenew=0, boardAppsWritten=JSON.stringify(boardAppPrincipals(values.root,record));
 // Teams verifies the Workplace's tokens against its own JWKS (ADR 0070): nothing is relayed for them here.
 while(!stopped){
   try{
@@ -145,8 +181,13 @@ while(!stopped){
     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();}
+    const boardApps=JSON.stringify(boardAppPrincipals(values.root,record));
+    if(boardApps!==boardAppsWritten){
+      const agents=installed.find(grant=>grant.name==='agents');
+      if(agents){await stopChild(agents.name);start(agents);boardAppsWritten=boardApps;log('board-handover-config-changed');}
+    }
     recover('issuer');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);rmSync(stopFile,{force:true});process.exit(0);}
+async function stop(){if(stopped)return;stopped=true;await Promise.all([...children.keys()].map(stopChild));record.stoppedAt=new Date().toISOString();save();unlinkSync(lock);rmSync(stopFile,{force:true});await closeWorkLedger();process.exit(0);}

package/bin/hermes-worker.mjs

@@ -2,9 +2,10 @@
 // The command the board's dispatcher runs as a headless profile's worker (docs/plans/hermes-compat.md row 14):
 // Hermes's own worker argv and environment; see `kanban-worker.mjs`.
 import { runKanbanWorker } from '../kanban-worker.mjs';
+import { currentRelease } from '@volter/teams/stable-release';
 
 // Hermes watches this pid: it exits the moment the turn is over, whatever handle is still open.
-process.exit(await runKanbanWorker(process.argv.slice(2), process.env).catch((error) => {
+process.exit(await runKanbanWorker(process.argv.slice(2), process.env, currentRelease).catch((error) => {
   process.stdout.write(`hermes-worker: ${error.stack ?? error.message}\n`);
   return 1;
 }));

package/bin/orchestrator.mjs

@@ -15,9 +15,9 @@ try { ({ lockedProgram } = await import('../source-lock.mjs')); }
 catch (error) { process.stderr.write(`${error.message}\n`); process.exit(1); }
 // Any command on a home whose record names another orchestrator is that orchestrator's (hand-off.mjs).
 if (process.argv[2] !== 'workflow' && !(typeof process.send === 'function' && Number(process.env.SUPERCODE_BOARD_GENERATION_OWNER) === process.ppid)) {
-  const { handOff, homeOfArgs } = await import('../hand-off.mjs');
+  const { handOff, homeOfArgs } = await import('../hand-off.mjs'); const { enforceSourceLock } = await import('@volter/supercode-teams/source-lock');
   let handed;
-  try { handed = handOff(homeOfArgs(process.argv.slice(2)), process.argv.slice(2)); }
+  try { handed = handOff(homeOfArgs(process.argv.slice(2)), process.argv.slice(2), enforceSourceLock); }
   catch (error) { process.stderr.write(`supercode ${process.argv[2] ?? ''}: ${error.message}\n`); process.exit(1); }
   if (handed !== null) process.exit(await handed);
 }
@@ -33,7 +33,7 @@ if (process.argv[2] === 'workflow') {
   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));
   let code=0;
-  try {code=await runWorkflow(process.argv.slice(3));}
+  try {code=await runWorkflow(process.argv.slice(3),{serveBoardOwner:async(root,args,firstReaderEpoch)=>(await import('../board/generation-owner.mjs')).serveBoardOwner(root,args,firstReaderEpoch)});}
   // 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) {noteCommandError(error);process.stderr.write(`supercode workflow: ${error.message??error}\n${error?.errcode!=null&&error.stack?`${error.stack}\n`:''}`);code=1;}

package/bin/runtime.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { stopWorkChild } from '@volter/supercode-harness-sdk/work-ledger';
 // The orchestrator daemon entry (ORC-7).
 //
 //   node bin/orchestrator.mjs --root <home> [--once]
@@ -492,7 +493,7 @@ async function appsMain(argv) {
       process.exit(127);
     }
     const child = spawn(program, ['mcp'], { stdio: 'inherit', env: { ...process.env, ...rh2AgentEnv(record, home) } });
-    for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(signal, () => child.kill(signal));
+    for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(signal, () => stopWorkChild(child, () => child.kill(signal), { signal: signal }));
     child.on('error', (error) => { process.stderr.write(`apps mcp: ${error.message}\n`); process.exit(127); });
     child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
     return;
@@ -707,7 +708,7 @@ async function main() {
   // when its command line is a gateway's (hermes-locks.mjs). A launcher that did not name it so is re-run as it.
   if (!args.once && basename(process.argv0) !== GATEWAY_KIND) {
     const child = spawn(process.execPath, process.argv.slice(1), { argv0: GATEWAY_KIND, stdio: 'inherit', env: process.env });
-    for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(signal, () => child.kill(signal));
+    for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(signal, () => stopWorkChild(child, () => child.kill(signal), { signal: signal }));
     child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
     return;
   }

package/board/agent-current.mjs

@@ -0,0 +1,82 @@
+// Current delivery obligations, reconstructed from the board after restart. Successful ended
+// records leave pending; changed board/agent identities put only their references back in it.
+import { setImmediate as yieldToOwner } from 'node:timers/promises';
+import { currentRecordChanges, currentRecordConnection } from './current-records.mjs';
+import { agentRecordChanges, cardAgentAssignments } from '../agents.mjs';
+import { json, RUN_AGENT_REF, runField, view } from './store.mjs';
+
+const held = new WeakMap();
+const FIELDS = ['session_id','address','machine','harness','surface','pane','pid','detached_at','agent_id','agent_org','mode','launch_key','launch_pending','launch_deferred'];
+const sessionSql = () => `json_object(${FIELDS.flatMap(name => [`'${name}'`,runField(name)]).join(',')})`;
+export function latestAgentRow(board, ref) {
+  return view(board, db => {
+    const row = db.prepare(`SELECT id,task_id,ended_at,${RUN_AGENT_REF} AS ref,${sessionSql()} AS session
+      FROM task_runs WHERE ${runField('agent_id')} IS NOT NULL AND ${RUN_AGENT_REF}=? ORDER BY id DESC LIMIT 1`).get(ref);
+    return row ? { ...row, session: json(row.session,{}) } : null;
+  });
+}
+const runtimeRef = row => row?.session.session_id ? `${row.session.harness}:${row.session.session_id}` : null;
+function retain(state, ref, row) {
+  const old = state.rows.get(ref);
+  if (old) {
+    state.tasks.get(old.task_id)?.delete(ref);
+    state.runtime.get(runtimeRef(old))?.delete(ref);
+  }
+  state.rows.delete(ref); state.credentials.delete(ref);
+  if (!row) { state.pending.delete(ref); return; }
+  state.rows.set(ref,row);
+  const tasks = state.tasks.get(row.task_id) ?? new Set(); tasks.add(ref); state.tasks.set(row.task_id,tasks);
+  const runtime = state.runtime.get(runtimeRef(row)) ?? new Set(); runtime.add(ref); state.runtime.set(runtimeRef(row),runtime);
+  if (!row.ended_at || row.session.detached_at) state.credentials.add(ref);
+  if (!old || old.id !== row.id || old.task_id !== row.task_id || old.ended_at !== row.ended_at
+    || JSON.stringify(old.session) !== JSON.stringify(row.session)) state.pending.add(ref);
+}
+/** Select/reconcile rows, not fleet/credential decisions; those are recomputed from live inputs. */
+export async function currentAgentWork(board) {
+  let state = held.get(currentRecordConnection(board.db));
+  const boardChange = currentRecordChanges(board.db,state?.boardToken);
+  const agentChange = agentRecordChanges(board.root,state?.agentToken);
+  if (!state || boardChange.reset) {
+    state = { rows: new Map(), tasks: new Map(), runtime: new Map(), pending: new Set(), credentials: new Set(), assignments: new Set(), usageDue: new Map() };
+    held.set(currentRecordConnection(board.db),state);
+    let cursor = null;
+    for (;;) {
+      const refs = view(board, db => db.prepare(`SELECT ${RUN_AGENT_REF} AS ref FROM task_runs
+        WHERE ${runField('agent_id')} IS NOT NULL${cursor === null ? '' : ` AND ${RUN_AGENT_REF}>?`}
+        GROUP BY ${RUN_AGENT_REF} ORDER BY ${RUN_AGENT_REF} LIMIT 32`).all(...(cursor === null ? [] : [cursor])));
+      for (const {ref} of refs) retain(state,ref,latestAgentRow(board,ref));
+      if (refs.length < 32) break;
+      cursor = refs.at(-1).ref; await yieldToOwner();
+    }
+    for (const assignment of cardAgentAssignments(board.root)) state.assignments.add(assignment.target);
+  } else {
+    for (const target of boardChange.cards) {
+      state.assignments.add(target);
+      const affected = new Set(state.tasks.get(target));
+      let cursor = null;
+      for (;;) {
+        const refs = view(board,db => db.prepare(`SELECT DISTINCT ${RUN_AGENT_REF} AS ref FROM task_runs
+          WHERE task_id=? AND ${runField('agent_id')} IS NOT NULL${cursor === null ? '' : ` AND ${RUN_AGENT_REF}>?`}
+          ORDER BY ${RUN_AGENT_REF} LIMIT 32`).all(target,...(cursor === null ? [] : [cursor])));
+        for (const {ref} of refs) affected.add(ref);
+        if (refs.length < 32) break;
+        cursor = refs.at(-1).ref; await yieldToOwner();
+      }
+      for (const ref of affected) retain(state,ref,latestAgentRow(board,ref));
+      await yieldToOwner();
+    }
+  }
+  if (agentChange.reset) {
+    for (const ref of state.rows.keys()) state.pending.add(ref);
+    for (const assignment of cardAgentAssignments(board.root)) state.assignments.add(assignment.target);
+  } else {
+    for (const ref of agentChange.sessions) for (const boardRef of state.runtime.get(ref) ?? []) state.pending.add(boardRef);
+    for (const target of agentChange.targets) state.assignments.add(target);
+  }
+  // Custody can retain credentials on an ended remote session even when its run predates the
+  // detached_at field. Only these retained addresses join the current credential candidates.
+  const custody = view(board,db => new Set(db.prepare('SELECT address FROM supercode_session_custody').all().map(row => row.address)));
+  for (const ref of custody) if (state.rows.has(ref)) state.credentials.add(ref);
+  state.boardToken = boardChange.token; state.agentToken = agentChange.token;
+  return state;
+}

package/board/agent-declarations.mjs

@@ -1,9 +1,10 @@
 // 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, renameCardAgent, finishAgentAssignment, cardAgentAssignments, cardAgentScopeTransition, pendingCardAgentChanges, acknowledgeCardAgentChanges, handOffAgents } from '../agents.mjs';
+import { agentScope, localCardAgent, renameCardAgent, finishAgentAssignment, cardAgentAssignments, cardRoleAssignment, cardAgentScopeTransition, pendingCardAgentChanges, acknowledgeCardAgentChanges, handOffAgents } from '../agents.mjs';
 import { cardHandleOf, readableIdOf, event, json, tx, view } from './store.mjs';
-import { workflowFor } from './workflow.mjs';
+import { requestSessionClose, workflowFor } from './workflow.mjs';
+import { authorizeAgentHandoff } from './session-continuity.mjs';
 import { cardAgentFacts, cardAgentReceiptRecorded, syncCardAgentScope } from './published.mjs';
 
 function admitsScope(board,target,org){
@@ -29,6 +30,8 @@ export async function declareCardAgentEffect(board,effect) {
     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,handle:cardHandleOf(board,effect.id),readableId:readableIdOf(board,effect.id),role:effect.role,context,starterSession:effect.starter_session};
+    const previous=cardAgentAssignments(board.root,effect.id).find(item=>item.org===scope.org&&item.id===cardRoleAssignment(effect.id,effect.role));
+    if(previous)options.existingAgent=previous.agent_id;
     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.
@@ -73,7 +76,11 @@ export function recordCardAgentChanges(board,target){
   const recorded=(db,change)=>cardAgentReceiptRecorded(db,target,change.receipt);
   if(missingScope||view(board,db=>changes.some(change=>!recorded(db,change))))tx(board,db=>{
     if(transition)syncCardAgentScope(db,target,transition);
-    for(const change of changes)if(!recorded(db,change)&&admitsScope(board,target,change.org))event(db,target,change.kind??'agent_assignment_reassigned',change);
+    for(const change of changes)if(!recorded(db,change)&&admitsScope(board,target,change.org)){
+      const source=event(db,target,change.kind??'agent_assignment_reassigned',change);
+      const assignment=cardAgentAssignments(board.root,target).find(item=>item.org===change.org&&item.id===change.assignment);
+      authorizeAgentHandoff(db,target,change,source,assignment,requestSessionClose);
+    }
   });
   acknowledgeCardAgentChanges(board.root,changes.map(change=>change.receipt));
 }

package/board/args.mjs

@@ -3,11 +3,131 @@ import { resolve } from 'node:path';
 
 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', 'plan']);
+  'once', 'goal', 'no-goal', 'off', 'switch', 'delete', 'no-attachments', 'include-logs', 'verbose', 'side', 'plan', 'attest-release']);
 // flags that take every following word up to the next flag (Hermes's nargs='+')
 export const GREEDY = new Set(['ids', 'rm']);
 
-export function parse(argv) {
+// These are the options the native verb actually reads, not every option another verb happens to know. Keep the
+// admission in the shared parser: both the caller and the serving generation must refuse before doing any work.
+// Workflow-declared event verbs and `goto` carry open payloads; their fields are consumed, not native CLI options.
+// `--break-glass "<reason>"` is every verb's: a card's session gives it to write outside its own card on purpose
+// (cli.mjs authorize), and it is never part of a verb's payload.
+const COMMON = new Set(['root', 'board', 'json', 'help', 'at', 'break-glass']);
+const NATIVE = new Map();
+const options = (verbs, names = '') => {
+  for (const verb of verbs.split(' ')) NATIVE.set(verb, new Set(names.split(' ').filter(Boolean)));
+};
+options('help declaration listeners context link unlink tag untag attachments attach-rm stats assignees capacity deliver compact repair resume start answer release close');
+options('events', 'after once');
+options('github-usage', 'since');
+options('init', 'backing document commit manager dispatching archive-max-lines archive-period');
+options('migrate', 'backing document status-map');
+options('create', 'body body-file assignee machine reviewer readable-id workspace branch parent priority tenant triage idempotency-key max-runtime max-retries skill model provider created-by no-start adopt every subtask-of initial-status project goal no-goal goal-max-turns tag requested-by request notify no-notify');
+options('swarm', 'readable-id worker verifier synthesizer tenant created-by priority idempotency-key');
+options('list ls', 'assignee mine status machine archived all subtasks tenant session workflow-template-id step-key tag sort backlog');
+options('show', 'state-type state-name all');
+options('usage', 'agent');
+options('brief', 'run');
+options('runs', 'state-type state-name');
+options('set', 'provider ids');
+options('set-model', 'provider');
+options('assign reassign', 'agent role');
+options('set-goal', 'goal-max-turns off ids');
+options('claim', 'ttl');
+options('reclaim return-review cancel dispatching', 'reason');
+options('pause', 'reason until');
+options('backlog', 'reason pause-revision');
+options('plan', 'reason');
+options('heartbeat', 'note until');
+options('comment', 'file max-len author pr pr-head source pr-disposition release-target reason released-artifact release-evidence attest-release');
+options('attach', 'upload name content-type author');
+options('attachment-read', 'offset length version');
+options('complete', 'summary result metadata commit pr pr-head reviewed-sha');
+options('person-done', 'person result-file result workplace-task');
+options('edit', 'result summary metadata');
+options('block', 'ids kind on waiting-on');
+options('schedule', 'ids');
+options('unblock', 'ids reason on waiting-on');
+options('request-review', 'summary reviewer metadata commit branch pr pr-head head plan force supersedes');
+options('request-changes', 'finding reviewer reason');
+options('reopen reopen-review', 'ids reason');
+options('promote', 'ids dry-run force');
+options('archive', 'reason rm');
+options('specify', 'all tenant readable-id title body body-file workspace branch machine author');
+options('decompose', 'all tenant child author');
+options('diagnostics diag', 'task severity');
+options('log', 'tail');
+options('tail watch', 'interval kinds assignee tenant');
+options('notify-subscribe', 'for-card address platform chat-id thread-id role user-id user-id-alt chat-type notifier-profile delivery-mode');
+options('notify-unsubscribe', 'for-card address platform chat-id thread-id role');
+options('notify-list');
+options('dispatch', 'failure-limit max dry-run');
+options('daemon serve', 'interval max failure-limit pidfile verbose');
+options('gc', 'event-retention-days log-retention-days');
+options('run-session', 'harness task native-home');
+options('detach', 'to');
+options('adopt', 'side workspace assignee role');
+options('handover', 'action transaction entry supercode candidate release');
+NATIVE.set('goto', null);
+const BOARDS = new Map();
+const boardOptions = (actions, names = '') => {
+  for (const action of actions.split(' ')) BOARDS.set(action, new Set(names.split(' ').filter(Boolean)));
+};
+boardOptions('list ls', 'all');
+boardOptions('create new', 'name description icon color default-workdir switch backing document');
+boardOptions('rm remove delete', 'delete');
+boardOptions('switch use show current set-default-workdir');
+boardOptions('rename', 'name');
+boardOptions('export', 'output no-attachments include-logs');
+boardOptions('import', 'as switch');
+
+function nativeOptions(args) {
+  const [verb, action = 'list'] = args._;
+  if (verb === 'boards') {
+    if (!BOARDS.has(action)) throw new Error(`boards ${action}: list | create | rm | switch | show | rename | set-default-workdir | export | import`);
+    return { label: `boards ${action}`, allowed: BOARDS.get(action) };
+  }
+  if (verb === 'handover') {
+    const action = args.action ?? 'replace';
+    const allowed = action === 'status' ? 'action'
+      : ['prepare', 'replace'].includes(action) ? 'action transaction entry supercode candidate release' : 'action transaction';
+    return { label: `handover --action ${action}`, allowed: new Set(allowed.split(' ')) };
+  }
+  return { label: verb ?? 'help', allowed: NATIVE.get(verb ?? 'help') };
+}
+
+// Operator verbs act on the whole board and take no operand: a stray word (`dispatch status`) is retained as an
+// incomplete request naming it (ADR 0252), never dropped and run as the bare verb.
+const NO_OPERANDS = new Set(['dispatch', 'daemon', 'serve', 'gc', 'compact', 'repair']);
+
+function assertNativeOptions(args) {
+  const { label, allowed } = nativeOptions(args);
+  if (NO_OPERANDS.has(args._[0]) && args._.length > 1) throw new Error(`${label} takes no operand; \`${args._.slice(1).join(' ')}\` is not one of its options. Nothing was done.`);
+  if (allowed === undefined || allowed === null) return;
+  for (const key of Object.keys(args)) {
+    if (key !== '_' && !COMMON.has(key) && !allowed.has(key)) throw new Error(`${label} does not support --${key}. Nothing was done.`);
+  }
+  // Options read only by one branch of a native verb must not disappear in another branch either.
+  const unused = args._[0] === 'adopt' && args.side ? ['workspace', 'assignee', 'role']
+    : ['assign', 'reassign'].includes(args._[0]) && !args.agent ? ['role']
+      : args._[0] === 'comment' && args['pr-disposition'] ? ['released-artifact', 'release-evidence', 'attest-release']
+        : ['notify-subscribe', 'notify-unsubscribe'].includes(args._[0]) && args['for-card'] ? ['user-id', 'user-id-alt', 'chat-type', 'notifier-profile', 'delivery-mode'] : [];
+  if (args._[0] === 'notify-unsubscribe' && !args['for-card']) unused.push('role');
+  for (const key of unused) if (Object.hasOwn(args, key)) throw new Error(`${label} does not use --${key} with these options. Nothing was done.`);
+}
+
+/** The open payload door belongs only to events this home's workflow declares. Check before any board write. */
+export function assertWorkflowVerb(args, workflow) {
+  const [verb] = args._;
+  if (!verb || verb === 'boards' || NATIVE.has(verb)) return;
+  const name = verb.replace(/-/g, '_');
+  if (!Object.values(workflow?.statuses ?? {}).some(status => status.on?.[name])
+      && !workflow?.on?.[name] && !workflow?.verbs?.[name] && !workflow?.run?.on?.[name]) {
+    throw new Error(`no workflow verb ${verb}; \`supercode workflow help\` lists them`);
+  }
+}
+
+export function parse(argv, { contextOnly = false } = {}) {
   const out = { _: [] };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
@@ -16,23 +136,34 @@ export function parse(argv) {
     // reached the board as one word " --pr … --pr-head …" that a comment stored as its text (and `--file` dropped),
     // so its review was requested without two of its PRs.
     if (/^\s+--[A-Za-z]/.test(a) || (a.startsWith('--') && /\s/.test(a.slice(2).split('=')[0]))) {
+      if (contextOnly) continue;
       throw new Error(`One argument holds flags and their values together: ${JSON.stringify(a.length > 120 ? `${a.slice(0, 117)}...` : a)}. Pass each flag and each value as its own word (a shell variable holding several is split with \${=args} in zsh, or built as an array: "\${args[@]}" in bash). Nothing was done.`);
     }
     if (!a.startsWith('--') || a === '--') { out._.push(a); continue; }
     const [key, inline] = a.slice(2).split(/=(.*)/s);
+    if (key === '_') { if (contextOnly) continue; throw new Error('--_ is reserved for positional arguments. Nothing was done.'); }
     // init toggles document commits; completion/review names a git revision.
-    if (FLAGS.has(key) || (key === 'commit' && out._[0] === 'init')) { out[key] = true; continue; }
+    if (FLAGS.has(key) || (key === 'commit' && out._[0] === 'init')) {
+      if (inline !== undefined && !contextOnly) throw new Error(`--${key} takes no value. Nothing was done.`);
+      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]);
       (out[key] ??= []).push(...values);
       continue;
     }
-    const value = inline ?? argv[++i];
-    if (value === undefined) throw new Error(`--${key} needs a value`);
+    const value = inline !== undefined ? inline : argv[i + 1];
+    if (value === undefined || (inline === undefined && value.startsWith('--'))) {
+      out[key] = null;
+      continue;
+    }
+    if (inline === undefined) i++;
     if (MULTI.has(key)) (out[key] ??= []).push(value);
-    else out[key] = value;
+    else Object.defineProperty(out, key, { value, enumerable: true, writable: true, configurable: true });
   }
+  if (!contextOnly) assertNativeOptions(out);
   return out;
 }
 

package/board/call.mjs

@@ -20,7 +20,7 @@ import { generationWork } from './generation.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)
-const fresh = () => ({ actor: null, principal: null, roles: () => ['manager'], recorded: null, workflows: new Map(), agentMains: new Map(), said: new Set() });
+const fresh = () => ({ actor: null, principal: null, roles: () => ['manager'], recorded: null, workflows: new Map(), agentMains: new Map(), managerDeadline: null, managerUnread: null, said: new Set() });
 // the process's own context pins no workflow (it lives as long as the process): its reads always take the latest
 const unpinned = { get: () => undefined, set: () => {} };
 const own = { kind: 'own', caller: null, facts: process.env, ...fresh(), workflows: unpinned, get cwd() { return process.cwd(); }, get stdin() { return readFileSync(0, 'utf8'); }, out: (text) => process.stdout.write(text), err: (text) => process.stderr.write(text) };
@@ -28,6 +28,16 @@ const own = { kind: 'own', caller: null, facts: process.env, ...fresh(), workflo
 /** The call running now: a caller's verb in the owner, else the process's own. */
 export const current = () => calls.getStore() ?? own;
 
+/** The shared JSON answer for request receipts; each door selects the receipts its answer consumes. */
+export function requestReceiptEnvelope({ requests, accepted, queued, unqueued }) {
+  if (!requests.length && !accepted.length && !queued.length && !unqueued.length) return null;
+  if (unqueued.length) return { ok: false, disposition: 'not_queued', queued: false, reviews: unqueued };
+  const kinds = [requests.length && 'routed', queued.length && 'queued', accepted.length && 'recorded'].filter(Boolean);
+  return { ok: true, disposition: kinds.length === 1 ? kinds[0] : 'recorded',
+    ...(requests.length ? { requests } : {}), ...(queued.length ? { reviews: queued } : {}),
+    ...(accepted.length ? { accepted } : {}) };
+}
+
 /** 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, readOnly = false }, fn) {
   return calls.run({ kind: 'caller', caller, facts, ...fresh(), cwd, stdin, out, err, readOnly }, fn);
@@ -45,5 +55,10 @@ export function callerOf(call = current()) {
   return m ? { address: m[0], machine: m[1], harness: m[2], session: m[3] } : null;
 }
 
+/** An unread manager identity decides nothing (cli readAgentMains). A refusal for want of a role, asked by a session
+ *  that might be the manager whose main could not be read, stops with that identity error: never refused, routed to
+ *  the manager or granted by guess. A call that resolved to an allowed role never reaches this. */
+export function refuseUnreadManager(call = current()) { if (call.managerUnread) throw call.managerUnread; }
+
 /** Whether this is a caller's call in the owner rather than the process's own. */
 export const isCallersCall = () => calls.getStore()?.kind === 'caller';

package/board/caller-session.mjs

@@ -1,7 +1,9 @@
+import { measureSyncChild } from '@volter/supercode-harness-sdk/work-ledger';
+const spawnSync = (...args) => measureSyncChild(() => workLedgerNativeSpawnSync(...args));
 // The session this process runs in, as its own harness names it (Claude Code CLAUDE_CODE_SESSION_ID, Codex
 // CODEX_THREAD_ID). A pane inherits every variable the program that started its terminal server had, so a Codex pane
 // can carry a Claude session's id too: the nearest harness among the process's ancestors says which is its own.
-import { spawnSync } from 'node:child_process';
+import { spawnSync as workLedgerNativeSpawnSync } from 'node:child_process';
 import { basename } from 'node:path';
 
 export function processSession() {