@volter/supercode-orchestrator 0.5.206 → 0.5.208

package/connection.mjs

@@ -1,5 +1,5 @@
 // The kit's connection coordinator. Module manifests and programs belong to their application publisher.
-import { chmodSync, existsSync, mkdirSync, openSync, closeSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, openSync, closeSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { createHash, randomBytes } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -7,7 +7,15 @@ import { spawn } 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 = ['arcs-rooms','orchestration-rh2'];
+// 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.
+export const SERVICE_APPS = ['agents','cards','machines'];
+export const SERVICE_REGISTRATIONS = fileURLToPath(new URL('../teams/workplace/registrations/', import.meta.url));
+export const SERVICE_PROGRAM = fileURLToPath(new URL('../teams/workplace/main.mjs', import.meta.url));
+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) {
   mkdirSync(dirname(path),{recursive:true,mode:0o700});
   const pending=`${path}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
@@ -16,37 +24,30 @@ export function privateJson(path, value) {
 export async function connectionCall(record, side, method, path, body, token) {
   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. A lease refresh is a new operation even
-  // with the same keys/results. Keep its key in custody until an answer is received.
-  const lease=side==='teams'&&method==='POST'&&path.endsWith('/issuer-keyring');
-  let operationKey;
-  if(lease){
-    const digest=createHash('sha256').update(JSON.stringify(body)).digest('hex');
-    if(record.issuerKeyOperation?.digest!==digest)record.issuerKeyOperation={digest,key:`connect-${randomBytes(24).toString('hex')}`};
-    operationKey=record.issuerKeyOperation.key;
-    privateJson(connectionPath(record.root,record.id),record);
-  }
+  // their digest is one operation's key, retained on a retry.
   const began=Date.now();
-  const response=await fetch(`${origin}${path}`,{method,redirect:'manual',signal:AbortSignal.timeout(path.endsWith('issuer-checks')?30000:9000),
+  const response=await fetch(`${origin}${path}`,{method,redirect:'manual',signal:AbortSignal.timeout(9000),
     headers:{accept:'application/json',...(token?{authorization:`Bearer ${token}`} : {}),
       ...(side==='rh2'?{origin:record.origin,'x-rh2-organization':record.organization}:{}),
       ...(body===undefined?{}:{'content-type':'application/json'}),
-      ...(['POST','PATCH','DELETE'].includes(method)?{'idempotency-key':operationKey??`connect-${createHash('sha256').update(`${method}\n${path}\n${JSON.stringify(body)}`).digest('hex')}`}:{})},
+      ...(['POST','PATCH','DELETE'].includes(method)?{'idempotency-key':`connect-${createHash('sha256').update(`${method}\n${path}\n${JSON.stringify(body)}`).digest('hex')}`}:{})},
     ...(body===undefined?{}:{body:JSON.stringify(body)})});
   const text=await response.text();
   record.calls??=[];record.calls.push({side,method,path,status:response.status,ms:Date.now()-began,bytes:Buffer.byteLength(text)});record.calls=record.calls.slice(-200);
-  let payload;try{payload=JSON.parse(text);}catch{throw new Error(`${side} ${method} ${path}: invalid JSON (${response.status})`);}
+  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});
-  if(lease){delete record.issuerKeyOperation;privateJson(connectionPath(record.root,record.id),record);}
   return payload;
 }
 export function connectionPath(root,id){return join(root,'apps','connections',id,'connection.json');}
 export function generateModuleConfig(root, record, grant) {
+  if(SERVICE_APPS.includes(grant.name))return generateServiceConfig(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${grant.teams?`TEAMS_TOKEN=${grant.teams.credential.token}\n`:''}`,{mode:0o600});chmodSync(custody,0o600);
-  const config={rh2:{baseUrl:record.origin,issuer:record.issuer,organization:record.organization,principalId:grant.rh2.principalId,tokenEnv:'RH2_TOKEN'},
+  // The arcs module seats card agents by resolving them in the registration that provides them: the connection's agents.
+  const agents=record.grants.find(g=>g.name==='agents'&&g.clientId), cards=record.grants.find(g=>g.name==='cards'&&g.rh2);
+  const config={rh2:{baseUrl:record.origin,issuer:record.issuer,organization:record.organization,principalId:grant.rh2.principalId,tokenEnv:'RH2_TOKEN',...(agents?{agentsRegistration:agents.clientId}:{}),...(cards?{cardsPrincipalId:cards.rh2.principalId}:{})},
     teams:{server:record.teams.server,team:record.teams.team,source:record.source,tokenEnv:'TEAMS_TOKEN'},
     envFile:custody,stateFile:join(dir,'state.json'),defaultFloor:record.floor,
     source:{key:`connection-${record.scope}`,namespace:`cx${record.scope}`,name:`${record.organization} / ${record.source}`,home:root,...(record.teamsContext?{teamsContext:record.teamsContext}:{}),...(process.env.SUPERCODE_BIN?{program:process.env.SUPERCODE_BIN}:{}),harness:record.harness??'hermes'},
@@ -56,6 +57,30 @@ export function generateModuleConfig(root, record, grant) {
     origin:record.origin,organizationId:record.organization,principalId:grant.rh2.principalId,installationId:grant.rh2.installationId,expiresAt:grant.rh2.expiresAt});
   return configPath;
 }
+/** The Workplace service's config and custody, written from the connection alone (no hand-written config): every installed
+ * service registration's credentials, ids and state, and the home's registry entry for `grant`. One config serves all. */
+export function generateServiceConfig(root, record, grant) {
+  const folder=dirname(connectionPath(root,record.id)), dir=join(folder,'service');
+  mkdirSync(dir,{recursive:true,mode:0o700});
+  const custody=join(dir,'credentials.env'), configPath=join(dir,'config.json');
+  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;
+  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`)});
+    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},
+      source:{namespace:`cx${record.scope}`},envFile:custody,stateFile:join(dir,'agents.state.json'),
+      ...(record.webhook?{webhook:record.webhook}:{}),
+      ...(held.cards?{cards:section('cards')}:{}),...(held.machines?{machines:section('machines')}:{}),
+    };
+    privateJson(configPath,config);
+  }
+  privateJson(join(root,'apps',`${grant.name}.${record.id}.json`),{app:grant.name,connection:record.id,configPath,program:SERVICE_PROGRAM,
+    origin:record.origin,organizationId:record.organization,principalId:grant.rh2.principalId,installationId:grant.rh2.installationId,expiresAt:grant.rh2.expiresAt});
+  return configPath;
+}
 export function startConnectionRunner(root,id) {
   const recordPath=connectionPath(root,id);
   if(!existsSync(recordPath)||!connectionCanRun(JSON.parse(readFileSync(recordPath,'utf8'))))return null;
@@ -63,12 +88,18 @@ export function startConnectionRunner(root,id) {
   const child=spawn(process.execPath,[fileURLToPath(new URL('./bin/connection-runner.mjs',import.meta.url)),'--root',root,'--connection',id],{detached:true,stdio:['ignore',fd,fd],env:process.env});
   closeSync(fd);child.unref();return child.pid;
 }
-export function connectionCanRun(record){return record.preparing===false&&record.paused===false&&typeof record.connectedAt==='string';}
+export function connectionCanRun(record){return record.preparing===false&&record.paused===false&&typeof record.connectedAt==='string'&&!record.disconnectedAt;}
 export async function connectWorkplace(flags) {
-  if(!flags.root||!flags['ticket-file']||!flags['modules-root']||!flags.source)throw new Error('connect needs --root, --ticket-file, --modules-root and --source (one board event source)');
+  if(!flags.root||!flags['ticket-file']||!flags.source)throw new Error('connect needs --root, --ticket-file and --source (one board event source)');
   const root=resolve(flags.root), ticket=JSON.parse(readFileSync(flags['ticket-file'],'utf8'));
   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))||new Set(ticket.grants.map(g=>g.name)).size!==ticket.grants.length)throw new Error('unsupported or duplicate connection modules');
+  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);
+  // 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`);
+  if(Boolean(flags['webhook-url'])!==Boolean(flags['webhook-listen']))throw new Error('--webhook-url and --webhook-listen go together: where the Workplace sends the agents registration\'s events, and the loopback address the service listens on');
+  const moduleRoot=flags['modules-root']?resolve(flags['modules-root']):null;
   // An explicit local credential input is useful for an owned stack; a normal connect uses its existing Teams context.
   let teams,owner;
   if(flags['teams-token-file']){
@@ -86,9 +117,13 @@ export async function connectWorkplace(flags) {
   const path=connectionPath(root,id),prior=existsSync(path)?JSON.parse(readFileSync(path,'utf8')):null;
   if(!prior&&!(Date.parse(ticket.expiresAt)>Date.now()))throw new Error('connection ticket expired; apply the organization file again');
   const record=prior??{version:1,id,scope:ticket.scope,teamsContext:flags.context??process.env.SUPERCODE_CONTEXT,origin:ticket.origin,issuer:ticket.issuer,organization:ticket.organization,teams,source:flags.source,
-    selection:ticket.grants.map(g=>g.name),moduleRoot:resolve(flags['modules-root']),floor:flags.floor??ticket.floor??'Work',alertRole:flags['alert-role']??'admin',grants:[]};
+    selection:ticket.grants.map(g=>g.name),moduleRoot,...(flags['webhook-url']?{webhook:{url:flags['webhook-url'],listen:flags['webhook-listen']}}:{}),floor:flags.floor??ticket.floor??'Work',alertRole:flags['alert-role']??'admin',grants:[]};
   record.root=root;
-  if(prior&&(record.source!==flags.source||record.moduleRoot!==resolve(flags['modules-root'])||record.selection.join(',')!==ticket.grants.map(g=>g.name).join(',')))throw new Error('the existing connection has different module/source settings; use a new connection ticket before replacing it');
+  if(prior?.disconnectedAt)throw new Error('this connection was disconnected; apply the organization file again for a new ticket');
+  // The service's event address is part of the connection: a different one is a new connection, never silently dropped.
+  const webhook=flags['webhook-url']?{url:flags['webhook-url'],listen:flags['webhook-listen']}:undefined;
+  if(prior&&webhook&&JSON.stringify(prior.webhook??null)!==JSON.stringify(webhook))throw new Error('the existing connection has a different --webhook-url/--webhook-listen; use a new connection ticket before replacing it');
+  if(prior&&(record.source!==flags.source||(record.moduleRoot??null)!==moduleRoot||record.selection.join(',')!==ticket.grants.map(g=>g.name).join(',')))throw new Error('the existing connection has different module/source settings; use a new connection ticket before replacing it');
   const lock=join(dirname(path),'runner.lock');
   if(prior&&existsSync(lock)) {
     const running=JSON.parse(readFileSync(lock,'utf8'));
@@ -106,7 +141,8 @@ export async function connectWorkplace(flags) {
   for(const selected of ticket.grants){
     let grant=record.grants.find(g=>g.name===selected.name);
     if(grant && JSON.stringify([grant.manifest,grant.teamsManifest,grant.rooms])!==JSON.stringify([selected.manifest,selected.teamsManifest,selected.rooms]))throw new Error('existing connection consent differs from the ticket');
-    if(!grant){grant={name:selected.name,rooms:selected.rooms,manifest:selected.manifest,teamsManifest:selected.teamsManifest};record.grants.push(grant);privateJson(path,record);}
+    if(!grant){grant={name:selected.name,clientId:selected.clientId,rooms:selected.rooms,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(!grant.rh2){
       const recovering=typeof grant.redemption==='string';
       grant.redemption??=randomBytes(32).toString('base64url');privateJson(path,record);
@@ -136,13 +172,13 @@ 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);
     }
-    generateModuleConfig(root,record,grant);
+    if(!SERVICE_APPS.includes(grant.name))generateModuleConfig(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:'Installation-scoped outbound delegated trust',actions:['delegation.sessions','delegation.surfaces','delegation.notices','delegation.machines'],event_kinds:[],redirect_urls:['http://127.0.0.1/connected'],issuer:record.issuer,outbound_issuer:true,secret:record.issuerStagedSecret},owner)).data;privateJson(path,record);}
+  // 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);}
   if(!record.issuerConsent&&!record.issuerCredential){record.issuerStagedCode??=`sci_${randomBytes(32).toString('base64url')}`;privateJson(path,record);record.issuerConsent=(await connectionCall(record,'teams','POST',`/api/v1/teams/${encodeURIComponent(teams.team)}/apps/${record.issuerRegistration.id}/installations`,{redirect_url:'http://127.0.0.1/connected',state:id,code:record.issuerStagedCode},owner)).data;privateJson(path,record);}
   if(!record.issuerCredential){record.issuerStagedCredential??=newInstallationToken();privateJson(path,record);record.issuerCredential=await connectionCall(record,'teams','POST','/api/v1/apps/token',{app_id:record.issuerRegistration.id,app_secret:record.issuerStagedSecret,code:record.issuerStagedCode,redirect_url:'http://127.0.0.1/connected',credential_token:record.issuerStagedCredential});privateJson(path,record);delete record.issuerConsent;delete record.issuerRegistration.secret;privateJson(path,record);}
-  const keys=(await connectionCall(record,'rh2','GET','/.well-known/jwks.json')).keys;
-  await connectionCall(record,'teams','POST',`/api/v1/teams/${encodeURIComponent(teams.team)}/app-installations/${record.issuerCredential.installation.id}/issuer-keyring`,{keys,results:[]},record.issuerCredential.credential.token);
   privateJson(join(dirname(path),'standing.json'),[]);
   record.connectedAt??=new Date().toISOString();
   record.preparing=false;record.paused=Boolean(flags['no-start']);privateJson(path,record);
@@ -150,4 +186,37 @@ export async function connectWorkplace(flags) {
   return {connection:id,root,modules:record.grants.map(g=>g.name),runner:pid,calls:record.calls.map(({side,method,path,status,ms,bytes})=>({side,method,path,status,ms,bytes}))};
 }
 
+/** Undo a connection with its own credentials, no admin needed (runhuman-2 ADR 0055 decision 3): its runner stops, every
+ * installation it holds leaves both sides by itself (each Workplace installation through its own uninstall door, each
+ * Teams installation and the issuer's by deleting itself), and the home's registry entries go. The registrations stay, as
+ * consented apps with no installation; an admin deregisters them. The custody record stays, marked disconnected, for
+ * audit; it can never run again. */
+export async function disconnectWorkplace(flags) {
+  if(!flags.root||!flags.connection)throw new Error('disconnect needs --root and --connection (the id connect printed)');
+  const root=resolve(flags.root), path=connectionPath(root,flags.connection);
+  if(!existsSync(path))throw new Error(`no connection ${flags.connection} in ${root}`);
+  const record=JSON.parse(readFileSync(path,'utf8'));record.root=root;
+  record.paused=true;privateJson(path,record);
+  const lock=join(dirname(path),'runner.lock');
+  if(existsSync(lock)){
+    const running=JSON.parse(readFileSync(lock,'utf8'));
+    try{process.kill(running.pid,'SIGTERM');}catch(error){if(error.code!=='ESRCH')throw error;}
+    for(let waited=0;waited<20000;waited+=250){try{process.kill(running.pid,0);}catch{break;}await new Promise(done=>setTimeout(done,250));}
+  }
+  const team=`/api/v1/teams/${encodeURIComponent(record.teams.team)}`, left=[];
+  const leave=async(name,side,method,door,token)=>{
+    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});}
+    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)}/uninstall`,grant.rh2.accessToken);
+    const entry=join(root,'apps',`${grant.name}.${record.id}.json`);if(existsSync(entry))unlinkSync(entry);
+  }
+  if(record.issuerCredential?.installation?.id)await leave('issuer','teams','DELETE',`${team}/app-installations/${encodeURIComponent(record.issuerCredential.installation.id)}`,record.issuerCredential.token);
+  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)};
+}
+
 export function newInstallationToken(){return `sct_cred_${randomBytes(16).toString('hex')}.${randomBytes(32).toString('base64url')}`;}

package/index.d.ts

@@ -131,7 +131,7 @@ export function agentScope(context?: string): {server: string; org: string; prin
 /** The identity a run starts as without asking Teams; `identity.synced` is false until Teams has its declaration, made later under the same id. */
 /** A local agent: its daemon-minted id, retained intent and assignments. */
 export type LocalAgent = {identity: AgentIdentity; intended: ReturnType<typeof resolveAgentProfile>; assignment: string; assignments: Array<Record<string, unknown>>; org: string};
-export function localCardAgent(options: {root: Path; org: string; server: string; profiles: Record<string, Profile>; profile: string; card: string; role: string; sponsor?: string | null; machine?: string | null; starterSession?: string | null}): LocalAgent & {synced: false};
+export function localCardAgent(options: {root: Path; org: string; server: string; profiles: Record<string, Profile>; profile: string; card: string; role: string; handle?: string | null; readableId?: string | null; machine?: string | null; starterSession?: string | null}): LocalAgent & {synced: false};
 export function localProfileAgent(options: {root: Path; org: string; server: string; profiles: Record<string, Profile>; profile: string; machine?: string | null; agent?: string | null; declarations?: Record<string, unknown>}): LocalAgent & {synced: false};
 export function localForkAgent(options: {root: Path; org: string; server: string; profiles: Record<string, Profile>; parent: string; session: string; name: string; key: string}): LocalAgent;
 /** Hand this home's agent declarations and ends to this machine's daemon, which declares and ends them in Teams. Answers what could not be handed on. */
@@ -349,6 +349,10 @@ export class AgentMailboxBridge {
 }
 
 export class Orchestrator {
+  /** Private local preparation only: no hosted runtime or provider process. */
+  prepareMainPane(options: {directory: string; name: string; resume?: import('@volter/supercode-harness-sdk').SessionLocator | null}): Promise<{
+    ran: string; program: 'codex'; profile: string; cwd: string; arguments: string[]; env: Record<string,string>;
+  }>;
   constructor(o: {
     state: OrchestratorState;
     vault?: Vault;
@@ -485,7 +489,7 @@ export interface OrchestrationImported {
 
 /** Our folder, strict, through `harness.v1.orchestration.load`; the vault is read out of the home's own `.env`. */
 export function load(root: Path): Promise<{ state: OrchestratorState; vault: Vault }>;
-/** Our folder, canonical and byte-stable, through `harness.v1.orchestration.save`. Sends no secret. */
+/** Runtime persistence through `harness.v1.orchestration.save`. Leaves workflow.yaml untouched; sends no secret. */
 export function save(state: OrchestratorState, root?: Path): Promise<void>;
 /** Another harness's home as a state value; `vault_keys` names the `.env` keys it would need. */
 export function compile(from: 'hermes' | 'openclaw', home: Path): Promise<{ state: OrchestratorState; vault_keys: string[] }>;

package/loop.mjs

@@ -4,13 +4,14 @@
 // This is the only module that performs I/O for the loop. It holds the single
 // state value, the vault, the SDK client, the adapters, and an injected clock.
 
-import { mkdirSync, writeFileSync, existsSync, readdirSync, readFileSync, renameSync, unlinkSync } from 'node:fs';
+import { mkdirSync, writeFileSync, existsSync, readdirSync, readFileSync, renameSync, unlinkSync, realpathSync } from 'node:fs';
 import { basename, join, dirname } from 'node:path';
 import { step, leaseId } from './reducer.mjs';
 import * as events from './events.mjs';
-import { read, save, retainWorld, releaseWorld } from './orchestration.mjs';
+import { read, save, retainWorld, releaseWorld, refreshVault } from './orchestration.mjs';
 import { INSTRUCTION_ARGUMENTS, NAME_ARGUMENTS, activationEnv, activationCwd, workerCwd, declareWorkerFolder, declareWorkerHome, approvalPolicy, sandboxArguments, limitArguments, materializePersona, materializeSkills, modelArguments, turnCounter, userHomeArguments, userHomePersona } from './activation.mjs';
-import { workerRoute } from './worker-route.mjs';
+import { workerRoute, codexPaneRoute } from './worker-route.mjs';
+import { projectCodexPaneResume } from './codex-pane-resume.mjs';
 import { hermesAccess, hermesApproval, untrustedServerVerdict, hermesToolEnv, memorySnapshot, mirrorSession, mirrorState, recordIncident, sealMirror } from './hermes-cli.mjs';
 import { hermesSessionKey, homeChannel } from './ir.mjs';
 import { surfaceKeyString } from './ir.mjs';
@@ -536,6 +537,50 @@ export class Orchestrator {
     return runtime.handle;
   }
 
+  /** A private local preparation door for an explicit headful mailbox main.
+   * It returns only launch metadata and the configured forward's stand-in key;
+   * it creates no hosted conversation, controller lease, process or first turn. */
+  async prepareMainPane({ directory, name, resume = null }) {
+    if (typeof directory !== 'string' || typeof name !== 'string' || !/^[A-Za-z0-9._-]+$/.test(name))
+      throw new Error('a headful main needs its exact profile directory and agent name');
+    const folder = realpathSync(directory);
+    const profiles = Object.values(this.state.profiles).filter(profile => {
+      try { return realpathSync(profile.dir) === folder; } catch { return false; }
+    });
+    if (!profiles.length) throw Object.assign(new Error('this home has no profile at that directory'), { code: 'not_this_home' });
+    if (profiles.length !== 1) throw new Error('the directory names more than one profile; no main was prepared');
+    const profile = profiles[0], worker = profile.worker;
+    if (worker?.harness !== 'codex') throw new Error('the selected main profile does not run Codex');
+    refreshVault(this.state, this.vault);
+    const route = codexPaneRoute(profile, worker, this.vault);
+    if (resume !== null) {
+      if (resume.harness !== 'codex' || typeof resume.session_id !== 'string' || resume.storage?.kind !== 'file')
+        throw new Error('a main resume needs its exact Codex transcript locator');
+      projectCodexPaneResume(route.env.CODEX_HOME, resume.storage.path, resume.session_id);
+    }
+    const context = process.env.SUPERCODE_CONTEXT, scope = agentScope(context);
+    const agent = await localProfileAgent({ root: this.state.root, org: scope.org, server: scope.server,
+      profiles: this.state.profiles, profile: profile.name, agent: name, declarations: this.state.agents });
+    const env = { ...route.env, ...agentEnvironment(agent, { root: this.state.root,
+      context: localReaderContext(scope.org, agent.identity.id) ?? undefined, main: true }) };
+    // The headful main uses the same profile-owned MCP door and identity
+    // preamble. The returned plan carries no configured server credentials.
+    mountOrchestratorMcp({ root: this.state.root, profile, harness: 'codex',
+      socketPath: this.bridge?.path ?? socketPathFor(this.state.root), vault: this.vault,
+      agentId: agent.identity.id });
+    const instructions = agentPreamble(agent, { main: true,
+      previous: localAgentSessions(this.state.root, scope.org, agent.identity.id) });
+    const arguments_ = [...route.args, ...INSTRUCTION_ARGUMENTS.codex(instructions)];
+    if (resume === null) {
+      arguments_.push(...modelArguments({ ...worker, model: route.model }), '--ask-for-approval', approvalPolicy(profile, 'codex'));
+      arguments_.push(...sandboxArguments(profile, 'codex'));
+      if (worker.reasoning_effort) arguments_.push('-c', `model_reasoning_effort=${JSON.stringify(worker.reasoning_effort)}`);
+    }
+    declareWorkerHome({ harness: 'codex', env, cwd: folder, log: (level, text) => this.log(level, text) });
+    return { ran: `prepared a headful main for profile ${profile.name}`, program: 'codex',
+      profile: profile.name, cwd: folder, arguments: arguments_, env };
+  }
+
   /**
    * A new concurrent session of this profile's agent, asked for on its behalf (operator `sessions.launch`): the agent is
    * the one this home holds for the profile, and must be the one asked for. The session is composed by startRuntime
@@ -570,6 +615,8 @@ export class Orchestrator {
       const native=prior.session_ref.slice(prior.session_ref.indexOf(':')+1);
       const page=await this.client.discover({harnesses:[locator.harness],query:native,limit:200});
       target=page.sessions.find(item=>item.locator.harness===locator.harness&&item.locator.session_id===native)?.locator;
+      // a source still being read is no proof the retained session is gone: no replacement is made either way
+      if(!target&&page.reconciling?.length)throw new Error(`retained fork session cannot be confirmed yet: the session index is still reading ${page.reconciling.join(', ')}; no replacement was created`);
       if(!target)throw new Error('retained fork session is not available; no replacement was created');
     }else {
       const loaded=await this.client.loadWindow(locator,{message_limit:1});
@@ -814,6 +861,7 @@ export class Orchestrator {
     if (locator.storage) return locator;
     const found = await this.client.request('harness.v1.sessions.discover', { query: locator.session_id, harnesses: [locator.harness], limit: 200 });
     const whole = found.sessions?.find((item) => item.locator?.harness === locator.harness && item.locator?.session_id === locator.session_id)?.locator;
+    if (!whole && found.reconciling?.length) throw new Error(`${locator.harness}:${locator.session_id} cannot be found yet: the session index is still reading ${found.reconciling.join(', ')}`);
     if (!whole) throw new Error(`${locator.harness}:${locator.session_id} is not in its harness catalogue`);
     return whole;
   }

package/mcp/bridge.mjs

@@ -123,7 +123,10 @@ async function dispatch(orch, call, log) {
 async function dispatchOperator(orch, { op, args, profile }, log) {
   const name = typeof profile === 'string' && profile ? profile : 'default';
   let answer;
-  if (op === 'agents.fork') {
+  if (op === 'agents.main_plan') {
+    try { answer = { ok: true, result: await orch.prepareMainPane(args ?? {}) }; }
+    catch (error) { answer = { ok: false, error: error.message, ...(error.code ? { code: error.code } : {}) }; }
+  } else if (op === 'agents.fork') {
     // Operation `fork`: a declared child agent, its profile a copy of the parent's, its session a fork of the parent's.
     try {
       const a = args ?? {};

package/mcp/hermes-kanban-tools.json

@@ -46,7 +46,11 @@
         },
         "include_archived": {
           "type": "boolean",
-          "description": "Include archived tasks. Defaults to false."
+          "description": "Include cancelled and archived cards and their tasks. Defaults to false."
+        },
+        "include_subtasks": {
+          "type": "boolean",
+          "description": "Include subtasks as separate rows. Defaults to false; use kanban_show to read a card's tasks inside it."
         },
         "limit": {
           "type": "integer",

package/ontology.d.ts

@@ -1,7 +1,7 @@
 // GENERATED from `supercode ontology schema` — do not edit; run node sdk/orchestrator/scripts/generate-types.mjs
 //
-// The Rust records in `crates/interchange/src/world/` and
-// `crates/interchange/src/ontology/` are the source of truth (`docs/ONTOLOGY.md` §2).
+// The committed `sdk/interchange/ontology-schemas.json` contracts own these types.
+// Native serde records remain only with the capabilities still using them.
 
 /** The access record, as Hermes's stores hold it. */
 export interface Access {
@@ -45,8 +45,6 @@ export interface AgentDecl {
   label?: string | null;
   /** The agent it is declared under, if not the home's root. */
   parent?: string | null;
-  /** A person set on purpose as its sponsor; absent, the sponsor is inherited. */
-  sponsor?: string | null;
   /** What a source format said about it that the IR has no field for, verbatim. */
   residue?: Record<string, unknown>;
 }
@@ -115,7 +113,7 @@ export interface Binding {
 
 /**
  * A per-action gate on a profile's agents: a start or resume over it is refused, with the reason,
- * and the refusal is told to the manager and the sponsor. It never pauses or ends anything itself.
+ * and the refusal is told to the manager. It never pauses or ends anything itself.
  */
 export interface Budget {
   /** The window. */
@@ -390,19 +388,7 @@ export type FireStatus =
   | 'unknown';
 
 /** Observations a role can subscribe to, separate from a card's transition events. */
-export type FleetEventKind =
-  /** A native session process first observed running. */
-  | 'session_started'
-  /** A known native session observed running in a new process incarnation. */
-  | 'session_resumed'
-  /** A native source reports a session process ended; unavailable sources are not ends. */
-  | 'session_ended'
-  /** More than one observed live process incarnation names the same native session. */
-  | 'duplicate_session_process'
-  /** A card's native session reports that it needs its user's input. */
-  | 'card_waiting_on_user'
-  /** A machine's health source reports a critical alarm. */
-  | 'machine_health_crit';
+export type FleetEventKind = 'session_started' | 'session_resumed' | 'session_ended' | 'duplicate_session_process' | 'card_waiting_on_user' | 'machine_health_crit';
 
 /** A conversation moved (or moving) to another surface — Hermes `handoff_*`. */
 export interface Handoff {
@@ -836,7 +822,7 @@ export type SecretRef =
   /** A key in the home's own `.env` file. */
   | { dotenv: string };
 
-/** A session's usage, kept on the session and summed upward (session → agent → sponsor → Org). */
+/** A session's usage, kept on the session and summed upward (session → agent → Org). */
 export interface SessionUsage {
   /** The agent the session belongs to, when it has one. */
   agent?: string | null;
@@ -1134,11 +1120,6 @@ export interface Workflow {
   params?: Record<string, unknown>;
   /** Who acts on a card, each an expression naming a profile (`implementer: card.assignee`) or a person. */
   roles?: Record<string, Expr>;
-  /**
-   * Opt-in fleet observations delivered as mail to each role's declared addresses. These are not card
-   * transitions and grant no observation or machine authority. The manager is an implicit workflow role.
-   */
-  listeners?: Record<string, RoleFleetListener>;
   /** Where a new card starts: the first transition whose guard holds. */
   initial: Transition[];
   /** Every status, by name. */
@@ -1152,4 +1133,6 @@ export interface Workflow {
    * are), the event kinds it hears and the template each is told in. A kind not named is not sent.
    */
   notify?: Record<string, Record<string, string>>;
+  /** Role fleet listeners; a declaration grants no machine or mailbox authority. */
+  listeners?: Record<string, RoleFleetListener>;
 }

package/orchestration.mjs

@@ -150,7 +150,7 @@ export async function load(root) {
   const { orchestration, vault_keys } = await through((d) => d.orchestrationLoad({ root }));
   let vault = readVault(orchestration);
   if (vault_keys.some((k) => !vault.has(k))) {
-    await through((d) => d.orchestrationSave({ root, orchestration }));
+    await through((d) => d.orchestrationSave({ root, orchestration, preserve_workflow: true }));
     vault = readVault(orchestration);
     const missing = vault_keys.filter((k) => !vault.has(k));
     if (missing.length) throw new Error(`${root}: ${missing.join(', ')} referenced but not in .env after normalization`);
@@ -164,12 +164,15 @@ export async function read(root) {
 }
 
 /**
- * `save(state, root)` — our folder, canonical and byte-stable: an artifact whose record has not changed keeps its bytes.
+ * `save(state, root)` — persist runtime state, preserving the home's workflow.yaml.
+ * Board policy belongs to the live home, not the runtime's earlier snapshot. Full
+ * home creation/replacement uses orchestrationSave or importFrom explicitly.
+ * Other artifacts are canonical and byte-stable when their record has not changed.
  * Answers the entries the door could not read (`rejected`, each `{ collection, key, reason, kept_stored }`): each was
  * written as the home last held it, or left out when it held none, and none refuses the rest of the save.
  */
 export async function save(state, root = state.root) {
-  const saved = await through((d) => d.orchestrationSave({ root, orchestration: persistedView(state) }));
+  const saved = await through((d) => d.orchestrationSave({ root, orchestration: persistedView(state), preserve_workflow: true }));
   return { rejected: Array.isArray(saved?.rejected) ? saved.rejected : [] };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.206",
+  "version": "0.5.208",
   "type": "module",
   "description": "The orchestrator runtime over the Volter Harness ontology: one typed operational model whose folder is its serialization, read and written through the harness orchestration doors (docs/ORCHESTRATOR-IR.md)",
   "exports": {
@@ -32,10 +32,10 @@
     "check-types": "node scripts/generate-types.mjs --check"
   },
   "dependencies": {
-    "@volter/supercode-teams": "^0.3.343",
-    "@volter/supercode-terminal": "^0.3.9",
-    "@volter/supercode-harness-sdk": "^0.3.103",
-    "@volter/teams": "0.2.95",
+    "@volter/supercode-teams": "^0.3.345",
+    "@volter/supercode-terminal": "^0.3.10",
+    "@volter/supercode-harness-sdk": "^0.3.104",
+    "@volter/teams": "0.2.98",
     "@volter/ztrack": "^2.4.23",
     "yaml": "^2.9.0"
   },
@@ -61,5 +61,6 @@
     "board",
     "apply",
     "README.md"
-  ]
+  ],
+  "gitHead": "db4a88b4d2f670654fa8e57dbc3e93c7daa8d2bb"
 }

package/worker-route.mjs

@@ -27,9 +27,9 @@
 //
 // A route this table does not have is refused by name at launch, never run on the worker's default:
 // that would spend on a model nobody chose.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { MODEL_ARGUMENTS } from './activation.mjs';
+import { MODEL_ARGUMENTS, materializePersona, materializeSkills } from './activation.mjs';
 
 /** The Codex provider id a Hermes provider is served under. */
 const PROVIDER_ID = { custom: 'hermes_custom', openai: 'openai', 'openai-codex': 'hermes_codex' };
@@ -75,6 +75,7 @@ export function workerRoute(profile, worker, vault) {
     const forward = vault?.get?.('HERMES_CODEX_BASE_URL') ?? process.env.HERMES_CODEX_BASE_URL;
     if (!forward) throw new Error('model.provider openai-codex needs the Codex forward (HERMES_CODEX_BASE_URL in the home\'s .env, which the kit\'s start writes); refused rather than run on a login the worker would have to hold');
     table.base_url = forward;
+    table.requires_openai_auth = false;
     table.env_key = LITERAL_KEY_ENV;
     env[LITERAL_KEY_ENV] = 'valve';
     writeProviderTable(join(profile.dir, 'codex'), id, table);
@@ -126,7 +127,7 @@ function writeProviderTable(home, id, table) {
   const file = join(home, 'config.toml');
   const text = existsSync(file) ? readFileSync(file, 'utf8') : '';
   const header = `[model_providers.${id}]`;
-  const block = [header, ...Object.entries(table).map(([k, v]) => `${k} = ${JSON.stringify(String(v))}`)].join('\n');
+  const block = [header, ...Object.entries(table).map(([k, v]) => `${k} = ${typeof v === 'boolean' ? String(v) : JSON.stringify(String(v))}`)].join('\n');
   const lines = text.split('\n');
   const start = lines.findIndex((line) => line.trim() === header);
   let next;
@@ -138,3 +139,30 @@ function writeProviderTable(home, id, table) {
   }
   if (next !== text) writeFileSync(file, next, { mode: 0o600 });
 }
+
+/** The headful Codex lane must never fall back to the shared ChatGPT login.
+ * This returns only the configured forward's stand-in key and provider flags;
+ * it neither copies a credential nor starts a program or login. */
+export function codexPaneRoute(profile, worker, vault) {
+  if (worker?.harness !== 'codex' || hermesModel(profile)?.provider !== 'openai-codex')
+    throw new Error('headful Codex requires model.provider openai-codex and its configured HERMES_CODEX_BASE_URL; no shared-login pane was launched');
+  if (worker.home === 'user') throw new Error('headful Codex requires a profile home; no shared-login pane was launched');
+  const forward = vault?.get?.('HERMES_CODEX_BASE_URL') ?? process.env.HERMES_CODEX_BASE_URL;
+  if (!forward) throw new Error('headful Codex requires the configured HERMES_CODEX_BASE_URL; no shared-login pane was launched');
+  let endpoint;
+  try { endpoint = new URL(forward); } catch { throw new Error('the configured Codex forward is not an HTTP endpoint; no pane was launched'); }
+  if (!['http:', 'https:'].includes(endpoint.protocol) || endpoint.username || endpoint.password)
+    throw new Error('the configured Codex forward must be HTTP(S) without URL credentials; no pane was launched');
+  const home = join(profile.dir, 'codex');
+  if (Object.hasOwn(worker.env ?? {}, 'CODEX_HOME') && worker.env.CODEX_HOME !== home)
+    throw new Error('headful Codex has a different worker.env.CODEX_HOME; no shared-login pane was launched');
+  // lstat includes a dangling auth symlink. Do not read, unlink or migrate it.
+  try {
+    lstatSync(join(home, 'auth.json'));
+    throw new Error('the headful Codex profile home holds an auth.json entry; a login-free home is required and no credential was changed');
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  materializePersona(profile);
+  materializeSkills(profile);
+  const route = workerRoute(profile, worker, vault);
+  return { ...route, env: { CODEX_HOME: home, ...route.env } };
+}