@volter/supercode-orchestrator 0.5.228 → 0.5.229

package/connection.mjs

@@ -1,14 +1,20 @@
+import { stopWorkChild } from '@volter/supercode-harness-sdk/work-ledger';
+import { registerWorkOperations, measureWork } from "@volter/supercode-harness-sdk/work-ledger";
+registerWorkOperations([{"kind":"call","operation":"connection.http"}]);
+import { measureSyncChild } from '@volter/supercode-harness-sdk/work-ledger';
+const execFileSync = (...args) => measureSyncChild(() => workLedgerNativeExecFileSync(...args));
+const spawnSync = (...args) => measureSyncChild(() => workLedgerNativeSpawnSync(...args));
 // The kit's connection coordinator. Module manifests and programs belong to their application publisher.
 import { chmodSync, copyFileSync, existsSync, mkdirSync, openSync, closeSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { createHash, randomBytes } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { execFileSync, spawn, spawnSync } from 'node:child_process';
+import { execFile, execFileSync as workLedgerNativeExecFileSync, spawn, spawnSync as workLedgerNativeSpawnSync } from 'node:child_process';
 import { fromContext } from '@volter/teams/context';
 import { supercodeHome } from '@volter/teams/home';
 
 // RH2's modules, each its own program under --modules-root.
-export const MODULE_APPS = ['orchestration-rh2'];
+export const MODULE_APPS = ['orchestration-rh2', 'project-rooms'];
 // supercode's Workplace service's registrations (supercode ADR 0041 decision 3; runhuman-2 ADR 0055 decision 3): one program,
 // sdk/teams/workplace/main.mjs, hosts them all, each with its own credentials on both sides. Their manifests ship here, so an
 // organization's file selects them by these names and `rh2 apply-org` reads them with --modules-root SERVICE_REGISTRATIONS.
@@ -17,12 +23,23 @@ const SERVICE_ROOT = new URL('./workplace/', import.meta.resolve('@volter/superc
 export const SERVICE_REGISTRATIONS = fileURLToPath(new URL('registrations/', SERVICE_ROOT));
 export const SERVICE_PROGRAM = fileURLToPath(new URL('main.mjs', SERVICE_ROOT));
 const SERVICE_TOKENS = { agents: ['AGENTS_WORKPLACE_TOKEN','AGENTS_TEAMS_TOKEN'], cards: ['CARDS_WORKPLACE_TOKEN','CARDS_TEAMS_TOKEN'], machines: ['MACHINES_WORKPLACE_TOKEN','MACHINES_TEAMS_TOKEN'] };
-export function privateJson(path, value) {
+// The connection's modules that project the board into the Workplace and place a card's run session there (Open Autonomy's
+// Project Rooms seats it in its project's Room): a session a live card's run works in is handed to their principals
+// (the service's rh2.boardApps; organization.mjs keepHandover, runhuman-2 ADR 0046 decision 6).
+export const BOARD_APPS = ['project-rooms'];
+/** Writes `value` whole through a private temporary file and a rename, and returns the text it holds. Given the text the
+ * caller last wrote there (`unchanged`), an identical value writes nothing: a record saved on every event costs a write
+ * only when its content changed. */
+export function privateJson(path, value, unchanged) {
+  const text=JSON.stringify(value,null,2)+'\n';
+  if(text===unchanged)return text;
   mkdirSync(dirname(path),{recursive:true,mode:0o700});
   const pending=`${path}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
-  writeFileSync(pending,JSON.stringify(value,null,2)+'\n',{mode:0o600});renameSync(pending,path);chmodSync(path,0o600);
+  writeFileSync(pending,text,{mode:0o600});renameSync(pending,path);chmodSync(path,0o600);
+  return text;
 }
 export async function connectionCall(record, side, method, path, body, token) {
+    return measureWork("call", "connection.http", async () => {
   const origin=side==='teams'?record.teams.server:record.origin;
   // Registration, consent, exchange and renewal have receiver-staged random values in their bodies:
   // their digest is one operation's key, retained on a retry.
@@ -38,20 +55,33 @@ export async function connectionCall(record, side, method, path, body, token) {
   let payload;try{payload=text===''&&response.status===204?{}:JSON.parse(text);}catch{throw new Error(`${side} ${method} ${path}: invalid JSON (${response.status})`);}
   if(!response.ok)throw Object.assign(new Error(`${side} ${method} ${path}: ${payload.error?.code??response.status}`),{code:payload.error?.code,status:response.status,detail:typeof payload.error?.message==='string'?payload.error.message:null});
   return payload;
-}
+
+
+    });
+  }
 /** A registration that trusts a Workplace as its issuer trusts this connection's Workplace and organization, never the
  * one its committed manifest names (agents.teams-app.json names production's): otherwise every connection's agents app
  * trusted production's tokens, and its own Workplace's notices and views were decided as the issuer app instead. */
 export function trustedIssuer(manifest,record){return manifest.issuer===undefined?{}:{issuer:record.issuer,issuer_organization:record.organization};}
 export function connectionPath(root,id){return join(root,'apps','connections',id,'connection.json');}
+export function boardAppPrincipals(root, record) {
+  return [...new Set(record.grants.filter(g=>BOARD_APPS.includes(g.name)&&g.rh2?.principalId&&!g.retiring&&!g.disabled
+    &&existsSync(join(root,'apps',`${g.name}.${record.id}.json`))).map(g=>g.rh2.principalId))].sort();
+}
 export function generateModuleConfig(root, record, grant) {
   if(SERVICE_APPS.includes(grant.name))return generateServiceConfig(root,record,grant);
   if(grant.adopted)return generateAdoptedConfig(root,record,grant);
   const folder=dirname(connectionPath(root,record.id)), dir=join(folder,grant.name);
   mkdirSync(dir,{recursive:true,mode:0o700});
   const custody=join(dir,'credentials.env'), configPath=join(dir,'config.json');
-  writeFileSync(custody,`RH2_TOKEN=${grant.rh2.accessToken}\n`,{mode:0o600});chmodSync(custody,0o600);
-  const config={rh2:{baseUrl:record.origin,issuer:record.issuer,organization:record.organization,tokenEnv:'RH2_TOKEN'},envFile:custody,
+  writeFileSync(custody,`RH2_TOKEN=${grant.rh2.accessToken}\n${grant.teams?`TEAMS_TOKEN=${grant.teams.credential.token}\n`:''}`,{mode:0o600});chmodSync(custody,0o600);
+  const config=grant.name==='project-rooms'?{
+    teams:{server:record.teams.server,team:record.teams.team,source:record.source,tokenEnv:'TEAMS_TOKEN'},
+    rh2:{baseUrl:record.origin,issuer:record.issuer,organization:record.organization,tokenEnv:'RH2_TOKEN',principalId:grant.rh2.principalId,
+      agentsRegistration:record.grants.find(g=>g.name==='agents')?.clientId,cardsPrincipalId:record.grants.find(g=>g.name==='cards')?.rh2?.principalId},
+    ...(record.scope?{source:{namespace:`cx${record.scope}`}}:{}),envFile:custody,stateFile:join(dir,'state.json'),
+    board:{root,...(process.env.SUPERCODE_BIN?{supercode:process.env.SUPERCODE_BIN}:{})}
+  }:{rh2:{baseUrl:record.origin,issuer:record.issuer,organization:record.organization,tokenEnv:'RH2_TOKEN'},envFile:custody,
     source:{key:`connection-${record.scope}`,name:`${record.organization} / ${record.source}`,home:root,...(process.env.SUPERCODE_BIN?{program:process.env.SUPERCODE_BIN}:{}),harness:record.harness??'hermes'},
     alerts:{role:record.alertRole??'admin'}};
   privateJson(configPath,config);
@@ -66,7 +96,7 @@ function generateAdoptedConfig(root, record, grant) {
   mkdirSync(dir,{recursive:true,mode:0o700});
   const custody=join(dir,'credentials.env'), configPath=join(dir,'config.json');
   writeFileSync(custody,`${grant.config.rh2.tokenEnv}=${grant.rh2.accessToken}\n${grant.teams?`${grant.config.teams.tokenEnv}=${grant.teams.credential.token}\n`:''}`,{mode:0o600});chmodSync(custody,0o600);
-  privateJson(configPath,{...grant.config,envFile:custody,...(grant.config.stateFile?{stateFile:join(dir,'state.json')}:{})});
+  privateJson(configPath,{...grant.config,...(grant.name==='project-rooms'?{rh2:{...grant.config.rh2,principalId:grant.rh2.principalId,agentsRegistration:record.grants.find(g=>g.name==='agents')?.clientId??grant.config.rh2.agentsRegistration,cardsPrincipalId:record.grants.find(g=>g.name==='cards')?.rh2?.principalId??grant.config.rh2.cardsPrincipalId}}:{}),envFile:custody,...(grant.config.stateFile?{stateFile:join(dir,'state.json')}:{})});
   privateJson(join(root,'apps',`${grant.name}.${record.id}.json`),{app:grant.name,connection:record.id,configPath,program:grant.program,adopted:true,
     origin:record.origin,organizationId:record.organization,principalId:grant.rh2.principalId,installationId:grant.rh2.installationId,expiresAt:grant.rh2.expiresAt});
   return configPath;
@@ -82,11 +112,13 @@ export function generateServiceConfig(root, record, grant) {
   const held=Object.fromEntries(record.grants.filter(g=>SERVICE_APPS.includes(g.name)&&g.rh2&&g.teams).map(g=>[g.name,g]));
   writeFileSync(custody,Object.entries(held).map(([name,g])=>`${SERVICE_TOKENS[name][0]}=${g.rh2.accessToken}\n${SERVICE_TOKENS[name][1]}=${g.teams.credential.token}\n`).join(''),{mode:0o600});chmodSync(custody,0o600);
   const agents=held.agents;
+  const boardApps=boardAppPrincipals(root,record);
   if(agents){
     const section=name=>({registration:held[name].clientId,principal:held[name].rh2.principalId,tokenEnv:SERVICE_TOKENS[name][0],teamsTokenEnv:SERVICE_TOKENS[name][1],stateFile:join(dir,`${name}.state.json`),...record.settings?.[name]});
     const config={
       teams:{server:record.teams.server,team:record.teams.team,installation:agents.teams.installation.id,source:record.source,tokenEnv:SERVICE_TOKENS.agents[1]},
-      rh2:{baseUrl:record.origin,organization:record.organization,registration:agents.clientId,...(record.issuer!==record.origin?{issuer:record.issuer}:{}),tokenEnv:SERVICE_TOKENS.agents[0],principal:agents.rh2.principalId},
+      rh2:{baseUrl:record.origin,organization:record.organization,registration:agents.clientId,...(record.issuer!==record.origin?{issuer:record.issuer}:{}),tokenEnv:SERVICE_TOKENS.agents[0],principal:agents.rh2.principalId,
+        ...(boardApps.length?{boardApps}:{})},
       ...(record.scope?{source:{namespace:`cx${record.scope}`}}:{}),envFile:custody,stateFile:join(dir,'agents.state.json'),
       ...record.settings?.service,
       ...(record.webhook?{webhook:record.webhook}:{}),
@@ -117,9 +149,12 @@ export const runnerStopPath=lock=>join(dirname(lock),'runner.stop');
  * through that file, and an older one is ended with its whole process tree. */
 export async function stopConnectionRunner(lock,running,wait=20000){
   if(!alive(running.pid))return true;
-  if(process.platform!=='win32'){try{process.kill(running.pid,'SIGTERM');}catch(error){if(error.code!=='ESRCH')throw error;}}
+  if(process.platform!=='win32'){try{stopWorkChild(running.pid, () => process.kill(running.pid,'SIGTERM'), { signal: 'SIGTERM' });}catch(error){if(error.code!=='ESRCH')throw error;}}
   else if(running.tree)privateJson(runnerStopPath(lock),{pid:running.pid,at:new Date().toISOString()});
-  else spawnSync('taskkill',['/PID',String(running.pid),'/T','/F'],{stdio:'ignore',windowsHide:true});
+  else stopWorkChild(running.pid, () => {
+    const result = spawnSync('taskkill',['/PID',String(running.pid),'/T','/F'],{stdio:'ignore',windowsHide:true});
+    return !result.error && result.status === 0;
+  }, { exitCode: 1 });
   for(let waited=0;waited<wait&&alive(running.pid);waited+=250)await new Promise(done=>setTimeout(done,250));
   return !alive(running.pid);
 }
@@ -157,6 +192,7 @@ export async function connectWorkplace(flags) {
   if(!/^[0-9a-f]{24}$/.test(ticket.scope??''))throw new Error('connection ticket needs a source namespace; apply to a new private output path');
   if(ticket.version!==1||!Array.isArray(ticket.grants)||!ticket.grants.length||ticket.grants.some(g=>!MODULE_APPS.includes(g.name)&&!SERVICE_APPS.includes(g.name))||new Set(ticket.grants.map(g=>g.name)).size!==ticket.grants.length)throw new Error(`unsupported or duplicate connection apps (connect takes ${[...MODULE_APPS,...SERVICE_APPS].join(', ')})`);
   const names=ticket.grants.map(g=>g.name);
+  if(names.includes('project-rooms')&&(!names.includes('agents')||!names.includes('cards')))throw new Error('a fresh Project Rooms connection selects agents and cards too');
   // The service is the agents registration's host: its other registrations run only inside it.
   if(names.some(name=>name!=='agents'&&SERVICE_APPS.includes(name))&&!names.includes('agents'))throw new Error('cards and machines run in the Workplace service, which the agents registration hosts: select agents too');
   if(names.some(name=>MODULE_APPS.includes(name))&&!flags['modules-root'])throw new Error(`--modules-root names where ${names.filter(name=>MODULE_APPS.includes(name)).join(' and ')} are`);
@@ -191,7 +227,7 @@ export async function connectWorkplace(flags) {
     let grant=record.grants.find(g=>g.name===selected.name);
     if(grant && JSON.stringify([grant.manifest,grant.teamsManifest])!==JSON.stringify([selected.manifest,selected.teamsManifest]))throw new Error('existing connection consent differs from the ticket');
     if(!grant){grant={name:selected.name,clientId:selected.clientId,manifest:selected.manifest,teamsManifest:selected.teamsManifest};record.grants.push(grant);privateJson(path,record);}
-    if(SERVICE_APPS.includes(grant.name)&&!selected.teamsManifest)throw new Error(`${grant.name}: its Teams manifest is missing from the ticket (apply with --modules-root naming ${SERVICE_REGISTRATIONS})`);
+    if((SERVICE_APPS.includes(grant.name)||BOARD_APPS.includes(grant.name))&&!selected.teamsManifest)throw new Error(`${grant.name}: its Teams manifest is missing from the ticket (apply with --modules-root naming ${SERVICE_REGISTRATIONS})`);
     if(!grant.rh2){
       const recovering=typeof grant.redemption==='string';
       grant.redemption??=randomBytes(32).toString('base64url');privateJson(path,record);
@@ -221,8 +257,8 @@ export async function connectWorkplace(flags) {
       grant.teams=await connectionCall(record,'teams','POST','/api/v1/apps/token',{app_id:grant.registration.id,app_secret:grant.registration.secret,code:grant.consent.code,redirect_url:selected.teamsManifest.redirect_urls[0],credential_token:grant.stagedCredential});privateJson(path,record);
       delete grant.consent;delete grant.registration.secret;privateJson(path,record);
     }
-    if(!SERVICE_APPS.includes(grant.name))generateModuleConfig(root,record,grant);
   }
+  for(const grant of record.grants.filter(g=>!SERVICE_APPS.includes(g.name)))generateModuleConfig(root,record,grant);
   // The service's config names every one of its registrations, so it is written once all of them hold credentials.
   for(const grant of record.grants.filter(g=>SERVICE_APPS.includes(g.name)))generateServiceConfig(root,record,grant);
   if(!record.issuerRegistration){record.issuerStagedSecret??=`sca_${randomBytes(32).toString('base64url')}`;privateJson(path,record);record.issuerRegistration=(await connectionCall(record,'teams','POST',`/api/v1/teams/${encodeURIComponent(teams.team)}/apps`,{name:`Workplace issuer (${id.slice(0,8)})`,description:'The Workplace as a delegated issuer, verified against its JWKS',actions:['delegation.sessions','delegation.surfaces','delegation.notices','delegation.machines'],event_kinds:[],redirect_urls:['http://127.0.0.1/connected'],issuer:record.issuer,secret:record.issuerStagedSecret},owner)).data;privateJson(path,record);}
@@ -237,7 +273,7 @@ export async function connectWorkplace(flags) {
 /** The service settings an adopted config carries as it ran (main.mjs names every key it accepts); everything else in its
  * config is rebuilt from the connection's own custody, and any key that is neither is named in the answer as dropped. */
 const ADOPTED_SETTINGS={service:['closedLanes','leadProfiles','launch','teamsPerMinute'],cards:['floorTagPrefix'],machines:[]};
-const REBUILT={teams:['server','team','installation','source','tokenEnv'],rh2:['baseUrl','organization','registration','issuer','tokenEnv','principal','cardsPrincipalId'],
+const REBUILT={teams:['server','team','installation','source','tokenEnv'],rh2:['baseUrl','organization','registration','issuer','tokenEnv','principal','cardsPrincipalId','boardApps'],
   source:['namespace'],envFile:null,stateFile:null,webhook:['url','listen'],cards:['registration','principal','tokenEnv','teamsTokenEnv','stateFile'],machines:['registration','principal','tokenEnv','teamsTokenEnv','stateFile']};
 function dropped(config){
   const out=[];
@@ -402,7 +438,8 @@ export async function adoptWorkplaceService(flags) {
       if(existsSync(a)){copyFileSync(a,`${b}.${process.pid}.tmp`);chmodSync(`${b}.${process.pid}.tmp`,0o600);renameSync(`${b}.${process.pid}.tmp`,b);}else if(existsSync(b))unlinkSync(b);
     }
   }
-  for(const grant of record.grants)if(SERVICE_APPS.includes(grant.name))generateServiceConfig(root,record,grant);else generateModuleConfig(root,record,grant);
+  for(const grant of record.grants)if(!SERVICE_APPS.includes(grant.name))generateModuleConfig(root,record,grant);
+  for(const grant of record.grants)if(SERVICE_APPS.includes(grant.name))generateServiceConfig(root,record,grant);
   stopped();
   record.connectedAt??=new Date().toISOString();
   record.preparing=false;record.paused=Boolean(flags['no-start']);privateJson(path,record);
@@ -427,21 +464,39 @@ export async function disconnectWorkplace(flags) {
   record.paused=true;privateJson(path,record);
   const lock=join(dirname(path),'runner.lock');
   if(existsSync(lock)){
-    await stopConnectionRunner(lock,JSON.parse(readFileSync(lock,'utf8')));
+    if(!await stopConnectionRunner(lock,JSON.parse(readFileSync(lock,'utf8'))))throw new Error('the connection runner has not yielded its projection writers');
+  }
+  record.withdrawals??={};privateJson(path,record);
+  // Project Rooms removes its seats with its own credential, then Agents withdraws links and handovers with its own.
+  const owners=[...record.grants.filter(g=>BOARD_APPS.includes(g.name)),...record.grants.filter(g=>g.name==='agents')];
+  for(const grant of owners){
+    if(record.withdrawals[grant.name])continue;
+    const folder=dirname(path),service=SERVICE_APPS.includes(grant.name);
+    const config=join(folder,service?'service':grant.name,'config.json');
+    const program=service?SERVICE_PROGRAM:grant.program??join(record.moduleRoot,grant.name,'main.mjs');
+    try{
+      await new Promise((done,fail)=>execFile(process.execPath,[program,config,'--disconnect'],{windowsHide:true,maxBuffer:1024*1024},error=>error?fail(new Error(`${grant.name}: projection withdrawal remains incomplete; custody and state retained`)):done()));
+      record.withdrawals[grant.name]=new Date().toISOString();delete record.withdrawalError;privateJson(path,record);
+    }catch(error){record.withdrawalError={module:grant.name,at:new Date().toISOString()};privateJson(path,record);throw error;}
   }
   const team=`/api/v1/teams/${encodeURIComponent(record.teams.team)}`, left=[];
+  record.departures??={};
   const leave=async(name,side,method,door,token)=>{
+    const key=`${name}:${side}`;
+    if(record.departures[key]){left.push({name,side,left:true,already:true});return;}
     try{await connectionCall(record,side,method,door,side==='rh2'?{}:undefined,token);left.push({name,side,left:true});}
     catch(error){if(error.status===404||error.code==='installation-unknown'){left.push({name,side,left:true,already:true});}else left.push({name,side,left:false,code:error.code??error.status??error.message});}
+    if(left.at(-1).left)record.departures[key]=true;
     privateJson(path,record);
   };
   for(const grant of record.grants){
     if(grant.teams?.installation?.id)await leave(grant.name,'teams','DELETE',`${team}/app-installations/${encodeURIComponent(grant.teams.installation.id)}`,grant.teams.credential.token);
     if(grant.rh2?.installationId)await leave(grant.name,'rh2','POST',`/api/v3/automation/installations/${encodeURIComponent(grant.rh2.installationId)}/leave`,grant.rh2.accessToken);
-    const entry=join(root,'apps',`${grant.name}.${record.id}.json`);if(existsSync(entry))unlinkSync(entry);
+    const entry=join(root,'apps',`${grant.name}.${record.id}.json`);if((!grant.teams||record.departures[`${grant.name}:teams`])&&(!grant.rh2||record.departures[`${grant.name}:rh2`])&&existsSync(entry))unlinkSync(entry);
   }
   // The token exchange answers {installation, credential: {token, …}} (renewTeams reads the same shape).
   if(record.issuerCredential?.installation?.id)await leave('issuer','teams','DELETE',`${team}/app-installations/${encodeURIComponent(record.issuerCredential.installation.id)}`,record.issuerCredential.credential?.token);
+  if(left.some(each=>!each.left)){record.left=left;privateJson(path,record);throw new Error('connection departure remains incomplete; custody and state retained for retry');}
   record.disconnectedAt=new Date().toISOString();record.left=left;privateJson(path,record);
   return {connection:record.id,root,left,registrations:[...record.grants.map(g=>g.registration?.id).filter(Boolean),record.issuerRegistration?.id].filter(Boolean)};
 }

package/gates.mjs

@@ -1,3 +1,4 @@
+import { stopWorkChild } from '@volter/supercode-harness-sdk/work-ledger';
 // A fire's gate, the I/O half (docs/architecture/orchestrator.md §4.3 step 2a): the job's
 // pre-run script and its monitor source, run by the loop off the event queue. Transcribed from
 // Hermes 0.21.0: `cron/scheduler.py` `_run_job_script` / `_get_script_timeout`, and
@@ -107,7 +108,7 @@ export async function runJobScript(profile, scriptPath, workdir = null, { env =
     // SUPERCODE_FIRE_ID names the fire it runs for, so what it files can be keyed to that fire (a retried run of the
     // same fire files nothing new), not to the wall clock an interval schedule drifts against.
     const child = spawn(argv[0], argv[1], { cwd, env: { ...scriptEnv(), HERMES_HOME: profile.dir, ...(automation ? { SUPERCODE_AUTOMATION: automation } : {}), ...(fire ? { SUPERCODE_FIRE_ID: String(fire) } : {}) }, detached: true, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
-    const kill = () => { try { process.kill(-child.pid, 'SIGKILL'); } catch { /* already gone */ } };
+    const kill = () => { try { stopWorkChild(child, () => process.kill(-child.pid, 'SIGKILL'), { signal: 'SIGKILL' }); } catch { /* already gone */ } };
     const end = (result) => {
       if (finished) return;
       finished = true;

package/hand-off.mjs

@@ -1,3 +1,4 @@
+import { stopWorkChild } from '@volter/supercode-harness-sdk/work-ledger';
 // THE ONE PLACE A HOME'S ORCHESTRATOR IS DECIDED (D152 row 11). Every command on a home ends in an orchestrator's entry
 // (bin/orchestrator.mjs), whichever way it came: a shell's or a pane's supercode, the native binary (its \`workflow\`,
 // \`orchestrator start\`, \`apps\`, \`access\` and its cold write door all run \`node <entry> … --root <home>\` with the
@@ -12,7 +13,7 @@ import { spawn } from 'node:child_process';
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { enforceSourceLock } from '@volter/supercode-teams/source-lock';
+// The pinned source's check (enforceSourceLock, the host's source lock) is handed in by handOff's caller, the entry.
 
 /** The home a command (the whole of it, after the entry) names: --root, wherever it stands (the gateway's form,
  *  `node bin/orchestrator.mjs --root <home>`, has no verb before it); for `import`, which writes the home it names
@@ -27,7 +28,7 @@ export function homeOfArgs(argv, env = process.env) {
 
 /** The command (\`argv\`, after node and the entry) handed to the orchestrator the home's record names: its exit code, or
  *  null when this orchestrator serves it (it is the one named, or the home has no record). */
-export function handOff(root, argv) {
+export function handOff(root, argv, enforceSourceLock) {
   if (!root) return null;
   let record;
   try { record = JSON.parse(readFileSync(join(root, 'orchestrator.json'), 'utf8')); } catch { return null; }
@@ -43,7 +44,7 @@ export function handOff(root, argv) {
   if (named === own) { process.env.SUPERCODE_BIN = supercode; return null; }
   return new Promise((done) => {
     const child = spawn(process.execPath, [named, ...argv], { stdio: 'inherit', env: { ...process.env, SUPERCODE_BIN: supercode } });
-    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(signal, () => { try { child.kill(signal); } catch { /* gone */ } });
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(signal, () => { try { stopWorkChild(child, () => child.kill(signal), { signal: signal }); } catch { /* gone */ } });
     child.on('error', (error) => { process.stderr.write(`supercode: could not run orchestrator ${record.version ?? ''} (${named}): ${error.message}\n`); done(1); });
     child.on('close', (code, signal) => done(signal ? 1 : code ?? 1));
   });

package/hermes-cli.mjs

@@ -1,13 +1,15 @@
+import { measureSyncChild, stopWorkChild } from '@volter/supercode-harness-sdk/work-ledger';
+const spawnSync = (...args) => measureSyncChild(() => workLedgerNativeSpawnSync(...args));
 // Hermes's own tools beside a worker (docs/plans/hermes-compat.md row 7). A home is a Hermes home, and the
 // skills it carries call Hermes's CLI (`hermes kanban …`, `hermes cron notepad …`, `hermes cron doctor`)
 // against it, so a worker of any harness runs with `HERMES_HOME` set to its profile's folder and the
 // pinned `hermes` on its `PATH`. Native cron incidents use the owning interchange codec, in the same executions store.
-import { spawn, spawnSync } from 'node:child_process';
+import { spawn, spawnSync as workLedgerNativeSpawnSync } from 'node:child_process';
 import { accessSync, constants, existsSync, readFileSync, statSync } from 'node:fs';
 import { delimiter, dirname, join } from 'node:path';
 import { parseDotenv } from './orchestration.mjs';
 import { locateHermes } from './apply/doors.mjs';
-import { recordCronIncident } from '@volter/supercode-interchange/cron-incidents';
+import { recordCronIncident } from '@volter/supercode-teams/sessions-cron-incidents';
 import { redactText } from '@volter/teams/redact';
 
 /** Hermes's interpreter over `code`, `payload` on stdin, without blocking the daemon: `{ status, stdout, stderr }`. */
@@ -15,7 +17,7 @@ function python(install, code, payload, env, timeout) {
   return new Promise((done) => {
     const child = spawn(install.python, ['-c', code], { cwd: install.source, env, stdio: ['pipe', 'pipe', 'pipe'] });
     let stdout = '', stderr = '';
-    const timer = setTimeout(() => child.kill('SIGKILL'), timeout);
+    const timer = setTimeout(() => stopWorkChild(child, () => child.kill('SIGKILL'), { signal: 'SIGKILL' }), timeout);
     child.stdout.setEncoding('utf8').on('data', (c) => { stdout += c; });
     child.stderr.setEncoding('utf8').on('data', (c) => { stderr = (stderr + c).slice(-4000); });
     child.on('error', (error) => { clearTimeout(timer); done({ status: null, stdout, stderr: error.message }); });

package/hermes-locks.mjs

@@ -1,3 +1,6 @@
+import { stopWorkChild } from '@volter/supercode-harness-sdk/work-ledger';
+import { measureSyncChild } from '@volter/supercode-harness-sdk/work-ledger';
+const spawnSync = (...args) => measureSyncChild(() => workLedgerNativeSpawnSync(...args));
 // Hermes's two runtime locks, held the way Hermes holds them, so one home is served by one runtime and
 // one bot token by one gateway (docs/plans/hermes-compat.md, row 1; pinned Hermes gateway/status.py).
 //
@@ -9,7 +12,7 @@
 // Hermes calls a holder live when its pid exists and its command line is a gateway's (`hermes-gateway`,
 // `hermes gateway run`, `gateway/run.py`). The daemon runs as `hermes-gateway` (bin/orchestrator.mjs), so
 // Hermes reads the orchestrator's locks as a gateway's, which they are.
-import { spawn, spawnSync } from 'node:child_process';
+import { spawn, spawnSync as workLedgerNativeSpawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, unlinkSync, writeSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -163,7 +166,7 @@ function holdFileLock(path, home, { python, what, tail }) {
       const line = out.split('\n')[0];
       if (line === 'ok') {
         done({ release: () => releasing ??= (async () => {
-          child.stdin.end();
+          stopWorkChild(child, () => child.stdin.end());
           const result = await ended;
           if (result.code !== 0) throw new Error(`lock holder for ${path} exited ${result.code ?? result.signal}`);
         })() });

package/hosted.mjs

@@ -1,3 +1,4 @@
+import { stopWorkChild } from '@volter/supercode-harness-sdk/work-ledger';
 // Host integration: the orchestrator owns time and durable fires; a trusted
 // application executes each task through its existing conversation/action door.
 import { connect } from 'node:net';
@@ -71,7 +72,7 @@ export async function stopHostedDaemon({ root, executorUrl, timeoutMs = 30_000 }
   if (!leaseIsHere(lease)) return { stopped: true, wasRunning: false };
   const alive = () => { try { process.kill(lease.pid, 0); return true; } catch (error) { if (error.code === 'ESRCH') return false; throw error; } };
   if (!alive()) return { stopped: true, wasRunning: false };
-  process.kill(lease.pid, 'SIGTERM');
+  stopWorkChild(lease.pid, () => process.kill(lease.pid, 'SIGTERM'), { signal: 'SIGTERM' });
   const deadline = Date.now() + timeoutMs;
   while (alive()) {
     if (Date.now() >= deadline) throw new Error('The orchestrator has not finished stopping. Its lease and data were preserved.');

package/index.d.ts

@@ -599,3 +599,5 @@ export function leaseIsHere(lease: Pick<OrchestratorLease, 'host' | 'boot'> | nu
 /** Whether the daemon a lease names is alive now: here, and its pid live. */
 export function leaseIsLive(lease: OrchestratorLease | null | undefined): boolean;
 export function readLease(root: string): OrchestratorLease | null;
+
+export type { PrDispositionRecorded, PrReleaseReadback } from './ontology.js';

package/index.mjs

@@ -1,4 +1,4 @@
-import './source-lock.mjs';
+import './source-lock.mjs'; // layer: the orchestrator package enforces its pinned source when it loads (the host's source lock); owed: the host hands the lock in
 export {
   LoadError, sessionReset, homeChannel, CHAT_TYPES, END_REASONS, FIRE_STATUSES, OBLIGATION_STATES,
   renderSurfaceKey, parseSurfaceKey, surfaceKeyString, parseTarget, renderTarget, resolveRoute, routeSpecificity,

package/kanban-worker.mjs

@@ -8,7 +8,7 @@
 // run), its memory is its harness's own, its requests are answered by supercode's unattended rule. A profile whose
 // worker is Hermes runs Hermes itself, as its harness.
 import { spawn } from 'node:child_process';
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
 import { load } from './orchestration.mjs';
@@ -24,6 +24,7 @@ import { DEFAULT_BOARD, openBoard, view } from './board/store.mjs';
 import { getTask } from './board/engine.mjs';
 import { permissionResponse } from './reducer.mjs';
 import { boardGuardArguments } from '@volter/teams/board-process-guard';
+import { resolveNativeSessionHome } from '@volter/supercode-interchange';
 
 /** Hermes's worker argv, as `_default_spawn` builds it. */
 export function parseHermesArgv(argv) {
@@ -48,8 +49,14 @@ function rootOf(home) {
   return basename(dirname(home)) === 'profiles' ? dirname(dirname(home)) : home;
 }
 
-export async function runKanbanWorker(argv, env = process.env) {
+// currentRelease: the machine's current release (the host's), which its caller hands in for the board's hook command.
+export async function runKanbanWorker(argv, env = process.env, currentRelease) {
   const say = (line) => process.stdout.write(`${line}\n`);
+  const refuse = (line) => {
+    say(line);
+    if (env.SUPERCODE_BOARD_FAILURE_FILE) writeFileSync(env.SUPERCODE_BOARD_FAILURE_FILE, `${line}\n`, { mode: 0o600 });
+    return 78;
+  };
   const args = parseHermesArgv(argv);
   if (!env.HERMES_HOME || !args.query) { say('hermes-worker: HERMES_HOME and -q are required (the dispatcher sets both)'); return 2; }
   const home = resolve(env.HERMES_HOME);
@@ -57,22 +64,42 @@ export async function runKanbanWorker(argv, env = process.env) {
   const { state, vault } = await load(root);
   const profile = Object.values(state.profiles).find((p) => resolve(p.dir) === home) ?? state.profiles[args.profile ?? 'default'];
   if (!profile?.worker?.harness) { say(`hermes-worker: no worker for profile ${args.profile ?? home}`); return 2; }
+  const task = Object.fromEntries(KANBAN_ENV.filter((k) => env[k]).map((k) => [k, env[k]]));
   // The agent's home is already the effective profile. Hermes must not switch back to the shared template.
-  if (profile.worker.harness === 'hermes') return runHermes(env.SUPERCODE_AGENT_ID?withoutProfile(argv):argv, env);
+  if (profile.worker.harness === 'hermes') {
+    if (env.SUPERCODE_BOARD_RESUME_SESSION) return refuse(`hermes-worker: Hermes headless continuation of ${env.SUPERCODE_BOARD_RESUME_SESSION} has no verified resume door; a deliberate disposition is required`);
+    try { await recordSession(root, task, 'hermes', null, await resolveNativeSessionHome('hermes', env, process.cwd())); }
+    catch (error) { return refuse(`hermes-worker: recording the native home on its run failed: ${error.message}`); }
+    return runHermes(env.SUPERCODE_AGENT_ID?withoutProfile(argv):argv, env);
+  }
   const harness = profile.worker.harness;
-  const task = Object.fromEntries(KANBAN_ENV.filter((k) => env[k]).map((k) => [k, env[k]]));
   const taskId = task.HERMES_KANBAN_TASK ?? 'none';
   const workspace = env.HERMES_KANBAN_WORKSPACE;
   const cwd = workspace && existsSync(workspace) && statSync(workspace).isDirectory() ? workspace : activationCwd(profile, profile.worker.cwd);
   const worker = { ...profile.worker, ...(args.model ? { model: args.model } : {}) };
+  let retained = null;
+  if (env.SUPERCODE_BOARD_RESUME_SESSION) {
+    try {
+      retained = JSON.parse(env.SUPERCODE_BOARD_NATIVE_HOME ?? 'null');
+      const selected = retained?.env && await resolveNativeSessionHome(harness, retained.env, cwd);
+      if (!selected || JSON.stringify(selected.homes) !== JSON.stringify(retained.homes)) retained = null;
+    } catch { retained = null; }
+    if (!retained) return refuse('hermes-worker: the retained native home is unknown; nothing was resumed');
+  }
   if (args.toolsets) say(`hermes-worker: --toolsets ${args.toolsets} is Hermes's agent's setting, carried and not performed for ${harness}`);
 
   materializePersona(profile);
   materializeSkills(profile);
-  const route = workerRoute(profile, worker, vault);
+  const route = workerRoute(profile, worker, vault, retained);
   const surfaceKey = `kanban|task|${taskId}`;
   const identityEnv=Object.fromEntries(Object.entries(env).filter(([key])=>key.startsWith('SUPERCODE_AGENT_')));
   const runEnv = { ...activationEnv({ root, profile, surfaceKey, vault }), ...route.env, ...task, ...identityEnv,HERMES_HOME: home };
+  if (retained) {
+    for (const [name, value] of Object.entries(retained.env)) {
+      if (value === null) { delete runEnv[name]; delete process.env[name]; }
+      else runEnv[name] = value;
+    }
+  }
   const memory=env.SUPERCODE_AGENT_ID?await memorySnapshot(home):'';
   // the persona, the task protocol and the pinned skills, supercode's own (board/worker-prompt.mjs)
   // the board workflow's own words for this run (its status's prompt and doors), after the task protocol
@@ -80,14 +107,17 @@ export async function runKanbanWorker(argv, env = process.env) {
 
   const client = new SupercodeHarnessClient(env.SUPERCODE_BIN ? { command: env.SUPERCODE_BIN } : {});
   try {
-    return await runTurn({ client, profile, harness, worker, route, root, vault, surfaceKey, runEnv, instructions, task, cwd, args, say });
+    return await runTurn({ client, profile, harness, worker, route, root, vault, surfaceKey, runEnv, instructions, task, cwd, args, say, currentRelease, refuse, resumeSession: env.SUPERCODE_BOARD_RESUME_SESSION || null });
   } finally {
     await client.close().catch(() => {});
   }
 }
 
-async function runTurn({ client, profile, harness, worker, route, root, vault, surfaceKey, runEnv, instructions, task, cwd, args, say }) {
+async function runTurn({ client, profile, harness, worker, route, root, vault, surfaceKey, runEnv, instructions, task, cwd, args, say, currentRelease, refuse, resumeSession }) {
   const descriptor = (await client.supportReport()).harnesses.find((h) => h.id === harness);
+  if (resumeSession && !descriptor?.runtime?.capabilities?.resume_session) {
+    return refuse(`hermes-worker: ${harness} cannot continue ${resumeSession}: its native runtime advertises no resume door; a deliberate disposition is required`);
+  }
   // A worker's folder that is gone (a home moved or swept) fails its launch as the harness program missing; say which.
   if (!existsSync(cwd) || !statSync(cwd).isDirectory()) { say(`hermes-worker: the worker's folder ${cwd} does not exist (the profile's worker.cwd)`); return 2; }
   const base = descriptor?.runtime?.default_launch;
@@ -95,14 +125,31 @@ async function runTurn({ client, profile, harness, worker, route, root, vault, s
   const reasoning = args.reasoning && harness === 'codex' ? ['-c', `model_reasoning_effort=${JSON.stringify(args.reasoning)}`] : [];
   const launch = {
     program: base.program,
-    arguments: boardGuardArguments(harness, [...(base.arguments ?? []), ...modelArguments(worker), ...route.args, ...(instructions && INSTRUCTION_ARGUMENTS[harness] ? INSTRUCTION_ARGUMENTS[harness](instructions) : []), ...userHomeArguments(profile), ...reasoning, ...modeArguments(profile, harness), ...limitArguments(profile, worker, (level, line) => say(line))], { enabled: ['claude-code','codex'].includes(harness), cwd }),
+    arguments: boardGuardArguments(harness, [...(base.arguments ?? []), ...modelArguments(worker), ...route.args, ...(instructions && INSTRUCTION_ARGUMENTS[harness] ? INSTRUCTION_ARGUMENTS[harness](instructions) : []), ...userHomeArguments(profile), ...reasoning, ...modeArguments(profile, harness), ...limitArguments(profile, worker, (level, line) => say(line))], { enabled: ['claude-code','codex'].includes(harness), cwd, currentRelease }),
     env: { ...(base.env ?? {}), ...runEnv },
   };
   declareWorkerHome({ harness, env: launch.env, cwd, log: (_level, line) => say(`hermes-worker: ${line}`) });
   const mount = mountOrchestratorMcp({ root, profile, harness, surfaceKey, launch, vault, task });
+  const nativeHome = await resolveNativeSessionHome(harness, { ...process.env, ...mount.launch.env }, cwd);
+  try { if (nativeHome) await recordSession(root, task, harness, null, nativeHome); }
+  catch (error) { return refuse(`hermes-worker: recording the native home on its run failed: ${error.message}`); }
   const policy = approvalPolicy(profile, harness), reviewer = approvalsReviewer(profile, harness);
-  const runtime = await client.startManagedRuntime({ harness, cwd, launch: mount.launch, ...(mount.mcp_servers ? { mcp_servers: mount.mcp_servers } : {}), ...(policy ? { approval_policy: policy } : {}), ...(reviewer ? { approvals_reviewer: reviewer } : {}) });
-  try { await recordSession(root, task, harness, runtime.handle.runtime_id); } catch (error) { say(`hermes-worker: recording the session on its run: ${error.message}`); }
+  const params = { harness, cwd, launch: mount.launch, ...(mount.mcp_servers ? { mcp_servers: mount.mcp_servers } : {}), ...(policy ? { approval_policy: policy } : {}), ...(reviewer ? { approvals_reviewer: reviewer } : {}) };
+  let runtime;
+  try {
+    runtime = resumeSession ? await client.resumeManagedRuntime({ ...params, runtime_id: resumeSession }) : await client.startManagedRuntime(params);
+  } catch (error) {
+    const failure = `hermes-worker: ${resumeSession ? `native resume of ${resumeSession}` : 'native start'} failed: ${error.message}`;
+    if (resumeSession) return refuse(failure);
+    say(failure); return 1;
+  }
+  try {
+    if (resumeSession && runtime.handle.runtime_id !== resumeSession) throw new Error(`native resume returned ${runtime.handle.runtime_id}, expected ${resumeSession}`);
+    await recordSession(root, task, harness, runtime.handle.runtime_id);
+  } catch (error) {
+    await runtime.close().catch(() => {});
+    return refuse(`hermes-worker: recording the session on its run failed: ${error.message}`);
+  }
   let text = '', last = '';
   // `agent.max_turns` for a worker that takes no cap at launch, held as the daemon holds it (loop.mjs `holdTurnLimit`)
   const counter = turnCounter(profile, harness);
@@ -187,15 +234,18 @@ function cardWords(root, task) {
  * dispatcher recorded): the harness's own transcript, found and resumed by supercode like any session. Written by the
  * board's owner, as every board write is (`workflow run-session`).
  */
-async function recordSession(root, task, harness, sessionId) {
-  if (!task.HERMES_KANBAN_RUN_ID || !sessionId) return;
+async function recordSession(root, task, harness, sessionId, nativeHome = null) {
+  if (!task.HERMES_KANBAN_RUN_ID || (!sessionId && !nativeHome)) return;
   const answer = await askBoardOwner(root, {
-    argv: ['run-session', String(task.HERMES_KANBAN_RUN_ID), String(sessionId), '--harness', harness, '--task', String(task.HERMES_KANBAN_TASK ?? '')],
+    argv: ['run-session', String(task.HERMES_KANBAN_RUN_ID), ...(sessionId ? [String(sessionId)] : []), '--harness', harness, '--task', String(task.HERMES_KANBAN_TASK ?? ''), ...(nativeHome ? ['--native-home', JSON.stringify(nativeHome)] : [])],
     board: task.HERMES_KANBAN_BOARD || null, caller: null, session: null, cwd: process.cwd(), stdin: null,
     facts: { ...callerFacts(), SUPERCODE_CONTEXT: process.env.SUPERCODE_CONTEXT || 'local' },
   });
   if (answer.unanswered === true) throw new Error(unansweredText(answer, `the run's session record (run-session ${task.HERMES_KANBAN_RUN_ID})`).trim());
   if (answer.code) throw new Error((answer.stderr || 'the board owner did not record it').trim());
+  let result;
+  try { result = JSON.parse(answer.stdout ?? '{}'); } catch { /* text output is allowed */ }
+  if (result?.error) throw new Error(String(result.error));
 }
 
 /** A profile whose worker is Hermes: the dispatcher's own command, run as Hermes would have run it. */