@volter/supercode-orchestrator 0.5.205 → 0.5.207

package/connection.mjs

@@ -0,0 +1,153 @@
+// 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 { createHash, randomBytes } from 'node:crypto';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { fromContext } from '@volter/teams/context';
+import { supercodeHome } from '@volter/teams/home';
+
+export const MODULE_APPS = ['arcs-rooms','orchestration-rh2'];
+export function privateJson(path, value) {
+  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);
+}
+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);
+  }
+  const began=Date.now();
+  const response=await fetch(`${origin}${path}`,{method,redirect:'manual',signal:AbortSignal.timeout(path.endsWith('issuer-checks')?30000: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')}`}:{})},
+    ...(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})`);}
+  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) {
+  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'},
+    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'},
+    alerts:{role:record.alertRole??'admin'},standingFile:join(folder,'standing.json')};
+  privateJson(configPath,config);
+  privateJson(join(root,'apps',`${grant.name}.${record.id}.json`),{app:grant.name,connection:record.id,configPath,moduleRoot:record.moduleRoot,
+    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;
+  const logPath=join(dirname(connectionPath(root,id)),'runner.log'),fd=openSync(logPath,'a',0o600);
+  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 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)');
+  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');
+  // 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']){
+    if(!flags['teams-url']||!flags.team)throw new Error('--teams-token-file needs --teams-url and --team');
+    teams={server:new URL(flags['teams-url']).origin,team:flags.team};owner=readFileSync(flags['teams-token-file'],'utf8').trim();
+  }else{
+    const {context}=fromContext({supercodeHome:supercodeHome(),name:flags.context});
+    const {WorkspaceContexts}=await import('@volter/teams/context');
+    teams={server:context.origin,team:context.team_id};owner=new WorkspaceContexts(supercodeHome()).credential(context.credential_ref).token;
+  }
+  for(const origin of [ticket.origin,ticket.issuer,teams.server]){
+    const url=new URL(origin);if(url.origin!==origin||url.username||url.password||(url.protocol!=='https:'&&!(url.protocol==='http:'&&['127.0.0.1','localhost','[::1]'].includes(url.hostname))))throw new Error('connection endpoints must be exact HTTPS origins or loopback HTTP');
+  }
+  const id=createHash('sha256').update(`${ticket.scope}\0${ticket.issuer}\0${ticket.organization}\0${teams.server}\0${teams.team}\0${flags.source}`).digest('hex').slice(0,24);
+  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:[]};
+  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');
+  const lock=join(dirname(path),'runner.lock');
+  if(prior&&existsSync(lock)) {
+    const running=JSON.parse(readFileSync(lock,'utf8'));
+    let alive=false;try{process.kill(running.pid,0);alive=true;}catch(error){if(error.code!=='ESRCH')throw error;}
+    if(alive) {
+      if(flags['no-start'])throw new Error('stop this connection runner before preparing an owner handover');
+      return {connection:id,root,modules:record.grants.map(g=>g.name),runner:running.pid,calls:[]};
+    }
+  }
+  record.standingSelection=flags['standing-file']?JSON.parse(readFileSync(flags['standing-file'],'utf8')):(ticket.grants.find(g=>g.name==='arcs-rooms')?.rooms??[]).map(seat=>({profile:seat.key,roomKey:seat.key,roleKeys:seat.roleKeys}));
+  if(record.standingSelection.some(row=>!/^[-a-z0-9]{1,64}$/.test(row.profile??'')||!/^[-a-z0-9]{1,64}$/.test(row.roomKey??'')||row.session||row.agent))throw new Error('standing selections name a profile and Room key; agent/session ids come from the home');
+  // Registry entries may become visible during setup. They are never permission to start a writer.
+  record.preparing=true;record.paused=true;
+  privateJson(path,record);
+  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.rh2){
+      const recovering=typeof grant.redemption==='string';
+      grant.redemption??=randomBytes(32).toString('base64url');privateJson(path,record);
+      const body={clientId:selected.clientId,clientSecret:selected.clientSecret,code:selected.code,redemption:grant.redemption};
+      let exchanged;
+      if(recovering){
+        try{exchanged=await connectionCall(record,'rh2','POST','/api/v3/automation/apps/oauth/access',{...body,recover:true});}
+        catch(error){
+          if(error.code!=='invalid-grant')throw error;
+          if(!(Date.parse(selected.codeExpiresAt??ticket.expiresAt)>Date.now()))throw new Error(`${grant.name}: receipt-bound recovery refused; it needs the original receiver receipt, current client secret, live installation session and installer standing within the 24-hour recovery policy. An owner must explicitly reconsent after that window; reapply cannot replace redeemed custody.`);
+        }
+      }
+      // A recovery refusal can also mean the first request never committed. Only a live unspent code may
+      // enter first exchange; the server refuses this branch if a different receipt already spent it.
+      if(!exchanged){
+        if(!(Date.parse(selected.codeExpiresAt??ticket.expiresAt)>Date.now()))throw new Error(`${grant.name}: install code expired; apply the organization file again for unredeemed consent`);
+        exchanged=await connectionCall(record,'rh2','POST','/api/v3/automation/apps/oauth/access',body);
+      }
+      grant.rh2=exchanged.data;privateJson(path,record);
+    }
+    if(selected.teamsManifest&&!grant.teams){
+      if(!grant.registration){grant.stagedSecret??=`sca_${randomBytes(32).toString('base64url')}`;privateJson(path,record);grant.registration=(await connectionCall(record,'teams','POST',`/api/v1/teams/${encodeURIComponent(teams.team)}/apps`,{...selected.teamsManifest,name:`${selected.teamsManifest.name} (${id.slice(0,8)})`,secret:grant.stagedSecret},owner)).data;privateJson(path,record);}
+      grant.registration.secret=grant.stagedSecret;
+      if(!grant.consent){grant.stagedCode??=`sci_${randomBytes(32).toString('base64url')}`;privateJson(path,record);grant.consent=(await connectionCall(record,'teams','POST',`/api/v1/teams/${encodeURIComponent(teams.team)}/apps/${grant.registration.id}/installations`,{redirect_url:selected.teamsManifest.redirect_urls[0],state:id,actions:selected.teamsManifest.actions,code:grant.stagedCode},owner)).data;privateJson(path,record);}
+      grant.consent.code=grant.stagedCode;
+      grant.stagedCredential??=newInstallationToken();privateJson(path,record);
+      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(!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);}
+  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);
+  const pid=record.paused?null:startConnectionRunner(root,id);
+  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}))};
+}
+
+export function newInstallationToken(){return `sct_cred_${randomBytes(16).toString('hex')}.${randomBytes(32).toString('base64url')}`;}

package/index.d.ts

@@ -1,10 +1,10 @@
 // Types for the orchestrator IR — docs/ORCHESTRATOR-IR.md §2 is normative.
 //
-// ONT-6: every record shape is the Rust ontology's
-// (`crates/interchange/src/orchestration/`, `crates/interchange/src/ontology/`), reached
+// ONT-6: every record shape is the committed ontology contract's
+// (`sdk/interchange/ontology-schemas.json`), reached
 // through `./ontology.d.ts` — written by
 // `node sdk/orchestrator/scripts/generate-types.mjs` from `supercode ontology schema`.
-// Declare no record here; add the field in Rust and regenerate.
+// Declare no record here; update the contract and regenerate.
 
 import type {
   Access,
@@ -137,6 +137,7 @@ export function localForkAgent(options: {root: Path; org: string; server: string
 /** 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. */
 export function handOffAgents(root: Path, options?: {context?: string}): Array<{agent: string; error: string}>;
 export function localAgentRecord(root: Path, org: string, id: string): LocalAgent | null;
+export function homeAgentId(root: Path, scope: {org: string; server: string; name: string; profile?: string}): string | null;
 export function localAgentSessions(root: Path, org: string, id: string): Array<{session: string; machine: string | null; ended_at: number | null; end_reason: string | null}>;
 export function agentProfileMismatch(intent: unknown, resolved: unknown): import('@volter/teams/agent-profile').ProfileComparison;
 
@@ -439,8 +440,9 @@ export function mountOrchestratorMcp(o: {
   root: Path; profile: Profile; harness: string; surfaceKey?: string | null;
   launch?: { program: string; arguments?: string[]; env?: Record<string, string> };
   socketPath?: Path; serverPath?: Path; program?: string;
-  /** The agent the session is; its installed rh2-agent is mounted beside the orchestrator server as `rh2-agent`. */
-  agent?: string | null;
+  /** The Teams id of the agent the session is; the rh2-agent record installed for that id (`--agent`) is mounted beside
+   * the orchestrator server as `rh2-agent`. */
+  agentId?: string | null;
 }): { door: McpDoor; ran: string; launch: unknown; mcp_servers: McpServerLaunch[] | null; path: Path | null };
 
 export function socketPathFor(root: Path): Path;

package/index.mjs

@@ -41,5 +41,5 @@ export { hermesAccess, recordIncident, hermesToolEnv, hermesInstall } from './he
 export { holdGatewayLock, gatewayLockHeld, acquireTokenLock, releaseTokenLock, looksLikeGateway, TOKEN_SCOPES } from './hermes-locks.mjs';
 
 export { resolveAgentProfile, profileDifferences, sessionAgent } from "./agent-profiles.mjs";
-export { agentScope, localCardAgent, localProfileAgent, localAgentRecord, localAgentSessions, declareAgentIntent, agentRunForKey, agentIntent, assignAgent, reassignAgent, activeAgentAssignments, finishAgentAssignment, recordAgentRun, recordNativeAgentSession, agentRunForSession, agentPreamble, agentEnvironment, agentProfileMismatch, localForkAgent, handOffAgents} from "./agents.mjs";
+export { agentScope, localCardAgent, localProfileAgent, localAgentRecord, homeAgentId, localAgentSessions, declareAgentIntent, agentRunForKey, agentIntent, assignAgent, reassignAgent, activeAgentAssignments, finishAgentAssignment, recordAgentRun, recordNativeAgentSession, agentRunForSession, agentPreamble, agentEnvironment, agentProfileMismatch, localForkAgent, handOffAgents} from "./agents.mjs";
 export { agentStateHome,materializeAgentHome } from './agent-home.mjs';

package/installed-apps.mjs

@@ -9,9 +9,11 @@ import { delimiter, isAbsolute, join } from 'node:path';
 export const APPS_DIR = 'apps';
 /** The apps this orchestrator can host, by name: what each installs and which adapter it attaches. */
 export const INSTALLABLE_APPS = Object.freeze({
+  'arcs-rooms': { side: 'rh2', module: true, describe: 'arcs-rooms installed module' },
+  'orchestration-rh2': { side: 'rh2', module: true, describe: 'orchestration-rh2 installed module' },
   'room-chat': { side: 'rh2', adapter: 'rh2', describe: 'Room chat → orchestrator: a person\'s line in an RH2 Room reaches the agent seated there' },
-  // An agent the RH2 organization declares is one participant there: its chat, its DM and its call are its own agent
-  // principal, never an automation beside it. One record per agent (`rh2-agent.<agent>`).
+  // An agent the RH2 organization declares is one participant there: its chat and its call are its own agent principal,
+  // never an automation beside it. One record per agent, bound to its Teams id (`rh2-agent.<name>`, `agentId`).
   'rh2-agent': { side: 'rh2', adapter: 'rh2', perProfile: true, describe: 'An agent the RH2 organization declares, in its Rooms as its own principal' },
 });
 
@@ -26,16 +28,18 @@ export function installedApps(root) {
   }).filter((record) => INSTALLABLE_APPS[record.app ?? record.name]);
 }
 
-/** An RH2 agent's own identity for a mail agent: the token the organization's admin issued that agent principal (RH2's
- * agent-token door), kept once RH2 answers it in that organization. */
-export async function installAgent({ root, origin, organization, principal, token, profile, fetchImpl = globalThis.fetch }) {
+/** An RH2 agent's own identity: the token the organization's admin issued that agent principal (RH2's agent-token door),
+ * kept once RH2 answers it in that organization, for the one agent it is (`--agent`, its Teams id). It is found by that
+ * id alone (installedAgentRecord): a name or profile another agent shares never reaches it. */
+export async function installAgent({ root, origin, organization, principal, token, profile, agent, fetchImpl = globalThis.fetch }) {
   if (!profile) throw new Error('an RH2 agent is installed for a profile (--profile <agent>)');
+  if (!/^agent_[A-Za-z0-9_-]+$/.test(String(agent))) throw new Error('--agent is the Teams id of the agent this identity is (agent_…)');
   if (!/^prn_/.test(String(principal))) throw new Error('--principal is the RH2 agent\'s principal id (prn_…)');
   if (!rh2Origin(origin)) throw new Error('the RH2 origin is an https URL');
   const base = new URL(origin).origin;
   const response = await fetchImpl(`${base}/api/v3/rooms`, { headers: { authorization: `Bearer ${token}`, 'x-rh2-organization': organization, origin: base, accept: 'application/json' } });
   if (!response.ok) throw new Error(`RH2 refused the agent's token in ${organization}: HTTP ${response.status}`);
-  const record = { app: 'rh2-agent', side: 'rh2', origin: base, organizationId: organization, principalId: principal, profile, token, installedAt: new Date().toISOString() };
+  const record = { app: 'rh2-agent', side: 'rh2', origin: base, organizationId: organization, principalId: principal, agentId: agent, profile, token, installedAt: new Date().toISOString() };
   mkdirSync(join(root, APPS_DIR), { recursive: true, mode: 0o700 });
   const path = recordPath(root, 'rh2-agent', profile);
   const pending = `${path}.${process.pid}.tmp`;
@@ -44,19 +48,17 @@ export async function installAgent({ root, origin, organization, principal, toke
   return { ...record, name: `rh2-agent.${profile}`, token: undefined };
 }
 
-/** The rh2-agent record installed for `agent` (an agent name, as `apps install rh2-agent --profile <agent>` names it),
- * or null. */
-export function installedAgentRecord(root, agent) {
-  if (typeof agent !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(agent)) return null;
-  const path = recordPath(root, 'rh2-agent', agent);
-  if (!existsSync(path)) return null;
-  try {
-    const record = JSON.parse(readFileSync(path, 'utf8'));
-    // the origin install accepted (https, or a loopback for a local RH2), held again wherever the record is used
-    return record?.app === 'rh2-agent' && record.token && rh2Origin(record.origin) ? record : null;
-  } catch {
-    return null;
-  }
+/** The rh2-agent record that is the identity of `agentId` (an agent's Teams id, as `apps install rh2-agent --agent`
+ * named it), or null. It is found by that id alone, never by a name or profile another agent may share (a later
+ * generation of a card's agent, another home's root agent named after the same folder), and only when exactly one
+ * record names it. Its file name (`--profile`) is a label. */
+export function installedAgentRecord(root, agentId) {
+  if (typeof agentId !== 'string' || !/^agent_[A-Za-z0-9_-]+$/.test(agentId)) return null;
+  let records;
+  try { records = installedApps(root); } catch { return null; }
+  // the origin install accepted (https, or a loopback for a local RH2), held again wherever the record is used
+  const own = records.filter((record) => record.app === 'rh2-agent' && record.agentId === agentId && record.token && rh2Origin(record.origin));
+  return own.length === 1 ? own[0] : null;
 }
 
 /** Whether `origin` is one an RH2 app may be installed for: https, or a loopback for a local RH2. */
@@ -81,6 +83,7 @@ export function rh2AgentEnv(record) {
 /** Exchange an RH2 install code for the installation's token and keep the record. */
 export async function installApp({ root, name, origin, clientId, clientSecret, code, profile = 'default', fetchImpl = globalThis.fetch }) {
   const app = INSTALLABLE_APPS[name];
+  if(app?.module)throw new Error('module apps are consented and installed together by orchestrator connect');
   if (!app) throw new Error(`no installable app named ${name} (${Object.keys(INSTALLABLE_APPS).join(', ')})`);
   if (!rh2Origin(origin)) throw new Error('the RH2 origin is an https URL');
   const base = new URL(origin).origin;
@@ -104,4 +107,12 @@ export function removeApp(root, name) {
 }
 
 /** What `apps list` shows: never the token. */
-export const appView = (record) => ({ name: record.name, side: record.side, origin: record.origin, organization: record.organizationId, principal: record.principalId, installation: record.installationId, profile: record.profile, expires_at: record.expiresAt });
+export const appView = (record) => ({ name: record.name, side: record.side, origin: record.origin, organization: record.organizationId, principal: record.principalId, agent: record.agentId, installation: record.installationId, profile: record.profile, expires_at: record.expiresAt });
+
+/** The same home's app registry drives module hosting after a daemon restart. */
+export async function startInstalledModules(root) {
+  if(!root)return [];
+  const {startConnectionRunner}=await import('./connection.mjs');
+  const ids=[...new Set(installedApps(root).filter(app=>INSTALLABLE_APPS[app.app]?.module).map(app=>app.connection))];
+  return ids.map(id=>({connection:id,pid:startConnectionRunner(root,id)})).filter(row=>row.pid!==null);
+}

package/loop.mjs

@@ -9,7 +9,7 @@ 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 { INSTRUCTION_ARGUMENTS, NAME_ARGUMENTS, activationEnv, activationCwd, declareWorkerHome, approvalPolicy, sandboxArguments, limitArguments, materializePersona, materializeSkills, modelArguments, turnCounter, userHomeArguments, userHomePersona } from './activation.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 { hermesAccess, hermesApproval, untrustedServerVerdict, hermesToolEnv, memorySnapshot, mirrorSession, mirrorState, recordIncident, sealMirror } from './hermes-cli.mjs';
 import { hermesSessionKey, homeChannel } from './ir.mjs';
@@ -134,7 +134,19 @@ export class Orchestrator {
 
   /** The folder written from state, and each profile's `cron/jobs.json` as that write left it. */
   async save() {
-    await save(this.state, this.state.root);
+    const { rejected } = await save(this.state, this.state.root);
+    // An entry the store could not read was written as the home last held it (or, never held, left out), and is again
+    // at every save while it stays as it is; the log names it once per reason, not once per save.
+    for (const { collection, key, reason, kept_stored: kept } of rejected) {
+      const said = `${collection}\u0000${key}\u0000${reason}`;
+      if ((this.rejectedSaid ??= new Set()).has(said)) continue;
+      this.rejectedSaid.add(said);
+      // Said plainly: this daemon keeps its unreadable version, and the home on disk holds another, so its next start
+      // takes up what is on disk, not what runs now.
+      this.log('warn', kept
+        ? `${collection} ${key} could not be saved (${reason}): the home keeps its stored version of it, and the orchestrator will restart from that stored version, not from what runs now`
+        : `${collection} ${key} could not be saved (${reason}): it is left out of the home, and the orchestrator will restart without it`);
+    }
     this.jobsWritten = this.jobsFiles();
   }
 
@@ -325,6 +337,8 @@ export class Orchestrator {
       case 'budget_refused': return this.tellBudgetRefusal(effect);
       case 'save': await this.save(); return;
       case 'log': this.log(effect.level, effect.message); return;
+      // an operator's refusal, answered by the operator door (operator.mjs); recorded here
+      case 'refused': this.log('info', effect.message); return;
       default: this.log('warn', `unknown effect ${effect.type}`);
     }
   }
@@ -398,14 +412,17 @@ export class Orchestrator {
   /** Wait for admitted host tasks; useful for deterministic tests and graceful shutdown. */
   async drainHosted() { await Promise.allSettled([...this.hostedTasks]); }
 
-  async startRuntime({ profile: profileName, keyString, worker, resume_runtime_id = null,agent_as=null,new_fork=false,run_key=null,starter_session=null,agent:agentName=null }) {
+  async startRuntime({ profile: profileName, keyString, worker, resume_runtime_id = null,agent_as=null,new_fork=false,run_key=null,starter_session=null,agent:agentName=null,concurrent=false }) {
     const profile = this.state.profiles[profileName];
     const lid = leaseId(profileName, keyString);
-    const cwd = activationCwd(profile, worker.cwd);
-    materializePersona(profile);
-    materializeSkills(profile);
-    let launch,agent,scope,context,agentPrompt,main,agentHome;
+    // Every step of a start is inside one of the two failure handlers below, which end the session with the reason
+    // (`start failed: …`, kept as its end_detail): a step outside them failed the effect with the session left starting.
+    let launch,agent,scope,context,agentPrompt,main,agentHome,cwd;
     try {
+      materializePersona(profile);
+      materializeSkills(profile);
+      // the profile's own subfolder is made; a missing folder outside it refuses the start, naming it (workerCwd)
+      cwd = workerCwd(profile, worker.cwd);
       // The launch asks Teams nothing (D137): the agent is this home's minted identity, its declaration handed to this
       // machine's daemon, its reader context the one this machine holds (the daemon delegates one when it binds the
       // session), its earlier sessions the ones this home ran.
@@ -419,7 +436,8 @@ export class Orchestrator {
       agent??=await localProfileAgent({root:this.state.root,org:scope.org,server:scope.server,profiles:this.state.profiles,profile:profileName,agent:agentName,declarations:this.state.agents});
       if(!scope.offline)for(const pending of await handOffAgents(this.state.root,{context}))this.log('warn',`agent ${pending.agent}: ${pending.error}`);
       agent.intended.resolved.worker={...agent.intended.resolved.worker,...worker,cwd};
-      main=new_fork||!agent.identity.main_session;
+      // A session started on request (`sessions.launch`) is the agent working elsewhere: never its main session.
+      main=concurrent?false:new_fork||!agent.identity.main_session;
       if(resume_runtime_id&&!new_fork){
         const owner=agentRunForSession(this.state.root,[`${worker.harness}:${resume_runtime_id}`]);
         if(owner&&owner.agent_id!==agent.identity.id)throw new Error('the resumed session is not owned by this profile agent');
@@ -437,7 +455,9 @@ export class Orchestrator {
       const tools = worker.harness === 'hermes' ? {} : hermesToolEnv(agentHome);
       const env = { ...tools, ...activationEnv({ root: this.state.root, profile, surfaceKey: keyString, vault: this.vault }), ...route.env,...agentEnvironment(agent,{root:this.state.root,context:localReaderContext(scope.org,agent.identity.id)??undefined,main}) };
       env.HERMES_HOME=agentHome;
-      declareWorkerHome({ harness: worker.harness, env, cwd, log: (level, message) => this.log(level, message) });
+      // its folder a sync root first (a home is declared on the roots covering its folder), then its config home
+      const say = (level, message) => this.log(level, message);
+      void declareWorkerFolder({ cwd, root: this.state.root, profile: profileName, profileDirs: Object.values(this.state.profiles ?? {}).map((each) => each?.dir), context, scope, log: say }).then(() => declareWorkerHome({ harness: worker.harness, env, cwd, log: say }));
       // All sessions of this agent carry its state; a shared profile contributes configuration only.
       const memory = INSTRUCTION_ARGUMENTS[worker.harness] ? await memorySnapshot(agentHome).catch((error) => { this.log('warn', `memory ${keyString}: ${error.message}`); return ''; }) : '';
       // a worker in the user's own home carries its persona there too (its config home's CLAUDE.md is the user's)
@@ -449,20 +469,20 @@ export class Orchestrator {
       this.enqueue(events.worker({ profile: profileName, keyString, runtime_id: null, ev: { kind: 'error', message: `start failed: ${error.message}` }, at: this.clock() }));
       return;
     }
-    // §7: the model-facing door. One MCP server per worker session, bound to
-    // this conversation, mounted through whatever door this harness publishes.
-    const mount = mountOrchestratorMcp({
-      root: this.state.root, profile, harness: worker.harness, surfaceKey: keyString, launch,
-      socketPath: this.bridge?.path ?? socketPathFor(this.state.root), vault: this.vault,
-      // the agent's own sessions speak in RH2 as it; a worker launched to act for it (agent_as) does not
-      agent: agent_as ? null : agent?.identity?.name ?? null,
-    });
-    this.log('info', `mcp mount (${worker.harness}, ${mount.door}): ${mount.ran}`);
-    if (resume_runtime_id) resume_runtime_id = await this.continueFromHermes(profile, keyString, worker, resume_runtime_id, cwd,agentHome);
-    // read before the runtime exists: a runtime emits from the moment it is made
-    const steer = Boolean((await this.descriptorFor(worker.harness).catch(() => null))?.runtime?.capabilities?.steer);
-    let runtime;
+    let runtime, steer;
     try {
+      // §7: the model-facing door. One MCP server per worker session, bound to
+      // this conversation, mounted through whatever door this harness publishes.
+      const mount = mountOrchestratorMcp({
+        root: this.state.root, profile, harness: worker.harness, surfaceKey: keyString, launch,
+        socketPath: this.bridge?.path ?? socketPathFor(this.state.root), vault: this.vault,
+        // the agent's own sessions speak in RH2 as it; a worker launched to act for it (agent_as) does not
+        agentId: agent_as ? null : agent?.identity?.id ?? null,
+      });
+      this.log('info', `mcp mount (${worker.harness}, ${mount.door}): ${mount.ran}`);
+      if (resume_runtime_id) resume_runtime_id = await this.continueFromHermes(profile, keyString, worker, resume_runtime_id, cwd,agentHome);
+      // read before the runtime exists: a runtime emits from the moment it is made
+      steer = Boolean((await this.descriptorFor(worker.harness).catch(() => null))?.runtime?.capabilities?.steer);
       const policy = approvalPolicy(profile, worker.harness);
       const params = { harness: worker.harness, cwd, launch: mount.launch, ...(mount.mcp_servers ? { mcp_servers: mount.mcp_servers } : {}), ...(policy ? { approval_policy: policy } : {}) };
       if (resume_runtime_id && (await this.descriptorFor(worker.harness).catch(() => null))?.runtime?.capabilities?.resume_session) {
@@ -480,23 +500,58 @@ export class Orchestrator {
       this.enqueue(events.worker({ profile: profileName, keyString, runtime_id: null, ev: { kind: 'error', message: `start failed: ${error.message}` }, at: this.clock() }));
       return;
     }
-    // `started` is queued before the runtime can be heard (steer was read
-    // before the start), so none of its events arrives ahead of its lease
-    const previous = this.runtimes.get(lid);
-    if (previous && previous !== runtime) this.retired.set(previous.handle.runtime_id, previous);
-    this.runtimes.set(lid, runtime);
-    if(!INSTRUCTION_ARGUMENTS[worker.harness])(this.runtimeAgentPreambles??=new Map()).set(lid,agentPrompt);
-    const session=`${worker.harness}:${runtime.handle.runtime_id}`;
-    recordAgentRun(this.state.root,scope.org,agent.identity.id,{session,machine:null,run:run_key??lid,profile:agent.intended.resolved,main,starterSession:starter_session});
-    this.enqueue(events.worker({
-      profile: profileName, keyString, runtime_id: runtime.handle.runtime_id,
-      ev: { kind: 'started', runtime_id: runtime.handle.runtime_id, session_id: runtime.handle.runtime_id, connection: runtime.connection, harness: worker.harness, steer },
-      at: this.clock(),
-    }));
-    this.watch(profileName, keyString, runtime);
+    // The runtime runs from here, so every later step is one whose failure ends it: until `started` is queued, the
+    // runtime is closed here and the start fails as every earlier step's does; after, the error is the runtime's own,
+    // and the session's end closes it (its lease is held by then). None leaves a session `starting` with a runtime
+    // nobody watches.
+    let started = false;
+    try {
+      // the agent run is recorded before the runtime is held here, so a refused record (agents.mjs: a busy store, an
+      // ownership change) leaves nothing of it behind
+      const session=`${worker.harness}:${runtime.handle.runtime_id}`;
+      recordAgentRun(this.state.root,scope.org,agent.identity.id,{session,machine:null,run:run_key??lid,profile:agent.intended.resolved,main,starterSession:starter_session,conversation:!run_key});
+      const previous = this.runtimes.get(lid);
+      if (previous && previous !== runtime) this.retired.set(previous.handle.runtime_id, previous);
+      this.runtimes.set(lid, runtime);
+      if(!INSTRUCTION_ARGUMENTS[worker.harness])(this.runtimeAgentPreambles??=new Map()).set(lid,agentPrompt);
+      // `started` is queued before the runtime can be heard (steer was read
+      // before the start), so none of its events arrives ahead of its lease
+      this.enqueue(events.worker({
+        profile: profileName, keyString, runtime_id: runtime.handle.runtime_id,
+        ev: { kind: 'started', runtime_id: runtime.handle.runtime_id, session_id: runtime.handle.runtime_id, connection: runtime.connection, harness: worker.harness, steer },
+        at: this.clock(),
+      }));
+      started = true;
+      this.watch(profileName, keyString, runtime);
+    } catch (error) {
+      if (started) {
+        this.enqueue(events.worker({ profile: profileName, keyString, runtime_id: runtime.handle.runtime_id, ev: { kind: 'error', message: `start failed: ${error.message}` }, at: this.clock() }));
+        return;
+      }
+      if (this.runtimes.get(lid) === runtime) this.runtimes.delete(lid);
+      try { await runtime.close(); } catch { /* already gone */ }
+      this.enqueue(events.worker({ profile: profileName, keyString, runtime_id: null, ev: { kind: 'error', message: `start failed: ${error.message}` }, at: this.clock() }));
+      return;
+    }
     return runtime.handle;
   }
 
+  /**
+   * 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
+   * exactly as every session of the agent is (persona, skills, home, model route, vault, instructions with its preamble
+   * for a concurrent session, persona and memory, the orchestrator's MCP door, the approval policy, the agent's
+   * environment); its first turn is its caller's first line to it.
+   */
+  async prepareLaunch({ profile: profileName, agentId }) {
+    const profile = this.state.profiles[profileName];
+    if (!profile?.worker) throw new Error(`profile ${profileName} has no worker to start a session with`);
+    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: profileName, agent: profileName, declarations: this.state.agents });
+    if (agent.identity.id !== agentId) throw new Error(`profile ${profileName} runs agent ${agent.identity.id}, not ${agentId}`);
+    return { agent: agent.identity.id };
+  }
+
   /** Fork through native handoff/materialization. The source remains retained and the child has its own id. */
   async forkRuntime({profile:profileName,keyString,parent,locator:given,name,key,machine=null}) {
     if(machine)throw new Error('fork this owned workspace on its execution host; move it through the workspace door afterward');

package/mcp/bridge.mjs

@@ -133,6 +133,18 @@ async function dispatchOperator(orch, { op, args, profile }, log) {
       const forked = await orch.forkRuntime({ profile: name, keyString: surfaceKeyString(key), parent: a.parent, locator: { harness: a.harness, session_id: a.session_id }, name: a.name, key: a.key, machine: a.machine ?? null });
       answer = { ok: true, result: { ran: `forked ${a.harness}:${a.session_id} as agent ${forked.agent.path} (${forked.agent.id})`, agent: forked.agent, locator: forked.locator } };
     } catch (error) { answer = { ok: false, error: error.message }; }
+  } else if (op === 'sessions.launch') {
+    // A concurrent session of the profile's agent, on request: the agent is checked here, where the home's agents are;
+    // the start is the reducer's, ordered on the loop's queue like any other, and its refusal is this answer's.
+    try {
+      const a = args ?? {};
+      if (typeof a.agent_id !== 'string' || !a.agent_id || typeof a.key !== 'string' || !a.key) throw new Error('sessions.launch needs agent_id and key');
+      if (typeof a.opening !== 'string' || !a.opening.trim() || a.opening.length > 4000) throw new Error('sessions.launch needs the requester\'s opening message, up to 4000 characters');
+      // The agent's preamble is already in the session's instructions (startRuntime); the requester's own words are its
+      // first turn, and nothing else is.
+      await orch.prepareLaunch({ profile: name, agentId: a.agent_id });
+      answer = await applyOperator(orch.state, op, { key: a.key, agent_id: a.agent_id, input: a.opening.trim() }, name, orch.clock(), (event) => orch.dispatch(event));
+    } catch (error) { answer = { ok: false, error: error.message }; }
   } else try {
     answer = await applyOperator(orch.state, op, args ?? {}, name, orch.clock(), (event) => orch.dispatch(event));
   } catch (error) {

package/mcp/hermes-kanban-tools.json

@@ -102,11 +102,7 @@
         },
         "commit": {
           "type": "string",
-          "description": "Exact pushed branch head for a subtask, or merged deployment commit for an arc."
-        },
-        "ci_run": {
-          "type": "integer",
-          "description": "GitHub Actions deployment run id for that exact commit."
+          "description": "Exact pushed source head for a subtask or independently reviewed arc."
         },
         "branch": {
           "type": "string",
@@ -354,7 +350,7 @@
   },
   {
     "name": "kanban_attachments",
-    "description": "List the files attached to a task: id, filename, content_type, size, who uploaded it, and the absolute on-disk path you can read.",
+    "description": "List a task's attachment metadata. Supply attachment_id to read its bytes through the board as a bounded base64 range; no host filesystem access is needed. Carry the first response version on subsequent ranges.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -362,6 +358,26 @@
           "type": "string",
           "description": "Task id. If omitted, defaults to HERMES_KANBAN_TASK from the env (the task the dispatcher spawned you to work on)."
         },
+        "attachment_id": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Read this attachment of the named task; omit to list metadata."
+        },
+        "offset": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Byte offset, default 0. A nonzero offset requires version."
+        },
+        "length": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1048576,
+          "description": "Maximum bytes in this range, default 1048576."
+        },
+        "version": {
+          "type": "string",
+          "description": "The first range's filesystem metadata version; changed attachments refuse."
+        },
         "board": {
           "type": "string",
           "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env \u2192 HERMES_KANBAN_BOARD env \u2192 the 'current' symlink under the kanban home \u2192 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
@@ -561,14 +577,6 @@
           "type": "string",
           "description": "Pushed branch head for a source verdict or subtask, or merged commit for final arc completion."
         },
-        "ci_run": {
-          "type": "integer",
-          "description": "Legacy receipt field; deployment is not a board completion requirement."
-        },
-        "deployed_sha": {
-          "type": "string",
-          "description": "Legacy receipt field; deployment is not a board completion requirement."
-        },
         "branch": {
           "type": "string",
           "description": "The pushed worktree branch the reviewer inspected."