@volter/supercode-orchestrator 0.4.160 → 0.5.2

package/installed-apps.mjs

@@ -0,0 +1,52 @@
+// Installed integration apps of an orchestrator home (mirrored ontology M4, ADR 0017). An app reaches a profile only by
+// an installation the other side consented to: its admin installs the app there, and the one-time code that consent
+// returns is exchanged here, with the app's client secret, for the installation's token. The record lives in the home's
+// `apps/` folder (owner-only); no `platforms:` block attaches an integration. Uninstalling on the other side revokes the
+// token, and the channel stops; `remove` forgets the record here.
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { 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({
+  'room-chat': { side: 'rh2', adapter: 'rh2', describe: 'Room chat → orchestrator: a person\'s line in an RH2 Room reaches the agent seated there' },
+});
+
+const recordPath = (root, name) => join(root, APPS_DIR, `${name}.json`);
+
+export function installedApps(root) {
+  const dir = join(root, APPS_DIR);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((file) => file.endsWith('.json')).map((file) => {
+    const record = JSON.parse(readFileSync(join(dir, file), 'utf8'));
+    return { ...record, name: file.slice(0, -5) };
+  }).filter((record) => INSTALLABLE_APPS[record.name]);
+}
+
+/** 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) throw new Error(`no installable app named ${name} (${Object.keys(INSTALLABLE_APPS).join(', ')})`);
+  if (!/^https:\/\/|^http:\/\/(localhost|127\.0\.0\.1)(:|\/|$)/.test(String(origin))) throw new Error('the RH2 origin is an https URL');
+  const base = new URL(origin).origin;
+  const response = await fetchImpl(`${base}/api/v3/automation/apps/oauth/access`, { method: 'POST', redirect: 'manual', headers: { 'content-type': 'application/json', accept: 'application/json' }, body: JSON.stringify({ clientId, clientSecret, code }) });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) throw Object.assign(new Error(payload?.error?.message ?? `the install code exchange answered ${response.status}`), { code: payload?.error?.code });
+  const { accessToken, expiresAt, installationId, organizationId, principalId } = payload.data;
+  const record = { app: name, side: app.side, origin: base, organizationId, principalId, installationId, expiresAt, profile, token: accessToken, installedAt: new Date().toISOString() };
+  mkdirSync(join(root, APPS_DIR), { recursive: true, mode: 0o700 });
+  const pending = `${recordPath(root, name)}.${process.pid}.tmp`;
+  writeFileSync(pending, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+  renameSync(pending, recordPath(root, name));
+  return { ...record, token: undefined };
+}
+
+export function removeApp(root, name) {
+  const path = recordPath(root, name);
+  if (!existsSync(path)) return false;
+  rmSync(path);
+  return true;
+}
+
+/** 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 });

package/ir.mjs

@@ -135,7 +135,7 @@ export function homeChannel(profile, platform = null) {
   return null;
 }
 
-export const END_REASONS = new Set(['idle', 'daily', 'reset', 'new', 'handoff', 'error']);
+export const END_REASONS = new Set(['idle', 'daily', 'reset', 'new', 'handoff', 'transfer', 'left', 'error']);
 
 export const FIRE_STATUSES = new Set(['claimed', 'running', 'succeeded', 'failed', 'timeout', 'unknown']);
 
@@ -156,7 +156,7 @@ export function resolveRoute(routes, key, guildId) {
     if (m.thread_id && m.thread_id !== key.thread_id) continue;
     if (!best || routeSpecificity(r) > routeSpecificity(best)) best = r;
   }
-  return best ? best.profile : null;
+  return best ? best.agent : null;
 }
 
 // ---------------------------------------------------------------- profiles / state
@@ -183,7 +183,7 @@ export function emptyRuntime() {
 }
 
 export function emptyState(root) {
-  return { root, profiles: { default: emptyProfile('default', root) }, runtime: emptyRuntime() };
+  return { root, profiles: { default: emptyProfile('default', root) }, agents: {}, conversations: {}, transfers: [], handoffs: [], usage: {}, runtime: emptyRuntime() };
 }
 
 /** Stable, secret-free JSON of the persisted half of the state (runtime omitted). */

package/kanban-worker.mjs

@@ -14,13 +14,14 @@ import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
 import { load } from './orchestration.mjs';
 import { INSTRUCTION_ARGUMENTS, activationCwd, activationEnv, sandboxArguments, approvalPolicy, limitArguments, materializePersona, materializeSkills, modelArguments, turnCounter, userHomeArguments, userHomePersona } from './activation.mjs';
 import { workerRoute } from './worker-route.mjs';
-import { KANBAN_ENV, untrustedServerVerdict, hermesInstall } from './hermes-cli.mjs';
+import { KANBAN_ENV, untrustedServerVerdict, hermesInstall, memorySnapshot } from './hermes-cli.mjs';
 import { pinnedSkills, taskProtocol } from './board/worker-prompt.mjs';
 import { mountOrchestratorMcp } from './mcp/mount.mjs';
 import { normalizeWorkerEvent } from './loop.mjs';
 import { DEFAULT_BOARD, json, openBoard, tx } from './board/store.mjs';
 import { setRunSession } from './board/engine.mjs';
 import { permissionResponse } from './reducer.mjs';
+import { boardGuardArguments } from '../teams/board-process-guard.mjs';
 
 /** Hermes's worker argv, as `_default_spawn` builds it. */
 export function parseHermesArgv(argv) {
@@ -50,11 +51,12 @@ export async function runKanbanWorker(argv, env = process.env) {
   const args = parseHermesArgv(argv);
   if (!env.HERMES_HOME || !args.query) { say('hermes-worker: HERMES_HOME and -q are required (the dispatcher sets both)'); return 2; }
   const home = resolve(env.HERMES_HOME);
-  const root = rootOf(home);
+  const root = env.SUPERCODE_AGENT_HOME ? resolve(env.SUPERCODE_AGENT_HOME) : rootOf(home);
   const { state, vault } = await load(root);
   const profile = Object.values(state.profiles).find((p) => resolve(p.dir) === home) ?? state.profiles[args.profile ?? 'default'];
   if (!profile?.worker?.harness) { say(`hermes-worker: no worker for profile ${args.profile ?? home}`); return 2; }
-  if (profile.worker.harness === 'hermes') return runHermes(argv, env);
+  // The agent's home is already the effective profile. Hermes must not switch back to the shared template.
+  if (profile.worker.harness === 'hermes') return runHermes(env.SUPERCODE_AGENT_ID?withoutProfile(argv):argv, env);
   const harness = profile.worker.harness;
   const task = Object.fromEntries(KANBAN_ENV.filter((k) => env[k]).map((k) => [k, env[k]]));
   const taskId = task.HERMES_KANBAN_TASK ?? 'none';
@@ -67,10 +69,12 @@ export async function runKanbanWorker(argv, env = process.env) {
   materializeSkills(profile);
   const route = workerRoute(profile, worker, vault);
   const surfaceKey = `kanban|task|${taskId}`;
-  const runEnv = { HERMES_HOME: profile.dir, ...activationEnv({ root, profile, surfaceKey, vault }), ...route.env, ...task };
+  const identityEnv=Object.fromEntries(Object.entries(env).filter(([key])=>key.startsWith('SUPERCODE_AGENT_')));
+  const runEnv = { ...activationEnv({ root, profile, surfaceKey, vault }), ...route.env, ...task, ...identityEnv,HERMES_HOME: home };
+  const memory=env.SUPERCODE_AGENT_ID?await memorySnapshot(home):'';
   // the persona, the task protocol and the pinned skills, supercode's own (board/worker-prompt.mjs)
   // the board workflow's own words for this run (its status's prompt and doors), after the task protocol
-  const instructions = [userHomePersona(profile), taskProtocol(taskId), env.SUPERCODE_BOARD_PROMPT ?? '', pinnedSkills(profile.dir, args.skills)].filter(Boolean).join('\n\n');
+  const instructions = [userHomePersona(profile), taskProtocol(taskId), env.SUPERCODE_BOARD_PROMPT ?? '', memory,pinnedSkills(profile.dir, args.skills)].filter(Boolean).join('\n\n');
 
   const client = new SupercodeHarnessClient(env.SUPERCODE_BIN ? { command: env.SUPERCODE_BIN } : {});
   try {
@@ -87,7 +91,7 @@ async function runTurn({ client, profile, harness, worker, route, root, vault, s
   const reasoning = args.reasoning && harness === 'codex' ? ['-c', `model_reasoning_effort=${JSON.stringify(args.reasoning)}`] : [];
   const launch = {
     program: base.program,
-    arguments: [...(base.arguments ?? []), ...modelArguments(worker), ...route.args, ...(instructions && INSTRUCTION_ARGUMENTS[harness] ? INSTRUCTION_ARGUMENTS[harness](instructions) : []), ...userHomeArguments(profile), ...reasoning, ...sandboxArguments(profile, harness), ...limitArguments(profile, worker, (level, line) => say(line))],
+    arguments: boardGuardArguments(harness, [...(base.arguments ?? []), ...modelArguments(worker), ...route.args, ...(instructions && INSTRUCTION_ARGUMENTS[harness] ? INSTRUCTION_ARGUMENTS[harness](instructions) : []), ...userHomeArguments(profile), ...reasoning, ...sandboxArguments(profile, harness), ...limitArguments(profile, worker, (level, line) => say(line))], { enabled: ['claude-code','codex'].includes(harness), cwd }),
     env: { ...(base.env ?? {}), ...runEnv },
   };
   const mount = mountOrchestratorMcp({ root, profile, harness, surfaceKey, launch, vault, task });
@@ -162,3 +166,9 @@ function runHermes(argv, env) {
     child.on('error', () => done(1));
   });
 }
+
+function withoutProfile(argv) {
+  const selected=[];
+  for(let i=0;i<argv.length;i+=1){if(argv[i]==='-p'||argv[i]==='--profile'){i+=1;continue;}selected.push(argv[i]);}
+  return selected;
+}

package/loop.mjs

@@ -12,7 +12,7 @@ import { read, save, retainWorld, releaseWorld } from './orchestration.mjs';
 import { INSTRUCTION_ARGUMENTS, NAME_ARGUMENTS, activationEnv, activationCwd, 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 } from './ir.mjs';
+import { hermesSessionKey, homeChannel } from './ir.mjs';
 import { surfaceKeyString } from './ir.mjs';
 import { BREAKER_FAILURES, BREAKER_MINUTES, MAX_ATTEMPTS, historyRetention, jobGate } from './cron.mjs';
 import { startWebhookListener } from './webhook.mjs';
@@ -23,6 +23,9 @@ import { performRemoveProfileDir } from './operator.mjs';
 import { harnessHomes } from './mcp/verbs.mjs';
 import { checkMonitor, runJobScript } from './gates.mjs';
 import { startBoard } from './board.mjs';
+import { SenderIdentityRecord } from '@volter/teams/sender-identity';
+import { agentDoor,agentScope,teamsUnavailable,ensureProfileAgent,localProfileAgent,localAgentRecord,localAgentSessions,synchronizeLocalAgents,ensureForkAgent,agentRunForKey,agentIntent,agentPreamble,agentEnvironment,recordAgentRun,recordNativeAgentSession,pendingAgentRuns,synchronizeAgentRun,agentRunForSession } from './agents.mjs';
+import { materializeAgentHome } from './agent-home.mjs';
 import { localMachine } from './board/dispatch.mjs';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
@@ -55,6 +58,7 @@ export class Orchestrator {
     this.state = state;
     this.executeJob = executeJob;
     this.hostedTasks = new Set();
+    this.identityRecord = new SenderIdentityRecord();
     state.runtime ??= {};
     state.runtime.hostedJobs = !!executeJob;
     state.runtime.machine = localMachine(); // a job naming another machine fires there (cron.mjs startFire)
@@ -183,11 +187,24 @@ export class Orchestrator {
   tick(at = this.clock()) {
     this.queue = this.queue.then(() => this.adoptOutsideJobs()).catch((error) => this.log('warn', `cron/jobs.json not read back: ${error.message}`));
     return this.dispatch(events.tick(at, cronInactivitySeconds(), cronMaxParallel())).then(
-      (result) => { this.tickerHeartbeat(true); return result; },
+      (result) => { this.tickerHeartbeat(true); this.synchronizeProfileSessions();return result; },
       (error) => { this.tickerHeartbeat(false); throw error; },
     );
   }
 
+  synchronizeProfileSessions(){
+    if(!existsSync(join(this.state.root,'agent-state.sqlite')))return;
+    try{
+      const context=process.env.SUPERCODE_CONTEXT,scope=agentScope(context);
+      if(scope.offline)return;
+      for(const pending of synchronizeLocalAgents({root:this.state.root,profiles:this.state.profiles,context,declarations:this.state.agents??{}}))this.log('warn',`agent ${pending.agent} declaration pending: ${pending.error}`);
+      for(const row of pendingAgentRuns(this.state.root,scope.org)){
+        try{synchronizeAgentRun(this.state.root,scope.org,row,{context,intended:row.profile_json?JSON.parse(row.profile_json):undefined});}
+        catch(error){this.log('warn',`agent session ${row.session_ref}: ${error.message}`);}
+      }
+    }catch(error){this.log('warn',`agent session synchronization: ${error.message}`);}
+  }
+
   /**
    * Hermes's ticker liveness (`cron/jobs.py` `record_ticker_heartbeat`), in each profile's cron store: the
    * epoch of every tick in `ticker_heartbeat`, and of every tick that did not fail in `ticker_last_success`.
@@ -255,6 +272,12 @@ export class Orchestrator {
   }
 
   async apply(event) {
+    if(event.type==='inbound'&&!event.is_me) {
+      // An adapter's display name or supplied principal never proves identity.
+      const observation=`${event.key.platform}:${event.sender}`;
+      try {event={...event,identity:await this.identityRecord.observe({observation,location:JSON.stringify(event.key),at:Date.parse(event.at),name:event.sender_name,evidence:{adapter:event.adapter,message_id:event.message_id}})};}
+      catch(error){event={...event,identity:{observation,principal:null,classification:'unresolved',label:'unresolved'}};this.log('warn',`identity observation unavailable: ${error.message}`);}
+    }
     const effects = step(this.state, event);
     for (const effect of effects) {
       this.effectLog.push(effect);
@@ -292,7 +315,7 @@ export class Orchestrator {
         let got;
         try { got = hermesAccess(this.state.profiles[effect.profile].dir, 'issue', effect); } catch (error) { this.log('warn', `pairing: ${error.message}`); return; }
         if (got?.silent) return;
-        await this.dispatch({ type: 'pairing_issued', profile: effect.profile, key: effect.key, code: got?.code ?? null, at: this.clock() });
+        this.enqueue({ type: 'pairing_issued', profile: effect.profile, key: effect.key, code: got?.code ?? null, at: this.clock() });
         return;
       }
       case 'access_write': {
@@ -300,7 +323,10 @@ export class Orchestrator {
         try {
           const got = hermesAccess(dir, effect.op, effect);
           if (effect.op === 'approve') {
-            if (got) await this.dispatch({ type: 'operator', verb: 'access_granted', profile: effect.profile, args: { platform: got.platform, user_id: got.user_id }, at: this.clock() });
+            if (got) {
+              await this.identityRecord.approvedPairing({...got,code:effect.code,principal_id:effect.principal??null,location:dir}).catch(error=>this.log('warn',`pairing identity not recorded: ${error.message}`));
+              this.enqueue({ type: 'operator', verb: 'access_granted', profile: effect.profile, args: { platform: got.platform, user_id: got.user_id }, at: this.clock() });
+            }
             else this.log('warn', `pairing code ${effect.code}: not pending in Hermes's pairing store (wrong, expired, or locked out)`);
           }
         } catch (error) {
@@ -308,6 +334,8 @@ export class Orchestrator {
         }
         return;
       }
+      case 'usage_refresh': return this.refreshUsage(effect);
+      case 'budget_refused': return this.tellBudgetRefusal(effect);
       case 'save': await this.save(); return;
       case 'log': this.log(effect.level, effect.message); return;
       default: this.log('warn', `unknown effect ${effect.type}`);
@@ -371,7 +399,7 @@ export class Orchestrator {
       }
       // Hermes runs a no_agent script in the job's workdir, and an agent job's
       // pre-run script from the scripts folder
-      const script = gate.script ? await runJobScript(profile, gate.script, gate.no_agent ? workdir : null, { signal, secrets }) : null;
+      const script = gate.script ? await runJobScript(profile, gate.script, gate.no_agent ? workdir : null, { signal, secrets, automation: `cron:${profile.name}/${job.id}` }) : null;
       return { monitor, script };
     })()
       .catch((error) => ({ script: { ok: false, output: `Script execution failed: ${error.message}` } }))
@@ -383,23 +411,70 @@ 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 }) {
+  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 }) {
     const profile = this.state.profiles[profileName];
     const lid = leaseId(profileName, keyString);
     const cwd = activationCwd(profile, worker.cwd);
     materializePersona(profile);
     materializeSkills(profile);
-    let launch;
+    let launch,agent,scope,context,agentPrompt,main,agentHome;
     try {
+      context=process.env.SUPERCODE_CONTEXT;scope=agentScope(context);
+      const local=error=>{if(!teamsUnavailable(error))throw error;this.log('warn',`agent identity for ${profileName} stays local: ${error.message}`);};
+      let previous=null,reader=null;
+      if(agent_as) {
+        // A launch as a named agent is an act Teams authorizes; it never proceeds on local intent alone.
+        agentDoor('management',[agent_as],{context});
+        const identity=agentDoor('get',[agent_as],{context}).data,intent=agentIntent(this.state.root,scope.org,agent_as);
+        if(!intent)throw new Error('launch as an agent requires its retained profile intent');
+        agent={identity,intended:intent.profile,assignments:intent.assignments,org:scope.org};
+      } else if(!scope.offline) {
+        try{agent=ensureProfileAgent({root:this.state.root,org:scope.org,server:scope.server,profiles:this.state.profiles,profile:profileName,context,agent:agentName,declarations:this.state.agents});}catch(error){local(error);}
+      }
+      // Situation 16: no reachable Teams. The locally minted identity runs now and is declared later under its id.
+      agent??=localProfileAgent({root:this.state.root,org:scope.org,server:scope.server,profiles:this.state.profiles,profile:profileName,agent:agentName,declarations:this.state.agents});
+      agent.intended.resolved.worker={...agent.intended.resolved.worker,...worker,cwd};
+      main=new_fork||!agent.identity.main_session;
+      if(agent.synced!==false){
+        try{
+          previous=agentDoor('sessions',[agent.identity.id,{limit:200}],{context}).items??[];
+          if(resume_runtime_id&&!new_fork) {
+            // a session no sync rule publishes is unknown to Teams: its owner is the local run record, read below
+            let resumed=null;
+            try{resumed=agentDoor('session',[`${worker.harness}:${resume_runtime_id}`],{context}).data;}catch(error){if(error.code!=='not_found')throw error;}
+            if(resumed){
+              if(resumed.agent?.id!==agent.identity.id)throw new Error('the resumed session is not owned by this profile agent');
+              main=resumed.main;
+            } else {
+              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');
+              if(owner)main=owner.main===1;
+            }
+          }
+          reader=agentDoor('readerContext',[agent.identity.id,null],{context,timeout:60000});
+        }catch(error){local(error);}
+      }
+      if(resume_runtime_id&&!new_fork&&!previous){
+        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');
+        if(owner)main=owner.main===1;
+      }
+      previous??=localAgentSessions(this.state.root,scope.org,agent.identity.id);
+      agentPrompt=agentPreamble(agent,{main,previous});
+      // a conversation passes between this home's agents by name (conversation_transfer); the model learns the names here
+      const peers=[...new Set([...Object.keys(this.state.profiles??{}),...Object.keys(this.state.agents??{})])].filter((name)=>name!==(agent.identity.name??profile.name)&&name!==profile.name);
+      if(peers.length)agentPrompt+=`\nThe other agents of this home: ${peers.join(', ')}. conversation_transfer hands a conversation to one of them by that name; they are not Claude Code sessions.`;
+      agentHome=materializeAgentHome(this.state.root,scope.org,agent.identity.id,profile);
       // the home's own `model:` is the worker's model and route (docs/plans/hermes-compat.md row 6)
       const route = workerRoute(profile, worker, this.vault);
       // a worker of any harness but Hermes gets Hermes's CLI against its profile's home (row 7)
-      const tools = worker.harness === 'hermes' ? {} : hermesToolEnv(profile.dir);
-      const env = { ...tools, ...activationEnv({ root: this.state.root, profile, surfaceKey: keyString, vault: this.vault }), ...route.env };
-      // the home's memory, as Hermes's agent carries it into a session (row 13)
-      const memory = INSTRUCTION_ARGUMENTS[worker.harness] ? await memorySnapshot(profile.dir).catch((error) => { this.log('warn', `memory ${keyString}: ${error.message}`); return ''; }) : '';
+      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:reader?.context,main}) };
+      env.HERMES_HOME=agentHome;
+      // 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)
-      const instructionText = [userHomePersona(profile), memory].filter(Boolean).join('\n\n');
+      const instructionText = [agentPrompt,userHomePersona(profile), memory].filter(Boolean).join('\n\n');
       const instructions = instructionText && INSTRUCTION_ARGUMENTS[worker.harness] ? INSTRUCTION_ARGUMENTS[worker.harness](instructionText) : [];
       const naming = NAME_ARGUMENTS[worker.harness]?.(basename(this.state.root)) ?? [];
       launch = await this.resolveLaunch(profile, { ...worker, model: route.model }, env, [...route.args, ...instructions, ...naming, ...userHomeArguments(profile)]);
@@ -414,7 +489,7 @@ export class Orchestrator {
       socketPath: this.bridge?.path ?? socketPathFor(this.state.root), vault: this.vault,
     });
     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);
+    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;
@@ -426,9 +501,11 @@ export class Orchestrator {
           runtime = await this.client.resumeManagedRuntime({ ...params, runtime_id: resume_runtime_id });
           this.log('info', `resume ${keyString}: reopened ${resume_runtime_id}`);
         } catch (error) {
+          if(new_fork)throw error;
           this.log('warn', `resume ${keyString}: ${resume_runtime_id} did not reopen (${error.message}); starting fresh`);
         }
       }
+      if(new_fork&&!runtime)throw new Error('this harness cannot resume the materialized fork; no fresh replacement was started');
       runtime ??= await this.client.startManagedRuntime(params);
     } catch (error) {
       this.enqueue(events.worker({ profile: profileName, keyString, runtime_id: null, ev: { kind: 'error', message: `start failed: ${error.message}` }, at: this.clock() }));
@@ -439,12 +516,51 @@ export class Orchestrator {
     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});
+    if(agent.synced!==false)try{synchronizeAgentRun(this.state.root,scope.org,{agent_id:agent.identity.id,session_ref:session,machine:null,main},{context,intended:agent.intended.resolved});}
+    catch(error){this.log('warn',`agent session ${session} retained for synchronization: ${error.message}`);}
     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);
+    return runtime.handle;
+  }
+
+  /** 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');
+    const locator=await this.wholeLocator(given);
+    const profile=this.state.profiles[profileName];if(!profile)throw new Error('fork requires a named profile');
+    const binding=profile.bindings[keyString];
+    if(!binding||binding.ended_at)throw new Error('register the fork target conversation before starting its runtime');
+    if(this.runtimes.has(leaseId(profileName,keyString)))throw new Error('fork requires an unoccupied target conversation');
+    if(!(await this.descriptorFor(locator.harness))?.runtime?.capabilities?.resume_session)throw new Error('this harness cannot resume a materialized fork');
+    const context=process.env.SUPERCODE_CONTEXT,scope=agentDoor('scope',[],{context}),session=`${locator.harness}:${locator.session_id}`;
+    const child=ensureForkAgent({root:this.state.root,org:scope.org,server:scope.server,profiles:this.state.profiles,parent,session,name,key,context});
+    const runKey=`fork:${key}`,prior=agentRunForKey(this.state.root,scope.org,child.identity.id,runKey);
+    let target;
+    if(prior) {
+      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;
+      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});
+      if(loaded.session.session_id!==locator.session_id)throw new Error('fork locator and native session identity differ');
+      const cwd=activationCwd(profile,child.intended.resolved.worker?.cwd),store=WORKER_STORE[locator.harness];
+      if(!store)throw new Error('this harness has no admitted native materialization door');
+      const {artifact}=await this.client.handoffSession({locator,target_harness:locator.harness,cwd});
+      const home=materializeAgentHome(this.state.root,scope.org,child.identity.id,profile);
+      target=(await this.client.materializeSession({artifact,cwd,homes:store(locator.harness==='hermes'?home:join(profile.dir,locator.harness))})).locator;
+      recordAgentRun(this.state.root,scope.org,child.identity.id,{session:`${target.harness}:${target.session_id}`,machine:null,run:runKey,profile:child.intended.resolved,main:true,starterSession:session});
+    }
+    const runtime=await this.startRuntime({profile:profileName,keyString,worker:{...profile.worker,...child.intended.resolved.worker,harness:target.harness},resume_runtime_id:target.session_id,agent_as:child.identity.id,new_fork:true,run_key:runKey,starter_session:session});
+    if(!runtime)throw new Error('the child session did not start; its declared identity and native fork remain retained');
+    return {agent:child.identity,locator:target,runtime};
   }
 
   /**
@@ -461,6 +577,26 @@ export class Orchestrator {
       this.enqueue(events.operator({ verb: 'binding_interrupted', profile: profileName, args: { keyString, runtime_id }, at: this.clock() }));
     };
     if (!runtime_id || !harness) return interrupted('no runtime recorded on the binding');
+    const held = this.state.profiles[profileName]?.bindings?.[keyString];
+    const owner=agentRunForSession(this.state.root,[`${harness}:${held?.worker?.session_id??runtime_id}`,`${harness}:${runtime_id}`]);
+    let preamble=null;
+    if(owner) {
+      try {
+        const context=process.env.SUPERCODE_CONTEXT;
+        const intent=agentIntent(this.state.root,owner.org,owner.agent_id);
+        if(!intent)throw new Error('retained session has no agent profile intent');
+        try{
+          const live=agentDoor('session',[owner.session_ref],{context}).data;
+          if(live.agent?.id!==owner.agent_id||live.agent.state!=='active')throw new Error('retained session agent is no longer active or has different ownership');
+          const previous=agentDoor('sessions',[owner.agent_id,{limit:200}],{context}).items??[];
+          preamble=agentPreamble({identity:live.agent,intended:intent.profile,assignments:intent.assignments},{main:live.main,previous});
+        }catch(error){
+          // Teams cannot be asked: the session continues as the agent this home recorded, never as another.
+          if(!teamsUnavailable(error))throw error;
+          preamble=agentPreamble(localAgentRecord(this.state.root,owner.org,owner.agent_id),{main:owner.main===1,previous:localAgentSessions(this.state.root,owner.org,owner.agent_id)});
+        }
+      }catch(error){return interrupted(`agent identity unavailable: ${error.message}`);}
+    }
     let capable = false;
     try {
       capable = Boolean((await this.descriptorFor(harness))?.runtime?.capabilities?.attach_existing_process);
@@ -475,8 +611,8 @@ export class Orchestrator {
       return interrupted(`attach_existing failed: ${error.message}`);
     }
     this.runtimes.set(leaseId(profileName, keyString), runtime);
+    if(preamble)(this.runtimeAgentPreambles??=new Map()).set(leaseId(profileName,keyString),preamble);
     this.watch(profileName, keyString, runtime);
-    const held = this.state.profiles[profileName]?.bindings?.[keyString];
     this.enqueue(events.worker({
       profile: profileName, keyString, runtime_id: runtime.handle.runtime_id,
       ev: { kind: 'started', runtime_id: runtime.handle.runtime_id, session_id: held?.worker?.session_id || runtime.handle.runtime_id, connection: runtime.connection, harness, reattach_of: runtime_id },
@@ -540,6 +676,14 @@ export class Orchestrator {
 
   onWorkerEvent(profileName, keyString, runtime, ev) {
     const at = this.clock();
+    // Child tool frames cannot transfer the parent runtime's ownership to their own native id.
+    const nativeId=!ev.payload?.parent_tool_use_id&&(ev.payload?.type==='system'&&ev.payload?.subtype==='init'?ev.payload.session_id:ev.sessionId!==runtime.handle.runtime_id?ev.sessionId:null);
+    if(typeof nativeId==='string'&&nativeId) {
+      try {
+        recordNativeAgentSession(this.state.root,`${runtime.handle.harness}:${runtime.handle.runtime_id}`,`${runtime.handle.harness}:${nativeId}`);
+        this.enqueue(events.worker({profile:profileName,keyString,runtime_id:runtime.handle.runtime_id,ev:{kind:'session',session_id:nativeId},at}));
+      }catch(error){this.log('warn',`native session ownership: ${error.message}`);}
+    }
     // every event the runtime reports is the worker being alive, including the
     // tool calls, reasoning and turn starts the reducer does not otherwise read
     let w = normalizeWorkerEvent(ev) ?? { kind: 'activity' };
@@ -584,7 +728,7 @@ export class Orchestrator {
       // `cron_incomplete_no_output` for a run that said nothing)
       const said = (loaded.session.messages ?? []).some((m) => m.role === 'assistant' && (typeof m.content === 'string' ? m.content.trim() : (m.content ?? []).length));
       const end = b.recurrence && final ? (said ? 'cron_complete' : 'cron_incomplete_no_output') : null;
-      const got = await mirrorSession(profile.dir, {
+      const got = await mirrorSession(this.sessionStateHome(profile,w), {
         id: w.session_id, sessionKey: hermesSessionKey(profileName, b.key), binding: b, session: loaded.session,
         locator: locator.storage?.path ?? null, parent: this.continued?.get(keyString) ?? null, end,
       });
@@ -599,7 +743,7 @@ export class Orchestrator {
     const cached = this.locators?.get(keyString);
     if (cached?.session_id === w.session_id) return cached;
     const { sessions } = await this.client.discover({
-      harnesses: [w.harness], homes: WORKER_STORE[w.harness](join(profile.dir, w.harness)),
+      harnesses: [w.harness], homes: WORKER_STORE[w.harness](w.harness==='hermes'?this.sessionStateHome(profile,w):join(profile.dir, w.harness)),
       include_child_sessions: true, root_session_id: w.session_id, limit: 8,
     });
     const found = sessions.find((d) => d.locator.session_id === w.session_id)?.locator ?? null;
@@ -613,16 +757,21 @@ export class Orchestrator {
    * held when this home was its), its transcript is handed to the worker's harness and materialized in
    * the worker's home, the old mirror sealed, and that new session resumed; otherwise `sessionId`.
    */
-  async continueFromHermes(profile, keyString, worker, sessionId, cwd) {
+  sessionStateHome(profile,worker) {
+    const owner=agentRunForSession(this.state.root,[`${worker.harness}:${worker.session_id}`,`${worker.harness}:${worker.runtime_id}`]);
+    return owner?materializeAgentHome(this.state.root,owner.org,owner.agent_id,profile):profile.dir;
+  }
+
+  async continueFromHermes(profile, keyString, worker, sessionId, cwd,stateHome=this.sessionStateHome(profile,{...worker,session_id:sessionId})) {
     const store = WORKER_STORE[worker.harness];
     if (!store) return sessionId;
-    const state = await mirrorState(profile.dir, sessionId);
+    const state = await mirrorState(stateHome, sessionId);
     if (!state?.ahead) return sessionId;
     try {
-      const hermes = { harness: 'hermes', session_id: sessionId, storage: { kind: 'file', path: join(profile.dir, 'state.db') } };
+      const hermes = { harness: 'hermes', session_id: sessionId, storage: { kind: 'file', path: join(stateHome, 'state.db') } };
       const { artifact } = await this.client.handoffSession({ locator: hermes, target_harness: worker.harness, cwd });
       const { locator } = await this.client.materializeSession({ artifact, cwd, homes: store(join(profile.dir, worker.harness)) });
-      await sealMirror(profile.dir, sessionId, locator.session_id);
+      await sealMirror(stateHome, sessionId, locator.session_id);
       (this.locators ??= new Map()).set(keyString, locator);
       (this.continued ??= new Map()).set(keyString, sessionId);
       this.log('info', `resume ${keyString}: Hermes carried ${sessionId} on (${state.messages} messages); it goes on as ${worker.harness} ${locator.session_id}`);
@@ -644,15 +793,56 @@ export class Orchestrator {
     try { await runtime.steer(text); } catch (error) { requeue(error.message); }
   }
 
-  async sendInput({ profile, keyString, text, context_from = null, skills = [], job_id = null }) {
+  /** A session's whole locator: the harness's doors load a session by its storage address, which discovery names. */
+  async wholeLocator(locator) {
+    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) throw new Error(`${locator.harness}:${locator.session_id} is not in its harness catalogue`);
+    return whole;
+  }
+
+  /** G3: a session's usage, recomputed whole from its harness's own records, returns as an event. */
+  async refreshUsage({ session, agent }) {
+    try {
+      const locator = await this.wholeLocator({ harness: session.harness, session_id: session.session_id });
+      const reply = await this.client.request('harness.v1.sessions.usage', { locator });
+      this.enqueue({ type: 'usage', session: `${session.harness}:${session.session_id}`, agent, usage: reply.usage ?? [], at: this.clock() });
+    } catch (error) { this.log('warn', `usage of ${session.harness}:${session.session_id} unread: ${error.message}`); }
+  }
+
+  /** G3: a refused start is told where the profile's home is and logged; nothing is paused or ended. */
+  tellBudgetRefusal({ profile, agent, reason }) {
+    this.log('warn', `budget: ${reason}`);
+    const owner = this.state.profiles[profile];
+    const home = owner ? homeChannel(owner) : null;
+    if (home) this.enqueue(events.operator({ verb: 'send_message', profile, args: { key: home, text: `Budget: ${reason}. Its next start waits for the window to pass or the budget to change.` }, at: this.clock() }));
+  }
+
+  /** G2: what a transfer's receiver is given of the conversation, from the giving session's own transcript. */
+  async transferHistory(history) {
+    const tail = history.mode === 'filtered' ? Math.max(1, Math.min(200, Number(history.filter?.last ?? 20))) : 200;
+    try {
+      const loaded = await this.client.loadWindow(await this.wholeLocator({ harness: history.harness, session_id: history.session_id }), { message_tail: tail });
+      const lines = (loaded.session?.messages ?? []).filter((m) => ['user', 'assistant'].includes(m.role) && m.content)
+        .map((m) => `${m.role === 'user' ? 'them' : history.from}: ${typeof m.content === 'string' ? m.content : JSON.stringify(m.content)}`);
+      return lines.length ? `The conversation so far (${history.mode === 'full' ? 'whole' : `last ${tail}`}, from ${history.from}'s session):\n${lines.join('\n')}\n\n` : '';
+    } catch (error) { this.log('warn', `transfer history unread: ${error.message}`); return ''; }
+  }
+
+  async sendInput({ profile, keyString, text, context_from = null, skills = [], job_id = null, history = null }) {
     const runtime = this.runtimes.get(leaseId(profile, keyString));
     if (!runtime) { this.log('warn', `send_input with no runtime for ${keyString}`); return; }
     const owner = this.state.profiles[profile];
     const dir = owner?.dir;
     let input = context_from && dir ? contextFromPrefix(dir, job_id, context_from) + text : text;
+    if (history) input = (await this.transferHistory(history)) + input;
     if (skills?.length && owner) input = await this.skillsPrefix(owner, skills, owner.jobs?.[job_id]?.workdir ?? null, input) ?? input;
+    const lid=leaseId(profile,keyString),preamble=this.runtimeAgentPreambles?.get(lid);
+    if(preamble)input=`${preamble}\n\n${input}`;
     try {
       await runtime.sendInput(input);
+      this.runtimeAgentPreambles?.delete(lid);
     } catch (error) {
       // A turn the harness is still running (one this loop did not start, or whose end it has not heard yet) is not a
       // dead session: the line waits for that turn's end, as a refused steer does. Ending the binding on it killed a

package/mcp/bridge.mjs

@@ -37,7 +37,8 @@
 import { SOCKET_ENV } from './server.mjs';
 import { createServer } from 'node:net';
 import { rmSync } from 'node:fs';
-import { runVerb } from './verbs.mjs';
+import { runVerb, keyFromString } from './verbs.mjs';
+import { surfaceKeyString } from '../ir.mjs';
 import { applyOperator } from '../operator.mjs';
 
 export { socketPathFor } from './server.mjs';
@@ -122,7 +123,17 @@ async function dispatch(orch, call, log) {
 async function dispatchOperator(orch, { op, args, profile }, log) {
   const name = typeof profile === 'string' && profile ? profile : 'default';
   let answer;
-  try {
+  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 ?? {};
+      for (const field of ['surface', 'parent', 'harness', 'session_id', 'name', 'key']) if (typeof a[field] !== 'string' || !a[field]) throw new Error(`agents.fork needs ${field}`);
+      const key = keyFromString(a.surface);
+      if (!key) throw new Error(`surface ${JSON.stringify(a.surface)} is not a surface key: write it as platform|kind|chat_id|thread_id|participant_id`);
+      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 try {
     answer = await applyOperator(orch.state, op, args ?? {}, name, orch.clock(), (event) => orch.dispatch(event));
   } catch (error) {
     answer = { ok: false, error: error.message };

package/mcp/tools.mjs

@@ -42,6 +42,23 @@ export const TOOLS = Object.freeze([
       required: ['to'],
     },
   },
+  {
+    name: 'conversation_transfer',
+    // G2: OpenAI Agents' handoff, AutoGen Swarm's HandoffMessage, the voice front's hand_off.
+    description:
+      'Hand this conversation to another agent of this home: your binding ends, the agent takes the conversation '
+      + 'and is given its history. Delegating work is a card, not a transfer.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        to: { type: 'string', description: 'The receiving agent of this home, by name: a profile (`default`, or a profile folder\'s name) or an agent declared in it; never a Claude Code session. A refused name is answered with the home\'s agents.' },
+        reason: { type: 'string', description: 'Why, in one line; the receiver is told.' },
+        history: { type: 'string', enum: ['full', 'filtered', 'none'], description: 'What of the conversation the receiver is given (default full).' },
+        last: { type: 'integer', minimum: 1, maximum: 200, description: 'For filtered: how many recent messages.' },
+      },
+      required: ['to', 'reason'],
+    },
+  },
 ]);
 
 /**