@volter/supercode-orchestrator 0.5.68 → 0.5.70

package/agent-door.mjs

@@ -0,0 +1,75 @@
+// The orchestrator's door to Teams for agent identity, called in-process through the installed neutral SDK: the board's
+// owner is resident and async, so it awaits the request itself, never through a helper process.
+import { isCallersCall } from './board/call.mjs';
+import { fromContext, WorkspaceContexts } from '@volter/teams/context';
+import { supercodeHome } from '@volter/teams/home';
+import { openMachine, normalMachineName } from '@volter/teams/machine-door';
+import { StreamRpc } from '@volter/teams/client';
+import { hostname } from 'node:os';
+
+// This machine is reached through its own daemon's socket, never through the Teams server: the server route lists the
+// org's machines and opens a channel on the shared credential's allowance for a request that never leaves the box.
+const reach = (machine) => machine && normalMachineName(machine) !== normalMachineName(hostname()) ? machine : null;
+// A caller's verb in the board's owner names its context (the CLI and the daemon send it): an absent one is refused,
+// never taken from the owner's own environment. The process's own work reads its environment, then the selection.
+const contextOf = (context) => {
+  if (context) return context;
+  if (isCallersCall()) throw Object.assign(new Error('the caller named no Teams context'), { code: 'invalid_request' });
+  return process.env.SUPERCODE_CONTEXT ?? new WorkspaceContexts(supercodeHome()).read().current;
+};
+
+/**
+ * The Org agent identity belongs to: the selected Teams context as this home records it (read locally, no request), or
+ * this home's local store when none is selected. A context named but unreadable here is this home's error, and throws.
+ */
+export function agentScope(context) {
+  const named = contextOf(context);
+  if (!named || named === 'local') return { server: 'local', org: 'local', principal: null, offline: true, reason: 'no Teams context is selected' };
+  const { context: scope } = fromContext({ supercodeHome: supercodeHome(), name: named });
+  return { server: scope.origin, server_id: scope.server_id, org: scope.team_id, principal: scope.principal_id };
+}
+
+/** One agent-identity request to the selected context's Teams server. Throws its refusal, with its status and code. */
+export async function agentDoor(op, args = [], { context, timeout = 25_000 } = {}) {
+  if (op === 'scope') return agentScope(context);
+  const named = contextOf(context);
+  const { client, context: scope } = fromContext({ supercodeHome: supercodeHome(), name: named });
+  const team = client.team(scope.team_id);
+  // the door names itself to the server's tally of who spent the credential's allowance (X-Supercode-Caller)
+  const options = { signal: AbortSignal.timeout(timeout), caller: `agent-door ${op}` };
+  switch (op) {
+    case 'root': return team.agents.root(options);
+    case 'get': return team.agents.get(args[0], options);
+    case 'management': return team.agents.management(args[0], options);
+    case 'profile': return team.agents.update(args[0], { profile: args[1] }, { ...options, ifMatch: args[2] });
+    case 'reparent': return team.agents.update(args[0], { parent: args[1] }, { ...options, ifMatch: args[2] });
+    case 'declare': return team.agents.declare(args[0], { ...options, idempotencyKey: args[1] });
+    case 'sessions': return team.agents.sessions(args[0], args[1] ?? {}, options);
+    case 'ownSession': return team.agents.ownSession(args[0], args[1], { ...options, idempotencyKey: args[2] });
+    case 'session': return team.sessions.get(args[0]).identity(options);
+    case 'end': {
+      const agent = (await team.agents.get(args[0], options)).data;
+      return agent.state === 'ended' ? { data: { id: agent.id, state: 'ended' } } : team.agents.end(agent.id, { reason: args[1] }, { ...options, ifMatch: agent.revision, idempotencyKey: args[2] });
+    }
+    case 'reader': return team.agents.delegateReader(args[0], {}, { ...options, ifMatch: args[1] });
+    case 'readerContext': {
+      const identity = await team.agents.get(args[0], options);
+      const reader = await team.agents.delegateReader(args[0], { expires_in_ms: 86_400_000 }, { ...options, ifMatch: identity.data.revision });
+      const channel = await openMachine({ machine: reach(args[1]), context: named });
+      try { return await new StreamRpc(await channel.open('node')).call('harness.v1.agents.context', { origin: scope.origin, team: scope.team_id, agent: args[0], credential: reader.data }); }
+      finally { channel.close(); }
+    }
+    case 'resolveIdentity': return team.identity.resolve(args[0], options);
+    case 'find': {
+      let after = '';
+      do {
+        const page = await team.agents.list({ after, limit: 200 }, options);
+        const found = page.items.find((agent) => agent.name === args[0] && agent.parent === args[1] && agent.state !== 'ended') ?? null;
+        if (found) return { data: found };
+        after = page.next_after;
+      } while (after);
+      return { data: null };
+    }
+    default: throw Object.assign(new Error('unsupported agent door'), { code: 'invalid_request' });
+  }
+}

package/agents.mjs

@@ -2,28 +2,15 @@
 import { DatabaseSync } from 'node:sqlite';
 import { mkdirSync } from 'node:fs';
 import { join, basename } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { spawnSync } from 'node:child_process';
 import { createHash, randomBytes } from 'node:crypto';
 import { runtimeDoor } from './board/runtime-door.mjs';
 import { resolveAgentProfile } from './agent-profiles.mjs';
 import { compareAgentProfile } from '@volter/teams/agent-profile';
 import { WorkspaceContexts } from '@volter/teams/context';
 import { supercodeHome } from '@volter/teams/home';
-const entry=fileURLToPath(new URL('./bin/agent-door.mjs',import.meta.url));
-// The caller each door names to Teams (X-Supercode-Caller): this host's own command words, then the door's operation.
-const HOST_CALLER=(process.env.SUPERCODE_CALLER_NAME??`orchestrator ${process.argv.slice(2).filter(arg=>!arg.startsWith('-')).slice(0,2).filter(arg=>/^[a-z][a-z0-9-]{0,30}$/.test(arg)).join(' ')}`).slice(0,80);
-const lastJson=text=>{for(const line of String(text??'').trim().split('\n').reverse()){try{const value=JSON.parse(line);if(value&&typeof value==='object')return value;}catch{/* not the door's line */}}return null;};
-export function agentDoor(op,args=[],{context,timeout=25000}={}){
-  const reply=spawnSync(process.execPath,[entry],{input:JSON.stringify({op,args,context}),encoding:'utf8',timeout,maxBuffer:4*1024*1024,env:{...process.env,SUPERCODE_CALLER_NAME:`${HOST_CALLER} agent-door ${op}`}});
-  // The door's answer to a failure is the last stderr line that is JSON: a runtime's own lines (a preload's notice, a
-  // Node warning) may come before or after it.
-  if(reply.status!==0){const detail=lastJson(reply.stderr)??{message:reply.error?.message??String(reply.stderr).slice(-1000)};throw Object.assign(new Error(detail.message??'Teams agent door unavailable'),detail);}
-  return JSON.parse(reply.stdout);
-}
-/** The Org agent identity belongs to: the selected Teams context as this home records it (read locally, no request),
- * or this home's local store when none is selected. A context named but unreadable here is this home's error, and throws. */
-export function agentScope(context){return agentDoor('scope',[],{context});}
+// Agent identity is Teams's (agent-door.mjs, in-process); its intent and assignments are this home's (below).
+export { agentDoor, agentScope } from './agent-door.mjs';
+import { agentDoor, agentScope } from './agent-door.mjs';
 function store(root){
   mkdirSync(root,{recursive:true,mode:0o700});const db=new DatabaseSync(join(root,'agent-state.sqlite'));
   db.exec(`PRAGMA busy_timeout=5000; PRAGMA journal_mode=WAL;
@@ -50,13 +37,13 @@ export function assignAgent(root,org,id,{kind,target,role}){
   const db=store(root),key=digest(JSON.stringify([kind,target,role]));try{db.prepare("INSERT INTO agent_assignments(org,id,agent_id,kind,target,role,state,started_at) VALUES (?,?,?,?,?,?,'active',?) ON CONFLICT(org,id) DO UPDATE SET agent_id=excluded.agent_id,state='active',ended_at=NULL").run(org,key,id,kind,target,role,Date.now());return key;}finally{db.close();}
 }
 export function activeAgentAssignments(root){const db=store(root);try{return db.prepare("SELECT * FROM agent_assignments WHERE state='active'").all();}finally{db.close();}}
-export function reassignAgent(root,org,assignment,to,{context}={}) {
-  const target=agentDoor('management',[to],{context}).data;
+export async function reassignAgent(root,org,assignment,to,{context}={}) {
+  const target=(await agentDoor('management',[to],{context})).data;
   const db=store(root);
   try {
     const old=db.prepare("SELECT * FROM agent_assignments WHERE org=? AND id=? AND state='active'").get(org,assignment);
     if(!old)throw new Error('active assignment not found');
-    if(old.agent_id!==to)agentDoor('management',[old.agent_id],{context});
+    if(old.agent_id!==to)await agentDoor('management',[old.agent_id],{context});
     db.exec('BEGIN IMMEDIATE');
     const moved=db.prepare("UPDATE agent_assignments SET agent_id=? WHERE org=? AND id=? AND agent_id=? AND state='active'").run(to,org,assignment,old.agent_id);
     if(moved.changes!==1)throw new Error('assignment changed while reassigning it');
@@ -224,10 +211,43 @@ export function localForkAgent(options){
  * socket), which declares and ends them in Teams (D137: identity is Teams' job, never the dispatcher's or the gateway's).
  * Local only: a daemon not running keeps them here for the next hand-off. Answers what could not be handed on.
  */
-export function handOffAgents(root,{context=process.env.SUPERCODE_CONTEXT}={}){
-  const scope=agentScope(context);if(scope.offline)return [];
-  adoptLocalOrg(root,scope);
+/**
+ * The Teams context this machine has for `org`: the one context of that team that is not an agent's delegated reader
+ * context (`agent-…`); among several, the selected one. Null when there is none, or several and none selected: the
+ * caller says so rather than taking another org's or the process's.
+ */
+function contextForOrg(org){
+  const doc=new WorkspaceContexts(supercodeHome()).read();
+  const names=Object.entries(doc.contexts??{}).filter(([name,value])=>value?.team_id===org&&!name.startsWith('agent-')).map(([name])=>name);
+  return names.length===1?names[0]:names.includes(doc.current)?doc.current:null;
+}
+
+/**
+ * Hand this home's pending agent declarations and ends to Teams, each org's through this machine's context for that org
+ * (the context named, for its org alone). Never the process's own environment: the work was recorded for an org, and
+ * that org's context is the one that delivers it.
+ */
+export function handOffAgents(root,{context=null}={}){
   const waiting=[];
+  if(context){const scope=agentScope(context);if(!scope.offline)handOffOrg(root,scope,waiting);return waiting;}
+  let orgs;
+  const db=store(root);
+  try{orgs=db.prepare("SELECT org FROM agent_intents WHERE declared=0 AND declaration_json IS NOT NULL UNION SELECT org FROM agent_end_outbox").all().map(row=>row.org).filter(org=>org&&org!=='local');}
+  finally{db.close();}
+  for(const org of orgs){
+    // one org whose context cannot be read (a saved context gone bad) is said and left; the others are still handed off
+    try{
+      const named=contextForOrg(org);
+      if(!named){waiting.push({agent:'*',error:`no Teams context on this machine for org ${org} (or several, none selected); its agent work waits`});continue;}
+      const scope=agentScope(named);
+      if(!scope.offline&&scope.org===org)handOffOrg(root,scope,waiting);
+    }catch(error){waiting.push({agent:'*',error:`org ${org}: ${error.message}; its agent work waits`});}
+  }
+  return waiting;
+}
+
+function handOffOrg(root,scope,waiting){
+  adoptLocalOrg(root,scope);
   let db=store(root),rows,ends;
   try{
     rows=db.prepare('SELECT * FROM agent_intents WHERE org=? AND declared=0 AND declaration_json IS NOT NULL ORDER BY created_at').all(scope.org);
@@ -254,7 +274,6 @@ export function handOffAgents(root,{context=process.env.SUPERCODE_CONTEXT}={}){
       db.prepare('DELETE FROM agent_end_outbox WHERE org=? AND agent_id=?').run(scope.org,row.agent_id);
     }finally{db.close();}
   }
-  return waiting;
 }
 /** A managed runtime may report its native id after opening. Keep the lease pointer out of the catalogue. */
 export function recordNativeAgentSession(root,runtimeRef,session) {

package/bin/agent-channel.mjs

@@ -11,8 +11,10 @@
 // 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: the principal (`--principal`, RH2's principal id) as its operator, and the bot seated in its conversation
-// answering every line. `--room <id>` names an existing Room instead and opens nothing.
+// 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 … --profile <agent>` in the home, `--root` or HERMES_HOME), so its threads, its DM
@@ -37,10 +39,10 @@ import { installedApps } from '../installed-apps.mjs';
 
 const { values } = parseArgs({
   args: process.argv.slice(3),
-  options: { agent: { type: 'string' }, root: { type: 'string' }, room: { type: 'string' }, 'room-key': { type: 'string' }, 'room-name': { type: 'string' }, principal: { 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' }, 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' } },
 });
 if (values.help || !values.agent) {
-  console.log('supercode-orchestrator agent-channel --agent <name> [--root <home>] [--room <id> | --room-key <key> --principal <rh2 principal id> [--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>]');
+  console.log('supercode-orchestrator agent-channel --agent <name> [--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>]');
   process.exit(values.help ? 0 : 2);
 }
 const log = (level, line) => (level === 'debug' ? undefined : console.error(`${new Date().toISOString()} ${level} ${line}`));
@@ -99,10 +101,15 @@ async function accountRoom() {
   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: [{ principalId: values.principal, roleKeys: ['operator'] }],
+    members: seated.map((principalId) => ({ principalId, roleKeys: [values.role] })),
   });
   const view = await adapter.get(`/rooms/${encodeURIComponent(room.roomId)}`);
   const conversation = view.room?.defaultConversationId;

package/bin/orchestrator.mjs

@@ -9,7 +9,7 @@
 }
 // Board commands do not load daemon transports, platform adapters or the MCP server.
 if (process.argv[2] === 'workflow') {
-  const [{runWorkflow},{closeWorld},{timeCommand}]=await Promise.all([import('../board/cli.mjs'),import('../orchestration.mjs'),import('@volter/supercode-harness-sdk/slow-log')]);
+  const [{runWorkflow},{timeCommand}]=await Promise.all([import('../board/client.mjs'),import('@volter/supercode-harness-sdk/slow-log')]);
   // A board command is timed into the slow log; `serve` runs until stopped and is not one.
   const verb=process.argv.slice(3).find((arg,index,all)=>!arg.startsWith('-')&&!(index>0&&/^--(root|board|cwd|context|at)$/.test(all[index-1])));
   if(verb!=='serve')timeCommand(`workflow ${verb??''}`.trim(),process.argv.slice(3));
@@ -18,7 +18,6 @@ if (process.argv[2] === 'workflow') {
   // a store's own error (SQLite's, with its errcode) is no message written for a person: its stack says which statement
   // met it, as a follower's end in the connector's log (board events) otherwise could not
   catch(error) {process.stderr.write(`supercode workflow: ${error.message??error}\n${error?.errcode!=null&&error.stack?`${error.stack}\n`:''}`);code=1;}
-  finally {await closeWorld();}
   await Promise.all([process.stdout,process.stderr].map(stream=>new Promise(done=>stream.write('',done))));
   process.exit(code);
 } else if (process.argv[2] === 'agent-channel') {

package/board/agent-declarations.mjs

@@ -14,7 +14,9 @@ export function declareCardAgentEffect(board,effect) {
   const told=view(board,db=>new Set(db.prepare("SELECT payload FROM task_events WHERE task_id=? AND kind='agent_declaration_pending' AND id>COALESCE((SELECT max(id) FROM task_events WHERE task_id=? AND kind='agent_declared'),0)").all(effect.id,effect.id).map(row=>json(row.payload,{})?.reason)));
   try {
     if(!entry.profiles[profile])throw new Error('card agent declaration needs a named profile');
-    const context=effect.context??process.env.SUPERCODE_CONTEXT,scope=agentScope(context);
+    // the context the card's creator named, kept with the declaration: never the context of whoever retries it
+    if(!effect.context)throw new Error('the card agent declaration recorded no Teams context; it is declared again by a call that names one');
+    const context=effect.context,scope=agentScope(context);
     const options={root:board.root,org:scope.org,server:scope.server,profiles:entry.profiles,
       profile,card:effect.id,role:effect.role,sponsor:task.sponsor??null,context,starterSession:effect.starter_session};
     const agent=localCardAgent(options);

package/board/args.mjs

@@ -0,0 +1,36 @@
+// A workflow verb's arguments, as the CLI and the board's owner both read them.
+import { resolve } from 'node:path';
+
+export const MULTI = new Set(['parent', 'skill', 'worker', 'child', 'ids', 'rm', 'tag', 'pr', 'pr-head', 'reviewed-sha', 'finding']);
+export const FLAGS = new Set(['json', 'triage', 'no-notify', 'no-start', 'all', 'force', 'help', 'mine', 'archived', 'reclaim', 'dry-run',
+  'once', 'goal', 'no-goal', 'off', 'switch', 'delete', 'no-attachments', 'include-logs', 'verbose', 'commit']);
+// flags that take every following word up to the next flag (Hermes's nargs='+')
+export const GREEDY = new Set(['ids', 'rm']);
+
+export function parse(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (!a.startsWith('--') || a === '--') { out._.push(a); continue; }
+    const [key, inline] = a.slice(2).split(/=(.*)/s);
+    if (FLAGS.has(key)) { out[key] = true; continue; }
+    if (GREEDY.has(key)) {
+      const values = inline !== undefined ? [inline] : [];
+      while (i + 1 < argv.length && !argv[i + 1].startsWith('--')) values.push(argv[++i]);
+      (out[key] ??= []).push(...values);
+      continue;
+    }
+    const value = inline ?? argv[++i];
+    if (value === undefined) throw new Error(`--${key} needs a value`);
+    if (MULTI.has(key)) (out[key] ??= []).push(value);
+    else out[key] = value;
+  }
+  return out;
+}
+
+/** The home a verb names: `--root`, else the home's own variable. */
+export function homeOf(args) {
+  const root = args.root ?? process.env.SUPERCODE_ORCHESTRATOR_HOME;
+  if (!root) throw new Error('which home? --root <home> (or SUPERCODE_ORCHESTRATOR_HOME)');
+  return resolve(root);
+}

package/board/call.mjs

@@ -0,0 +1,45 @@
+// The call a board verb answers: who it answers for and where its answer goes. A board's resident owner (`workflow
+// serve`) answers many callers' verbs at once, each a call of its own, so nothing that names the caller or writes the
+// answer reads it from the process: it reads the call it runs in. A process's own work (the owner's dispatching, an
+// operation verb run on the machine) runs in the process's own call.
+//
+//   caller     the calling session's address (`sc:<machine>:<harness>:<id>`), as the caller's own side named it, or null
+//   facts      what the caller's environment says of it: SUPERCODE_AGENT_ID, SUPERCODE_AUTOMATION, SUPERCODE_CONTEXT,
+//              HERMES_PROFILE, USER (the process's own environment in its own call)
+//   actor, principal, roles, recorded   what the verb learns of the caller as it runs (store.mjs, engine.mjs, cli.mjs)
+//   said       the standing warnings this call has already been told (a backing's, once per call)
+//   cwd        the caller's working directory, against which a path it names is read
+//   stdin      what the caller sent on its standard input, for a `-` it names as a file (null: none)
+//   out, err   where the verb writes its answer
+import { readFileSync } from 'node:fs';
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+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)
+const fresh = () => ({ actor: null, principal: null, roles: () => ['manager'], recorded: null, workflows: new Map(), said: new Set() });
+// the process's own context pins no workflow (it lives as long as the process): its reads always take the latest
+const unpinned = { get: () => undefined, set: () => {} };
+const own = { kind: 'own', caller: null, facts: process.env, ...fresh(), workflows: unpinned, get cwd() { return process.cwd(); }, get stdin() { return readFileSync(0, 'utf8'); }, out: (text) => process.stdout.write(text), err: (text) => process.stderr.write(text) };
+
+/** The call running now: a caller's verb in the owner, else the process's own. */
+export const current = () => calls.getStore() ?? own;
+
+/** Run `fn` as one caller's call, its answer written through `out` and `err`. */
+export function within({ caller = null, facts = {}, cwd, stdin = null, out, err }, fn) {
+  return calls.run({ kind: 'caller', caller, facts, ...fresh(), cwd, stdin, out, err }, fn);
+}
+
+/** 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 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. */
+export function callerOf(call = current()) {
+  const m = /^sc:([^:\s]+):(claude-code|codex):([^:\s]+)$/.exec(call.caller ?? '');
+  return m ? { address: m[0], machine: m[1], harness: m[2], session: m[3] } : null;
+}
+
+/** Whether this is a caller's call in the owner rather than the process's own. */
+export const isCallersCall = () => calls.getStore()?.kind === 'caller';

package/board/caller-session.mjs

@@ -0,0 +1,25 @@
+// The session this process runs in, as its own harness names it (Claude Code CLAUDE_CODE_SESSION_ID, Codex
+// CODEX_THREAD_ID). A pane inherits every variable the program that started its terminal server had, so a Codex pane
+// can carry a Claude session's id too: the nearest harness among the process's ancestors says which is its own.
+import { spawnSync } from 'node:child_process';
+import { basename } from 'node:path';
+
+export function processSession() {
+  const claude = process.env.CLAUDE_CODE_SESSION_ID || null;
+  const codex = process.env.CODEX_THREAD_ID || null;
+  if (!claude || !codex) return claude ?? codex;
+  const table = spawnSync('ps', ['-A', '-o', 'pid=,ppid=,comm='], { encoding: 'utf8' });
+  const processes = new Map();
+  for (const row of String(table.stdout ?? '').split('\n')) {
+    const m = row.trim().match(/^(\d+)\s+(\d+)\s+(.*)$/);
+    if (m) processes.set(Number(m[1]), { parent: Number(m[2]), name: basename(m[3]) });
+  }
+  for (let pid = process.ppid, depth = 0; pid > 1 && depth < 64; depth++) {
+    const p = processes.get(pid);
+    if (!p) break;
+    if (p.name === 'codex') return codex;
+    if (/^claude(\.exe)?$/.test(p.name)) return claude;
+    pid = p.parent;
+  }
+  return claude;
+}