@volter/supercode-orchestrator 0.5.214 → 0.5.216

package/bin/agent-channel.mjs

@@ -1,199 +1,55 @@
-// `supercode-orchestrator agent-channel --agent <name>`: an agent's account Room, carried to its one mailbox
-// (docs/adr/0008-agent-mailbox.md, decisions 24-25). With `--platform slack` or `--platform jira` it carries another
-// channel to that mailbox instead, through the same bridge (company RFC 0026 decision 3: an engagement's Slack channel
-// and its client's ticket comments are channels of its account manager):
+// `supercode-orchestrator agent-channel --agent <name> --platform slack|jira`: a channel carried to an agent's one mailbox
+// (docs/adr/0008-agent-mailbox.md) through the mailbox bridge (company RFC 0026 decision 3: an engagement's Slack
+// channel and its client's ticket comments are channels of its account manager):
 //   --platform slack --slack-channel <id>[,<id>]   the Chat SDK's Slack (Socket Mode), SLACK_BOT_TOKEN and SLACK_APP_TOKEN
 //                                                   from the environment; only the named channels' lines are filed
 //   --platform jira --site <url> --jql <jql>        the tickets' comments (adapters/jira-comments.mjs), JIRA_EMAIL and
 //                                                   JIRA_API_TOKEN (or JIRA_TOKEN) from the environment
-// The RH2 account Room: the Room sits on the organization's floor (the RH2 bot's
-// organization), with the agent as its one participant: every line a person posts there is filed as mail to the agent,
-// and every answer is posted back anchored at its thread's root, by `AgentMailboxBridge` over the RH2 adapter.
-//
-// The Room is found by its key (`--room-key`, default `account-<agent>`), or opened once when the organization has
-// none: from the organization's preset (`--preset`) with the principal (`--principal`, RH2's principal id) and the agent
-// both seated in the role the org's floor names (`--role`), and the agent answering every line of its conversation.
-// Authority comes from a stated role: opening a Room without both is refused. `--room <id>` names an existing Room
-// instead and opens nothing.
-//
-// RH2 is reached as the agent's own principal where the organization declares the agent (docs/adr/0017: `supercode
-// orchestrator apps install rh2-agent … --agent <its Teams id>` in the home, `--root` or HERMES_HOME), the record bound to
-// the agent this channel names with `--agent-id`, else to the id the home holds for that agent (homeAgentId: its declared
-// identity, else its profile's by the home's agent layer `agents.json`), so its threads and its call are one participant
-// and no other agent's record is taken; otherwise through the Room-chat app's installation for this agent (`apps install
-// room-chat … --profile <agent>`). The record's origin, organization, principal and token are the agent's identity in the
-// Room. The bridge's thread anchors are kept in `--state`.
-//
-// The agent's seat in its Room carries its main session (RFC 0020 decision 26): where this machine is in a Teams team,
-// the seat is bound to the main session (`supercode sessions bind`, the session owner's view binding for the seat), and
-// rebound to each new main session, as the Agents → Room agents app binds an arc's agent. Until the main session is in
-// the team's catalog the binding is retried.
+// An agent's RH2 Rooms are not carried here: the Workplace's join command brings the agent in, its seat carries the
+// agent's current session, and the Workplace delivers the Room's lines to that session itself (runhuman-2 ADR 0063).
 import { parseArgs } from 'node:util';
-import { execFileSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
-import { Rh2Adapter } from '../adapters/rh2.mjs';
 import { AgentMailboxBridge } from '../adapters/agent-mailbox.mjs';
 import { JiraCommentsAdapter } from '../adapters/jira-comments.mjs';
 import { ChatSdkAdapter } from '../adapters/chat-sdk.mjs';
-import { installedAgentRecord, installedApps } from '../installed-apps.mjs';
-import { agentScope, homeAgentId } from '../agents.mjs';
 
 const { values } = parseArgs({
   args: process.argv.slice(3),
-  options: { agent: { type: 'string' }, 'agent-id': { type: 'string' }, root: { type: 'string' }, room: { type: 'string' }, 'room-key': { type: 'string' }, 'room-name': { type: 'string' }, principal: { type: 'string' }, preset: { type: 'string' }, role: { type: 'string' }, state: { type: 'string' }, platform: { type: 'string' }, site: { type: 'string' }, jql: { type: 'string' }, 'slack-channel': { type: 'string' }, help: { type: 'boolean' } },
+  options: { agent: { type: 'string' }, state: { type: 'string' }, platform: { type: 'string' }, site: { type: 'string' }, jql: { type: 'string' }, 'slack-channel': { type: 'string' }, help: { type: 'boolean' } },
 });
-if (values.help || !values.agent) {
-  console.log('supercode-orchestrator agent-channel --agent <name> [--agent-id <its Teams id>] [--root <home>] [--room <id> | --room-key <key> [--principal <rh2 principal id> --preset <preset id> --role <role key> [--room-name <name>]]] [--state <file>]\n       supercode-orchestrator agent-channel --agent <name> --platform slack --slack-channel <id>[,<id>] [--state <file>]\n       supercode-orchestrator agent-channel --agent <name> --platform jira --site <url> --jql <jql> [--state <file>]');
+if (values.help || !values.agent || !values.platform) {
+  console.log('supercode-orchestrator agent-channel --agent <name> --platform slack --slack-channel <id>[,<id>] [--state <file>]\n       supercode-orchestrator agent-channel --agent <name> --platform jira --site <url> --jql <jql> [--state <file>]');
   process.exit(values.help ? 0 : 2);
 }
 const log = (level, line) => (level === 'debug' ? undefined : console.error(`${new Date().toISOString()} ${level} ${line}`));
-if (values.platform && values.platform !== 'rh2') {
-  const statePath = (name) => values.state ?? join(homedir(), '.config', 'supercode', 'agent-channels', `${values.agent}.${name}.json`);
-  let adapter;
-  if (values.platform === 'jira') {
-    if (!values.site || !values.jql) { console.error('agent-channel: --platform jira needs --site and --jql'); process.exit(2); }
-    const authorization = process.env.JIRA_EMAIL && process.env.JIRA_API_TOKEN
-      ? `Basic ${Buffer.from(`${process.env.JIRA_EMAIL}:${process.env.JIRA_API_TOKEN}`).toString('base64')}`
-      : process.env.JIRA_TOKEN ? `Bearer ${process.env.JIRA_TOKEN}` : null;
-    if (!authorization) { console.error('agent-channel: --platform jira needs JIRA_EMAIL and JIRA_API_TOKEN (or JIRA_TOKEN) in its environment'); process.exit(2); }
-    adapter = new JiraCommentsAdapter({ site: values.site, jql: values.jql, authorization, statePath: `${statePath('jira')}.comments`, log });
-  } else if (values.platform === 'slack') {
-    const channels = new Set(String(values['slack-channel'] ?? '').split(',').map((c) => c.trim()).filter(Boolean));
-    if (!channels.size) { console.error('agent-channel: --platform slack needs --slack-channel <id>: an agent is carried only the channels named'); process.exit(2); }
-    if (!process.env.SLACK_BOT_TOKEN || !process.env.SLACK_APP_TOKEN) { console.error('agent-channel: --platform slack needs SLACK_BOT_TOKEN and SLACK_APP_TOKEN in its environment'); process.exit(2); }
-    // The Slack SDK adapter is built here, in Socket Mode, from this process's own environment: the wrapper's own path
-    // reads a profile's .env, and a channel process has no profile folder. SLACK_API_URL (a twin's) is honoured.
-    let createSlackAdapter;
-    try { ({ createSlackAdapter } = await import('@chat-adapter/slack')); } catch (error) { console.error(`agent-channel: @chat-adapter/slack is not installed (${error.message})`); process.exit(2); }
-    const sdkAdapter = createSlackAdapter({ botToken: process.env.SLACK_BOT_TOKEN, appToken: process.env.SLACK_APP_TOKEN, mode: 'socket', ...(process.env.SLACK_API_URL ? { apiUrl: process.env.SLACK_API_URL } : {}) });
-    const slack = new ChatSdkAdapter({ platform: 'slack', profile: values.agent, channel: { enabled: true, extra: {} }, sdkAdapter, log });
-    // Only the named channels' lines reach the mailbox; answers go back through the same adapter.
-    adapter = { platform: 'slack', connect: (emit) => slack.connect((event) => { if (channels.has(String(event.key?.chat_id))) emit(event); }), send: (target, content) => slack.send(target, content), close: () => slack.close?.() };
-  } else { console.error(`agent-channel: --platform is rh2, slack or jira (got ${values.platform})`); process.exit(2); }
-  const client = new SupercodeHarnessClient(process.env.SUPERCODE_BIN ? { command: process.env.SUPERCODE_BIN } : {});
-  const bridge = new AgentMailboxBridge({ adapter, client, agent: values.agent, platform: values.platform, fromName: `${values.platform}-${values.agent}`, log, statePath: statePath(values.platform) });
-  await bridge.start();
-  log('info', `${values.agent}: ${values.platform} is carried to its mailbox`);
-  const stop = async () => { await bridge.stop(); await adapter.close?.(); await client.close?.(); process.exit(0); };
-  process.on('SIGTERM', stop);
-  process.on('SIGINT', stop);
-} else {
-const root = values.root ?? process.env.HERMES_HOME;
-// The agent's own record only when it is this agent's (bound to its Teams id, as an agent's sessions are mounted with it):
-// the id named, else the one this home holds for the agent, read and never minted.
-const agentId = values['agent-id'] ?? (root ? (() => {
-  try {
-    // a named profile implies its own agent: a home with no agent layer runs the agent on the profile of its name
-    let layer = {};
-    try { layer = JSON.parse(readFileSync(join(root, 'agents.json'), 'utf8')); } catch (error) { if (error.code !== 'ENOENT') throw error; }
-    const { org, server } = agentScope(process.env.SUPERCODE_CONTEXT);
-    return homeAgentId(root, { org, server, name: values.agent, profile: layer.agents?.[values.agent]?.profile ?? values.agent });
-  } catch (error) { log('warn', `${values.agent}: its id in ${root} was not read (${error.message})`); return null; }
-})() : null);
-const own = root && agentId ? installedAgentRecord(root, agentId) : null;
-const installation = own ?? (root ? installedApps(root).find((app) => app.app === 'room-chat' && app.profile === values.agent) : undefined);
-if (!installation) {
-  console.error(`agent-channel: ${values.agent} has no RH2 identity in ${root ?? '(no home: --root or HERMES_HOME)'}; install its agent (supercode orchestrator apps install rh2-agent … --agent ${agentId ?? '<its Teams id>, and run this with --agent-id <its Teams id>'}) or Room chat for it (apps install room-chat … --profile ${values.agent})`);
-  process.exit(1);
-}
-const identity = { api_url: installation.origin, organization: installation.organizationId, principal_id: installation.principalId, token: installation.token };
-const adapter = new Rh2Adapter({ log, channel: { enabled: true, extra: identity } });
-/** One RH2 write, its `data` returned; a refusal throws with its status. */
-async function post(path, body) {
-  const res = await adapter.post(path, body);
-  if (!res.ok) throw new Error(`POST ${path} -> HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
-  return (await res.json()).data ?? {};
-}
-
-/** The account Room: named, found by its key, or opened once. */
-async function accountRoom() {
-  if (values.room) return values.room;
-  const key = values['room-key'] ?? `account-${values.agent}`;
-  const listing = await adapter.get('/rooms');
-  const found = (Array.isArray(listing) ? listing : listing.rooms ?? []).map((entry) => entry.room ?? entry).find((room) => room?.key === key && room.state === 'active');
-  if (found) return String(found.roomId);
-  if (!values.principal) throw new Error(`no active Room with key ${key}, and no --principal to open it for`);
-  // the Room's shape and the seats' role are the organization's (its floor names them), never this door's
-  const missing = ['preset', 'role'].filter((name) => !values[name]);
-  if (missing.length) throw new Error(`no active Room with key ${key}; opening one needs ${missing.map((name) => `--${name}`).join(' and ')} from the organization's floor (the preset the Room is made from and the role its principal and agent hold)`);
-  const seated = [...new Set([values.principal, adapter.principalId()])];
-  const { room } = await post('/rooms', {
-    key,
-    presetId: values.preset,
-    name: values['room-name'] ?? `${values.agent}`,
-    members: seated.map((principalId) => ({ principalId, roleKeys: [values.role] })),
-  });
-  const view = await adapter.get(`/rooms/${encodeURIComponent(room.roomId)}`);
-  const conversation = view.room?.defaultConversationId;
-  if (!conversation) throw new Error(`Room ${room.roomId} was opened without a conversation`);
-  await post(`/rooms/${encodeURIComponent(room.roomId)}/conversations/${encodeURIComponent(conversation)}/participants`, { answers: 'all', principalId: adapter.principalId() });
-  log('info', `opened the account Room ${room.roomId} (${key}) for ${values.agent}`);
-  return String(room.roomId);
-}
-
-const roomId = await accountRoom();
-// The agent answers every line of its Room's conversation (the Room shows it as the conversation's agent); a seat it
-// already holds answers 409.
-{
-  const view = await adapter.get(`/rooms/${encodeURIComponent(roomId)}`);
-  const conversation = view.room?.defaultConversationId;
-  if (conversation) {
-    const res = await adapter.post(`/rooms/${encodeURIComponent(roomId)}/conversations/${encodeURIComponent(conversation)}/participants`, { answers: 'all', principalId: adapter.principalId() });
-    if (!res.ok && res.status !== 409) log('warn', `could not answer every line of ${conversation}: HTTP ${res.status}`);
-  }
-}
-// The adapter follows only this Room.
-adapter.channel = { enabled: true, extra: { ...identity, rooms: [roomId] } };
+const statePath = (name) => values.state ?? join(homedir(), '.config', 'supercode', 'agent-channels', `${values.agent}.${name}.json`);
+let adapter;
+if (values.platform === 'jira') {
+  if (!values.site || !values.jql) { console.error('agent-channel: --platform jira needs --site and --jql'); process.exit(2); }
+  const authorization = process.env.JIRA_EMAIL && process.env.JIRA_API_TOKEN
+    ? `Basic ${Buffer.from(`${process.env.JIRA_EMAIL}:${process.env.JIRA_API_TOKEN}`).toString('base64')}`
+    : process.env.JIRA_TOKEN ? `Bearer ${process.env.JIRA_TOKEN}` : null;
+  if (!authorization) { console.error('agent-channel: --platform jira needs JIRA_EMAIL and JIRA_API_TOKEN (or JIRA_TOKEN) in its environment'); process.exit(2); }
+  adapter = new JiraCommentsAdapter({ site: values.site, jql: values.jql, authorization, statePath: `${statePath('jira')}.comments`, log });
+} else if (values.platform === 'slack') {
+  const channels = new Set(String(values['slack-channel'] ?? '').split(',').map((c) => c.trim()).filter(Boolean));
+  if (!channels.size) { console.error('agent-channel: --platform slack needs --slack-channel <id>: an agent is carried only the channels named'); process.exit(2); }
+  if (!process.env.SLACK_BOT_TOKEN || !process.env.SLACK_APP_TOKEN) { console.error('agent-channel: --platform slack needs SLACK_BOT_TOKEN and SLACK_APP_TOKEN in its environment'); process.exit(2); }
+  // The Slack SDK adapter is built here, in Socket Mode, from this process's own environment: the wrapper's own path
+  // reads a profile's .env, and a channel process has no profile folder. SLACK_API_URL (a twin's) is honoured.
+  let createSlackAdapter;
+  try { ({ createSlackAdapter } = await import('@chat-adapter/slack')); } catch (error) { console.error(`agent-channel: @chat-adapter/slack is not installed (${error.message})`); process.exit(2); }
+  const sdkAdapter = createSlackAdapter({ botToken: process.env.SLACK_BOT_TOKEN, appToken: process.env.SLACK_APP_TOKEN, mode: 'socket', ...(process.env.SLACK_API_URL ? { apiUrl: process.env.SLACK_API_URL } : {}) });
+  const slack = new ChatSdkAdapter({ platform: 'slack', profile: values.agent, channel: { enabled: true, extra: {} }, sdkAdapter, log });
+  // Only the named channels' lines reach the mailbox; answers go back through the same adapter.
+  adapter = { platform: 'slack', connect: (emit) => slack.connect((event) => { if (channels.has(String(event.key?.chat_id))) emit(event); }), send: (target, content) => slack.send(target, content), close: () => slack.close?.() };
+} else { console.error(`agent-channel: --platform is slack or jira (got ${values.platform})`); process.exit(2); }
 const client = new SupercodeHarnessClient(process.env.SUPERCODE_BIN ? { command: process.env.SUPERCODE_BIN } : {});
-const bridge = new AgentMailboxBridge({
-  adapter, client, agent: values.agent, fromName: `rh2-${values.agent}`, log,
-  statePath: values.state ?? join(homedir(), '.config', 'supercode', 'agent-channels', `${values.agent}.json`),
-});
+const bridge = new AgentMailboxBridge({ adapter, client, agent: values.agent, platform: values.platform, fromName: `${values.platform}-${values.agent}`, log, statePath: statePath(values.platform) });
 await bridge.start();
-log('info', `${values.agent}: the account Room ${roomId} is carried to its mailbox`);
-
-const supercode = process.env.SUPERCODE_BIN || 'supercode';
-const sc = (args) => JSON.parse(execFileSync(supercode, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }));
-let boundTo = null, failedAs = null;
-const lastLine = (error) => String(error.stderr || error.message).trim().split('\n').at(-1);
-const warnOnce = (as, line) => { if (failedAs !== as) { failedAs = as; log('warn', line); } };
-/** The agent's own seat takes its session at RH2's own-seat door (PUT …/members/:principalId/session, a Room
- * reader's): the session alone changes, never the seat's roles or who may read and post to it, which stay a
- * members.manage holder's. A refusal throws with its status. */
-async function seatSession(session) {
-  const path = `/rooms/${encodeURIComponent(roomId)}/members/${encodeURIComponent(adapter.principalId())}/session`;
-  const res = await adapter.fetch(`${adapter.apiUrl()}/api/v3${path}`, { method: 'PUT', headers: adapter.headers(), body: JSON.stringify({ session }) });
-  if (!res.ok) throw new Error(`PUT ${path} -> HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
-}
-/** The participant's seat bound to the agent's current main session; a new main session rebinds it. The agent's record
- *  is read again on every tick, so a re-declared main is bound at the next one. A bind that fails is said once per main
- *  and reason (a main that is not in the team's catalog, or one no session ever ran as), never only at debug level,
- *  which this process does not print. */
-async function bindMainSession() {
-  let main;
-  try { main = [sc(['agent', 'show', values.agent, '--json'])].flat().find((a) => a.name === values.agent)?.main_session; }
-  catch (error) { warnOnce(`agent show: ${lastLine(error)}`, `${values.agent}: its agent record was not read (${lastLine(error)}); its seat stays bound to ${boundTo ?? 'nothing'}`); return; }
-  const session = typeof main === 'string' ? main.split(':').pop() : null;
-  if (!session) { warnOnce('no main', `${values.agent}: its agent record names no main session; its seat stays bound to ${boundTo ?? 'nothing'}`); return; }
-  if (session === boundTo) return;
-  let bound;
-  try { bound = sc(['sessions', 'bind', session, '--room', roomId, '--agent', adapter.principalId(), '--rh2', adapter.apiUrl(), '--json']).data; }
-  catch (error) { warnOnce(`${session}: ${lastLine(error)}`, `${values.agent}: its seat is not bound to its main session ${main} (exit ${error.status ?? '?'}: ${lastLine(error)}); retried every 15 s with the record read again`); return; }
-  // The session by its reference (RH2 ADR 0050 decision 4); RH2 takes the registration that provides this agent's sessions.
-  await seatSession({ harness: bound.session.harness, reference: bound.session.reference });
-  failedAs = null;
-  boundTo = session;
-  log('info', `${values.agent}: its seat in the account Room carries its main session ${session}`);
-}
-// A refused seat is said once per reason and retried on the next tick, the first one too: it never ends the channel (a
-// refusal at start would otherwise restart the service in a loop, with the mailbox bridge down each time).
-const rebind = () => bindMainSession().catch((error) => warnOnce(`seat: ${error.message}`, `${values.agent}: its seat was refused its main session (${error.message}); retried every 15 s`));
-await rebind();
-const rebinding = setInterval(() => { void rebind(); }, 15_000);
-const stop = async () => { clearInterval(rebinding); await bridge.stop(); await client.close?.(); process.exit(0); };
+log('info', `${values.agent}: ${values.platform} is carried to its mailbox`);
+const stop = async () => { await bridge.stop(); await adapter.close?.(); await client.close?.(); process.exit(0); };
 process.on('SIGTERM', stop);
 process.on('SIGINT', stop);
-}

package/bin/connection-runner.mjs

@@ -4,11 +4,10 @@ import { existsSync, openSync, closeSync, readFileSync, unlinkSync, renameSync }
 import { dirname, join } from 'node:path';
 import { spawn } from 'node:child_process';
 import { parseArgs } from 'node:util';
-import { activeAgentAssignments, localAgentConversation } from '../agents.mjs';
 import { SERVICE_APPS, SERVICE_PROGRAM, connectionCall, connectionCanRun, connectionPath, generateModuleConfig, privateJson } from '../connection.mjs';
 
 const {values}=parseArgs({options:{root:{type:'string'},connection:{type:'string'}}});
-const path=connectionPath(values.root,values.connection),folder=dirname(path),lock=join(folder,'runner.lock');
+const path=connectionPath(values.root,values.connection),lock=join(dirname(path),'runner.lock');
 let record=JSON.parse(readFileSync(path,'utf8'));
 record.root=values.root;
 if(!connectionCanRun(record))process.exit(0);
@@ -40,7 +39,7 @@ function start(grant){
     while((at=buffer.indexOf('\n'))>=0){const line=buffer.slice(0,at);buffer=buffer.slice(at+1);let event;try{event=JSON.parse(line);}catch{continue;}
       if(['read-error','read-failed','tick-failed','event-stream-failed','resync_required','access_revoked'].includes(event.event))issue(grant.name,event.code??event.reason??event.event);
       if(['source-current','snapshot-read','snapshot-empty','published'].includes(event.event)&&event.current!==false)recover(grant.name);
-      if(['arc-pending','card-pending'].includes(event.event))issue(`obligation.${grant.name}.${event.card}`,`${event.status?'HTTP '+event.status+' ':''}${event.code??event.event}${event.message?' — '+event.message:''}`.slice(0,300));
+      if(event.event==='card-pending')issue(`obligation.${grant.name}.${event.card}`,`${event.status?'HTTP '+event.status+' ':''}${event.code??event.event}${event.message?' — '+event.message:''}`.slice(0,300));
       if(event.event==='projection-current')recover(`obligation.${grant.name}.${event.card}`);
     }
     if(buffer.length>65536)buffer='';
@@ -69,18 +68,6 @@ async function syncAlerts(){
     }catch(error){log('connection-alert-pending',{module:grant.name,code:error.code??error.status??'unavailable'});}
   }
 }
-function standing(){
-  const assignments=activeAgentAssignments(values.root);
-  const rows=(record.standingSelection??[]).map(selection=>{
-    const own=assignments.filter(row=>row.org===record.teams.team&&row.kind==='profile'&&row.target===selection.profile);
-    if(own.length!==1){issue(`standing.${selection.profile}`,own.length?'profile has multiple active agent owners':'profile has no declared conversation owner');return {...selection,reason:'conversation-owner-unknown'};}
-    const conversation=localAgentConversation(values.root,record.teams.team,own[0].agent_id);
-    if(!conversation){issue(`standing.${selection.profile}`,'the home has no conversation-session receipt for this profile');return {...selection,agent:own[0].agent_id,reason:'conversation-session-unknown'};}
-    recover(`standing.${selection.profile}`);return {...selection,agent:own[0].agent_id,session:conversation.session,startedAt:conversation.started_at,running:conversation.ended_at==null};
-  });
-  const target=join(folder,'standing.json');
-  if(!existsSync(target)||readFileSync(target,'utf8').trim()!==JSON.stringify(rows,null,2))privateJson(target,rows);
-}
 async function renewTeams(value){
   if(!value.pendingRenewal&&value.credential.expires_at-Date.now()>7*86400000)return false;
   if(value.pendingRenewal&&value.renewalRetryAt>Date.now())return false;
@@ -115,7 +102,7 @@ async function renew(){
 }
 for(const signal of ['SIGTERM','SIGINT'])process.on(signal,()=>void stop());
 for(const grant of record.grants)start(grant);
-let lastRenew=0,lastStanding=0;
+let lastRenew=0;
 // Teams verifies the Workplace's tokens against its own JWKS (ADR 0070): nothing is relayed for them here.
 while(!stopped){
   try{
@@ -124,7 +111,6 @@ while(!stopped){
     if(!installed.length){await stop();break;}
     const pendingRenewalDue=[record.issuerCredential,...installed.map(grant=>grant.teams)].some(value=>value?.pendingRenewal&&!(value.renewalRetryAt>Date.now()));
     if(pendingRenewalDue||Date.now()-lastRenew>3600000){await renew();lastRenew=Date.now();}
-    if(Date.now()-lastStanding>15000){standing();lastStanding=Date.now();}
     recover('issuer');await syncAlerts();
   }catch(error){issue('issuer',error.code??error.status??'connection-unavailable');await syncAlerts();}
   await new Promise(done=>setTimeout(done,2000));

package/bin/orchestrator.mjs

@@ -2,24 +2,29 @@
 // A reader such as `head` may close its pipe before the final flush. Finish the command and its document work;
 // a closed output pipe is not an unhandled runtime error. Other stream failures retain their original error.
 for (const stream of [process.stdout, process.stderr]) stream.on('error', error => { if (error.code !== 'EPIPE') throw error; });
+if (process.argv[2] === 'workflow' && ['serve', 'daemon'].includes(process.argv[3])
+    && !(typeof process.send === 'function' && Number(process.env.SUPERCODE_BOARD_GENERATION_OWNER) === process.ppid)) {
+  const { sourceServiceEntry } = await import('@volter/supercode-teams/source-service-entry');
+  await sourceServiceEntry(import.meta.url, 'sdk/orchestrator/bin/orchestrator.mjs');
+}
 // before anything loads node:sqlite: Node's notice that it is experimental is not this command's to print
 try { await import('@volter/supercode-harness-sdk/runtime-warnings'); } catch { /* a harness SDK without it: the notice is printed */ }
 // Check before handing off or importing board/runtime dependencies.
-let lockedNative;
-try { ({ lockedNative } = await import('../source-lock.mjs')); }
+let lockedProgram;
+try { ({ lockedProgram } = await import('../source-lock.mjs')); }
 catch (error) { process.stderr.write(`${error.message}\n`); process.exit(1); }
 // Any command on a home whose record names another orchestrator is that orchestrator's (hand-off.mjs).
-{
+if (process.argv[2] !== 'workflow' && !(typeof process.send === 'function' && Number(process.env.SUPERCODE_BOARD_GENERATION_OWNER) === process.ppid)) {
   const { handOff, homeOfArgs } = await import('../hand-off.mjs');
   let handed;
   try { handed = handOff(homeOfArgs(process.argv.slice(2)), process.argv.slice(2)); }
   catch (error) { process.stderr.write(`supercode ${process.argv[2] ?? ''}: ${error.message}\n`); process.exit(1); }
   if (handed !== null) process.exit(await handed);
 }
-// Hand-off may have selected the home's SUPERCODE_BIN. Verify it too, then use the proved native for every child.
+// Hand-off may select the home's SUPERCODE_BIN. Verify its exact Node source entry before any child.
 try {
-  const pinnedNative = lockedNative();
-  if (pinnedNative) process.env.SUPERCODE_BIN = pinnedNative;
+  const pinnedProgram = lockedProgram();
+  if (pinnedProgram) process.env.SUPERCODE_BIN = pinnedProgram;
 } catch (error) { process.stderr.write(`${error.message}\n`); process.exit(1); }
 // Board commands do not load daemon transports, platform adapters or the MCP server.
 if (process.argv[2] === 'workflow') {
@@ -40,7 +45,7 @@ if (process.argv[2] === 'workflow') {
   const {parseArgs}=await import('node:util');
   const {connectWorkplace}=await import('../connection.mjs');
   const {SERVICE_REGISTRATIONS}=await import('../connection.mjs');
-  const options=Object.fromEntries(['root','ticket-file','modules-root','source','context','teams-token-file','teams-url','team','floor','standing-file','alert-role','webhook-url','webhook-listen'].map(key=>[key,{type:'string'}]));
+  const options=Object.fromEntries(['root','ticket-file','modules-root','source','context','teams-token-file','teams-url','team','alert-role','webhook-url','webhook-listen'].map(key=>[key,{type:'string'}]));
   options['no-start']={type:'boolean'};options.registrations={type:'boolean'};
   try{
     const {values}=parseArgs({args:process.argv.slice(3),options});

package/bin/runtime.mjs

@@ -7,7 +7,7 @@
 // `supercode orchestrator start` spawns the daemon form; the daemon itself
 // writes the lease (`<home>/orchestrator.lock`) naming this process and
 // removes it on the way out, so a service-managed daemon reports the same
-// lease a foreground one does. `supercode orchestrator stop` sends SIGTERM.
+// lease a foreground one does. Public stop uses the incarnation-bound control door.
 // A lock left behind by a process that is gone is the mark of a daemon that
 // died: this one dispatches `restart` (§4.7) before it accepts anything.
 //
@@ -53,12 +53,14 @@
 // Everything it prints is one JSON object per line on stdout.
 
 import { SenderIdentityRecord } from '@volter/teams/sender-identity';
-import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, unlinkSync, realpathSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
-import { spawn, spawnSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
+import { spawnSupercodeSync } from '@volter/supercode-harness-sdk/supercode-program';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { LOCK_FILE, leaseIsLive, readLease, thisHost } from '../lease.mjs';
+import { newDaemonIncarnation, clearDaemonLease, startDaemonControl } from '../daemon-control.mjs';
 import { socketPathFor } from '../mcp/server.mjs';
 import { GATEWAY_KIND, holdGatewayLock } from '../hermes-locks.mjs';
 import { adoptHome } from '../hermes-home.mjs';
@@ -70,7 +72,7 @@ import {
   TICK_MS, accessPolicy, applyOperator, performRemoveProfileDir, OPERATOR_OPS,
 } from '../index.mjs';
 import * as events from '../events.mjs';
-import { appView, installAgent, installApp, installedAgentRecord, installedApps, removeApp, rh2AgentEnv, rh2Program, startInstalledModules } from '../installed-apps.mjs';
+import { appView, installAgent, installApp, installedAgentRecord, installedAgentRecords, installedApps, removeApp, rh2AgentEnv, rh2Program, startInstalledModules } from '../installed-apps.mjs';
 import { httpJobExecutor } from '../hosted.mjs';
 import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
 
@@ -363,9 +365,9 @@ function buildAdapters(state, vault = new Map(), log = () => {}, root = null) {
   // installed for. Uninstalling on the other side revokes the token and the channel stops.
   for (const app of root ? installedApps(root) : []) {
     if (app.app !== 'room-chat') continue;
-    // An installation for a mail agent (its name as the profile) is carried to the agent's mailbox by its own channel
-    // (`agent-channel`, docs/adr/0008-agent-mailbox.md): its Room's lines are the agent's mail, never a worker's turns.
-    if (mailAgentNamed(app.profile)) { report.push({ platform: 'rh2', profile: app.profile, app: app.name, state: 'carried by the agent\'s channel' }); continue; }
+    // A mail agent (its name as the profile) is in a Room as its own principal, brought in by the Workplace's join command,
+    // which delivers the Room's lines to its session (runhuman-2 ADR 0063): never a worker's turns here.
+    if (mailAgentNamed(app.profile)) { report.push({ platform: 'rh2', profile: app.profile, app: app.name, state: 'unsupported (a mail agent is in its Rooms as its own principal)' }); continue; }
     if (!state.profiles[app.profile]) { report.push({ platform: 'rh2', profile: app.profile, app: app.name, state: 'unsupported (its profile does not exist)' }); continue; }
     if (adapters.rh2) { report.push({ platform: 'rh2', profile: app.profile, app: app.name, state: 'already owned by another profile' }); continue; }
     adapters.rh2 = new Rh2Adapter({ platform: 'rh2', profile: app.profile, log, vault, channel: { enabled: true, extra: { api_url: app.origin, organization: app.organizationId, principal_id: app.principalId, token: app.token } } });
@@ -376,7 +378,7 @@ function buildAdapters(state, vault = new Map(), log = () => {}, root = null) {
 
 /** Whether `name` is a declared mail agent on this machine (`supercode agent show`). */
 function mailAgentNamed(name) {
-  const shown = spawnSync(process.env.SUPERCODE_BIN || 'supercode', ['agent', 'show', name, '--json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  const shown = spawnSupercodeSync(process.env.SUPERCODE_BIN || 'supercode', ['agent', 'show', name, '--json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
   try { return shown.status === 0 && [JSON.parse(shown.stdout)].flat().some((agent) => agent?.name === name); } catch { return false; }
 }
 
@@ -405,11 +407,7 @@ function writeLock(root, lease) {
 }
 
 /** Only ever removes the record this process wrote. */
-function clearLock(root) {
-  const held = readLock(root);
-  if (held && held.pid !== process.pid) return;
-  try { unlinkSync(join(root, LOCK_FILE)); } catch { /* already gone */ }
-}
+const clearLock = clearDaemonLease;
 
 // ---------------------------------------------------------------- access verbs
 
@@ -480,7 +478,10 @@ async function appsMain(argv) {
       process.stderr.write('apps mcp rh2-agent --agent <its Teams id> [--root R]\n');
       process.exit(2);
     }
-    const record = installedAgentRecord(resolve(opts.root ?? defaultRoot()), opts.agent);
+    const home = resolve(opts.root ?? defaultRoot());
+    // its first Workplace: the one record, else the one installed by hand, else the first by origin; the rest are read
+    // per call from the home (RH2_AGENT_HOMES), so a call on another Workplace is made on the agent's record there
+    const record = installedAgentRecord(home, opts.agent) ?? installedAgentRecords(home, opts.agent)[0] ?? null;
     if (!record) {
       process.stderr.write(`no single rh2-agent record is installed for ${opts.agent}: install it with apps install rh2-agent --agent ${opts.agent}\n`);
       process.exit(1);
@@ -490,7 +491,7 @@ async function appsMain(argv) {
       process.stderr.write(`apps mcp: rh2 is not on PATH (searched ${process.env.PATH || 'an empty PATH'})\n`);
       process.exit(127);
     }
-    const child = spawn(program, ['mcp'], { stdio: 'inherit', env: { ...process.env, ...rh2AgentEnv(record) } });
+    const child = spawn(program, ['mcp'], { stdio: 'inherit', env: { ...process.env, ...rh2AgentEnv(record, home) } });
     for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(signal, () => child.kill(signal));
     child.on('error', (error) => { process.stderr.write(`apps mcp: ${error.message}\n`); process.exit(127); });
     child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
@@ -710,7 +711,8 @@ async function main() {
     child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
     return;
   }
-  const root = resolve(args.root ?? defaultRoot());
+  let root = resolve(args.root ?? defaultRoot());
+  let daemonLease = null;
   let crashed = false;
   let gatewayLock = null;
   if (!args.once) {
@@ -729,17 +731,19 @@ async function main() {
     }
     // Who serves the home now (`orchestrator.lock`), for `supercode orchestrator status` and the operator verbs' live
     // door. A record left behind is a predecessor that never stopped cleanly: this start replays for it (§4.7).
+    root = realpathSync(root);
     const previous = readLock(root);
     crashed = Boolean(previous && previous.pid !== process.pid);
     if (previous) unlinkSync(join(root, LOCK_FILE));
-    writeLock(root, { pid: process.pid, started_at: new Date().toISOString(), root, ...thisHost(), executor_url: args.executorUrl ?? null });
+    daemonLease = Object.freeze({ pid: process.pid, started_at: new Date().toISOString(), root, ...thisHost(), incarnation: newDaemonIncarnation(), launch_request: process.env.SUPERCODE_ORCHESTRATOR_START_REQUEST ?? null, executor_url: args.executorUrl ?? null });
+    writeLock(root, daemonLease);
     try {
       // the home in both forms before it is loaded: a Hermes home is adopted as it stands
       for (const change of adoptHome(root)) say('log', { level: 'info', message: `home: ${change}` });
     } catch (error) {
       say('error', { root, message: error.message });
-      gatewayLock?.release();
-      clearLock(root);
+      clearLock(root, daemonLease);
+      await gatewayLock?.release();
       process.exit(1);
     }
   }
@@ -763,9 +767,9 @@ async function main() {
         profileLocks.push(await holdGatewayLock(profile.dir));
       } catch (error) {
         say('error', { root, message: error.message });
-        for (const lock of profileLocks) lock.release();
-        gatewayLock.release();
-        clearLock(root);
+        clearLock(root, daemonLease);
+        for (const lock of profileLocks) await lock.release();
+        await gatewayLock.release();
         process.exit(1);
       }
     }
@@ -802,12 +806,53 @@ async function main() {
   }
 
 
-  await orchestrator.start();
-  // A daemon that came BACK replays pending obligations, re-attaches or
-  // interrupts the bindings that held a lease, and clears the stale ones
-  // before it accepts anything new (§4.7). A clean stop removes its own lock,
-  // so an ordinary start finds none and replays nothing.
-  if (crashed) await orchestrator.dispatch(events.restart(new Date().toISOString()));
+  let keepalive = null, control = null, stopped = null, finishing = null, starting = null;
+  const stop = (reason) => stopped ??= (async () => {
+    await starting?.catch(() => {});
+    clearInterval(keepalive);
+    say('stopping', { root, pid: process.pid, reason, incarnation: daemonLease.incarnation });
+    const errors = [];
+    const joinOwned = async (name, work) => {
+      try { await work(); }
+      catch (error) { errors.push(`${name}: ${String(error.message ?? error)}`); }
+    };
+    // Join each owner even if another failed. Never erase a replacement lease.
+    await joinOwned('orchestrator', () => orchestrator.stop());
+    await joinOwned('client', () => client.close?.());
+    await joinOwned('World', () => closeWorld());
+    for (const lock of profileLocks) await joinOwned('profile lock', () => lock.release());
+    if (!errors.length) await joinOwned('lease', () => clearLock(root, daemonLease));
+    await joinOwned('gateway lock', () => gatewayLock?.release());
+    const receipt = { version: 1, daemon: daemonLease, status: errors.length ? 'failed' : 'stopped', errors };
+    say(receipt.status, receipt);
+    return receipt;
+  })();
+  const finish = () => finishing ??= (async () => {
+    const receipt = await stop('signal');
+    try { await control?.close(); }
+    catch (error) { say('error', { root, message: `control close: ${error.message}` }); process.exitCode = 1; }
+    await exitAfterFlush(receipt.status === 'stopped' && !process.exitCode ? 0 : 1);
+  })();
+  process.on('SIGTERM', () => { void stop('SIGTERM'); void finish(); });
+  process.on('SIGINT', () => { void stop('SIGINT'); void finish(); });
+  try {
+    starting = (async () => {
+      await orchestrator.start();
+      // A daemon that came BACK replays pending obligations, re-attaches or
+      // interrupts the bindings that held a lease, and clears the stale ones
+      // before it accepts anything new (§4.7). A clean stop removes its own lock,
+      // so an ordinary start finds none and replays nothing.
+      if (!stopped && crashed) await orchestrator.dispatch(events.restart(new Date().toISOString()));
+      if (!stopped) control = await startDaemonControl({ root, lease: daemonLease, stop, complete: () => { void finish(); } });
+    })();
+    await starting;
+    if (stopped) { await finish(); return; }
+  } catch (error) {
+    say('error', { root, message: String(error.message ?? error) });
+    process.exitCode = 1;
+    await finish();
+    return;
+  }
   say('ready', {
     root,
     pid: process.pid,
@@ -822,29 +867,7 @@ async function main() {
   // The loop's own tick timer is `unref`'d, and the webhook listener may bind
   // nothing a profile uses; this timer is what keeps the daemon alive on
   // purpose, so "up" always means a process that will still be here next tick.
-  const keepalive = setInterval(() => {}, TICK_MS);
-
-  let stopping = false;
-  const stop = async (signal) => {
-    if (stopping) return;
-    stopping = true;
-    clearInterval(keepalive);
-    say('stopping', { root, pid: process.pid, signal });
-    try {
-      await orchestrator.stop();
-      await client.close?.();
-      await closeWorld();
-    } catch (error) {
-      say('log', { level: 'error', message: `stop: ${String(error.message ?? error)}` });
-    }
-    for (const lock of profileLocks) lock.release();
-    gatewayLock?.release();
-    clearLock(root);
-    say('stopped', { root, pid: process.pid });
-    process.exit(0);
-  };
-  process.on('SIGTERM', () => void stop('SIGTERM'));
-  process.on('SIGINT', () => void stop('SIGINT'));
+  keepalive = setInterval(() => {}, TICK_MS);
 }
 
 await main();

package/board/call.mjs

@@ -16,6 +16,7 @@
 import { readFileSync } from 'node:fs';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { withCredentialGuard } from './credential-guard.mjs';
+import { generationWork } from './generation.mjs';
 
 const calls = new AsyncLocalStorage();
 // what a call learns as it runs, and the workflow it read (pinned: a reload while it runs does not change its basis)
@@ -35,7 +36,7 @@ export function within({ caller = null, facts = {}, cwd, stdin = null, out, err,
 /** Run `fn` as a unit of the process's own work (a round, a delivery pass): the process's identity and output, with
  *  what it learns and the workflow it read kept to itself. */
 export function ownCall(fn) {
-  return withCredentialGuard(() => calls.run({ kind: 'own', caller: null, facts: process.env, ...fresh(), get cwd() { return process.cwd(); }, stdin: null, out: own.out, err: own.err }, fn));
+  return generationWork(() => withCredentialGuard(() => calls.run({ kind: 'own', caller: null, facts: process.env, ...fresh(), get cwd() { return process.cwd(); }, stdin: null, out: own.out, err: own.err }, fn)));
 }
 
 /** The caller as its address names it, or null. */