@volter/supercode-orchestrator 0.5.226 → 0.5.227

package/README.md

@@ -80,8 +80,8 @@ Other SDK callers that persist runtime state set `preserve_workflow: true` on
 `workflow serve` retains its public socket and kernel lock while dispatcher generations change.
 `workflow handover --entry /absolute/path/to/bin/orchestrator.mjs --supercode /absolute/path/to/native --root HOME`
 prepares a successor through the normal source checks, drains admitted work, and transfers its writer epoch.
-It routes calls only after a clean round and a successful stats reply. The parked predecessor remains available
-for rollback after candidate loss. A request already sent to a lost generation returns an unknown outcome and
+It routes calls only after a clean round and a successful stats reply. A candidate lost before the handover finishes
+rolls back to a fresh generation started from the predecessor's selection; finishing ends the parked predecessor. A request already sent to a lost generation returns an unknown outcome and
 is never replayed. This source mechanism still needs the complete machine release integration and recorded
 qualification described in [ADR 0080](../../docs/adr/0080-serving-generation-handovers.md).
 
@@ -517,8 +517,9 @@ Workplace in the home: the Agents → Room agents integration (`sdk/teams/workpl
 every agent it provides, the token of its principal minted at RH2's agent-token door on that registration's own
 installation (`rh2-agent.<agent id>@<Workplace host>`, renewed before it lapses, revoked when Teams ends the agent); one
 can also be kept by hand. Every session of the agent acts through them (the `rh2` CLI and MCP read the record for the
-Workplace each call goes to, from `RH2_AGENT_HOMES`), the agent's channel joins its Room's conversation on its record,
-and orchestrator-launched sessions mount them as the `rh2-agent` MCP server, never in another agent's that shares its
+Workplace each call goes to, from `RH2_AGENT_HOMES` or `SUPERCODE_AGENT_HOME`; a board pane of the agent on another
+machine reads the copies the board keeps in the agent's home on that machine, `harness.v1.agent.credentials.keep`),
+the agent's channel joins its Room's conversation on its record, and orchestrator-launched sessions mount them as the `rh2-agent` MCP server, never in another agent's that shares its
 name or profile. Kept by hand:
 
 ```sh
@@ -826,20 +827,30 @@ return through adoption and released availability remain unqualified.
 
 ## Readable card ids
 
-Every card has a `readable_id` beside its number and native id. Create one with
-`supercode workflow create "Voice calls" --readable-id voice-calls --root HOME`,
-or let the board derive it from the title. Names use lowercase kebab-case, start
-with a letter, have at most 32 characters and are unique among open cards.
-Automatic collisions gain a numeric suffix; explicit duplicates are refused.
-
-`workflow list` and `show` display the name. `workflow specify CARD --readable-id
-voice-calls --root HOME` changes it; the same `readable_id` property is editable
-in a ztrack card's metadata in `arcs.md`. A title edit keeps its existing id.
-Older boards fill missing names from leading title slugs before other title words.
-
-Generated branches use `vo-42-voice-calls`. Card agents become
+Every card has a `readable_id` beside its number and native id, given by its
+creator: `supercode workflow create "Voice calls" --readable-id voice-calls --root HOME`.
+A create without one is refused. Names are a few lowercase words joined by
+hyphens, start with a letter, have at most 32 characters and are unique on the
+board, among open and ended cards alike. A subtask, which no person names, takes
+one from its title; so do rows an older board or a hand-written document left
+without one.
+
+`workflow list`, `show`, `create`, capacity, notices and mail subjects lead with
+the name (`voice-calls (VO-42 t_4406c88a)`), and every verb takes it where it
+takes a card id. `workflow specify CARD --readable-id voice-calls --root HOME`
+changes it; the same `readable_id` property is editable in a ztrack card's
+metadata in `arcs.md`. A title edit keeps its existing id.
+
+A new worktree card's branch and worktree folder are its readable id
+(`voice-calls`, under a project's `<slug>/` for the branch), refused when another
+card's branch already has that name. Until the card's worktree is first made, its
+machine refuses a branch of that name already in the checkout or on origin, or a
+folder of that name, that the card did not make; `main`, `master`, `publish` and the
+repository's default branch are never a card's. Fresh sessions are named `voice-calls-3f`
+(a reviewer's `voice-calls-reviewer-3f`). Card agents become
 `implementer-voice-calls` or `reviewer-voice-calls`, with the same immutable agent
 id and sessions; the ordinary delivery pass sends existing agents' renames to
 the machine. The Workplace updates its existing principal and spoken name.
-Existing worktrees, explicit branches and personal naming overrides keep their
-normal protections. Merge and release remain separate from this source behavior.
+A card's recorded branch and worktree folder never follow a later rename, and
+existing sessions keep their names. Merge and release remain separate from this
+source behavior.

package/adapters/rh2.mjs

@@ -3,7 +3,7 @@
 // content) / close(). The orchestrator holds an RH2 session (the bot
 // principal's automation token), reads the Rooms it may read and answers
 // every line its conversation participation asks for only in a Room it was
-// brought into by the join command (RH2's `broughtIn` on the Room's members),
+// brought into by the join command (a participant of the Room's base channel: an app holds no seat, runhuman-2 ADR 0063),
 // elsewhere only a line naming it, the way it does in a Slack channel. RH2's own rule keeps a coding seat and this loop
 // from answering each other: a seat is never woken by an agent's message, and
 // this adapter turns only a person's line (kind `human`, or a trigger's
@@ -11,7 +11,7 @@
 //
 // Doors (RH2 `/api/v3`, bearer + `x-rh2-organization`):
 //   GET  /rooms                                            the Rooms to follow
-//   GET  /rooms/:room/view                                 members (names, broughtIn), conversations (permissions, nextSequence)
+//   GET  /rooms/:room/view                                 members (names), conversations (permissions, participants, nextSequence)
 //   GET  /rooms/:room/conversations/:c/messages?after=&limit=
 //   POST /rooms/:room/conversations/:c/messages            {body, correlationId, kind: "agent", parentMessageId?}
 //   PATCH /rooms/:room/conversations/:c/messages/:id        {body} — a streamed reply grows, a progress line updates, by edit
@@ -160,9 +160,10 @@ export class Rh2Adapter {
       const room = view.room ?? {};
       if (room.state && room.state !== 'active') continue;
       const names = new Map((view.members ?? []).filter((m) => m.principalId).map((m) => [String(m.principalId), String(m.displayName ?? m.principalId)]));
-      // Whether this principal is in the Room is RH2's own answer: brought in by the join command (`broughtIn`, runhuman-2
-      // ADR 0063). Only then does it take the lines its channel participation asks for; elsewhere, only those naming it.
-      const broughtIn = (view.members ?? []).some((m) => String(m.principalId) === this.principalId() && m.broughtIn === true);
+      // Whether this principal was brought into the Room is RH2's own answer: the join command makes an app a participant
+      // of the Room's base channel and gives it Room access, never a seat (runhuman-2 ADR 0063 decision 1). Only then does
+      // it take the lines its channel participation asks for; elsewhere, only those naming it.
+      const broughtIn = (view.conversations ?? []).some((c) => c.conversationId === room.defaultConversationId && (c.agentParticipants ?? []).some((p) => String(p.principalId) === this.principalId()));
       // Where this principal's own seat carries a session, the Workplace delivers the Room's lines to that session itself
       // (runhuman-2 ADR 0046 decision 4); this adapter then hands none of them on, so no line reaches it twice.
       const seated = (view.members ?? []).some((m) => String(m.principalId) === this.principalId() && m.sessionBinding);

package/bin/connection-runner.mjs

@@ -1,25 +1,49 @@
 #!/usr/bin/env node
 // The home's installed-app runner owns only children it starts, and every connection keeps separate custody.
-import { existsSync, openSync, closeSync, readFileSync, unlinkSync, renameSync } from 'node:fs';
+import { existsSync, openSync, closeSync, readFileSync, realpathSync, rmSync, unlinkSync, renameSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { spawn } from 'node:child_process';
 import { parseArgs } from 'node:util';
-import { SERVICE_APPS, SERVICE_PROGRAM, connectionCall, connectionCanRun, connectionPath, generateModuleConfig, privateJson } from '../connection.mjs';
+import { readSourceLock, sourceRoot } from '@volter/supercode-teams/source-lock';
+import { SERVICE_APPS, SERVICE_PROGRAM, connectionCall, connectionCanRun, connectionPath, generateModuleConfig, privateJson, runnerStopPath, stopConnectionRunner } from '../connection.mjs';
 
 const {values}=parseArgs({options:{root:{type:'string'},connection:{type:'string'}}});
-const path=connectionPath(values.root,values.connection),lock=join(dirname(path),'runner.lock');
+const path=connectionPath(values.root,values.connection),lock=join(dirname(path),'runner.lock'),stopFile=runnerStopPath(lock);
+const log=(event,data={})=>process.stdout.write(JSON.stringify({t:new Date().toISOString(),event,...data})+'\n');
+const alive=pid=>{try{process.kill(pid,0);return true;}catch(error){if(error.code!=='ESRCH')throw error;return false;}};
+// The tree this runner is loaded from, recorded in its lock: a source checkout's root, else its installed package.
+const tree=sourceRoot(import.meta.url)??realpathSync(fileURLToPath(new URL('..',import.meta.url)));
+// Serving is what the machine's source declaration names, as this runner's starter selected it (an activating kit's
+// gateway carries its candidate); with none declared, the runner a gateway has just started is the selection.
+function serving(){
+  let declared;try{declared=readSourceLock(process.env);}catch(error){log('runner-handover-unknown',{reason:String(error.message).slice(0,300)});return false;}
+  if(!declared)return true;
+  try{return realpathSync(declared.root)===tree;}catch{return false;}
+}
 let record=JSON.parse(readFileSync(path,'utf8'));
 record.root=values.root;
 if(!connectionCanRun(record))process.exit(0);
 if(existsSync(lock)){
   const previous=JSON.parse(readFileSync(lock,'utf8'));
-  try{process.kill(previous.pid,0);process.exit(0);}catch(error){if(error.code!=='ESRCH')throw error;}
-  renameSync(lock,`${lock}.stopped-${Date.now()}`);
+  // A source activation restarts the gateway on the new tree, which starts this home's runners again: a live runner of
+  // the same tree keeps the connection, and one of another tree (a lock without a tree predates this record) yields to a
+  // successor of the serving tree. It stops as `disconnect` stops it, its own children first, and the successor reads
+  // the record it last saved (renewed credentials, health) before starting any child, so no two runners hold custody.
+  if(alive(previous.pid)){
+    if(previous.tree===tree||!serving())process.exit(0);
+    log('runner-handover',{predecessor:previous.pid,from:previous.tree??null,to:tree});
+    // Never ended alone: its modules would outlive it with nobody stopping them. The next gateway start asks again.
+    if(!await stopConnectionRunner(lock,previous)){log('runner-handover-refused',{predecessor:previous.pid,reason:'predecessor did not stop within 20s'});process.exit(1);}
+    record=JSON.parse(readFileSync(path,'utf8'));record.root=values.root;
+    if(!connectionCanRun(record))process.exit(0);
+  }
+  if(existsSync(lock))renameSync(lock,`${lock}.stopped-${Date.now()}`);
 }
-const fd=openSync(lock,'wx',0o600);closeSync(fd);privateJson(lock,{pid:process.pid,connection:record.id});
+const fd=openSync(lock,'wx',0o600);closeSync(fd);privateJson(lock,{pid:process.pid,connection:record.id,tree});
+rmSync(stopFile,{force:true});
 const children=new Map(),health=record.health??={},raised=record.raised??{};
 let stopped=false;
-const log=(event,data={})=>process.stdout.write(JSON.stringify({t:new Date().toISOString(),event,...data})+'\n');
 const save=()=>{record.health=health;record.raised=raised;privateJson(path,record);};
 const teamPath=`/api/v1/teams/${encodeURIComponent(record.teams.team)}`;
 const issue=(name,reason)=>{health[name]={state:'unavailable',reason,at:new Date().toISOString()};save();};
@@ -31,7 +55,7 @@ function start(grant){
   if(SERVICE_APPS.includes(grant.name)&&grant.name!=='agents')return;
   if(stopped||children.has(grant.name)||!existsSync(join(values.root,'apps',`${grant.name}.${record.id}.json`)))return;
   const config=generateModuleConfig(values.root,record,grant);
-  const program=SERVICE_APPS.includes(grant.name)?SERVICE_PROGRAM:join(record.moduleRoot,grant.name,'main.mjs');
+  const program=SERVICE_APPS.includes(grant.name)?SERVICE_PROGRAM:grant.program??join(record.moduleRoot,grant.name,'main.mjs');
   const child=spawn(process.execPath,[program,config],{stdio:['ignore','pipe','pipe'],env:{...process.env,SUPERCODE_ORCHESTRATOR_HOME:values.root,HERMES_HOME:values.root}});
   children.set(grant.name,child);let buffer='';
   child.stdout.on('data',chunk=>{
@@ -44,7 +68,9 @@ function start(grant){
     }
     if(buffer.length>65536)buffer='';
   });
-  child.stderr.on('data',chunk=>{process.stderr.write(chunk);if(!stopped)issue(grant.name,'module wrote a startup/runtime error; inspect its runner log');});
+  // An exit names a module's trouble more exactly than its stderr; while it is unavailable a restart's stderr keeps the
+  // reason it has, so a crash loop is one raised alert, not one per restart.
+  child.stderr.on('data',chunk=>{process.stderr.write(chunk);if(!stopped&&health[grant.name]?.state!=='unavailable')issue(grant.name,'module wrote a startup/runtime error; inspect its runner log');});
   child.on('error',error=>issue(grant.name,error.code??'start-failed'));
   child.on('exit',(code,signal)=>{
     children.delete(grant.name);if(!stopped){issue(grant.name,`module exited (${code??signal})`);setTimeout(()=>start(grant),5000);}
@@ -87,20 +113,28 @@ async function renewTeams(value){
 function randomHex(size){return crypto.getRandomValues(new Uint8Array(size)).reduce((out,n)=>out+n.toString(16).padStart(2,'0'),'');}
 function randomBase64(){return Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString('base64url');}
 async function renew(){
+  const restart=new Set();
   for(const grant of record.grants){
     if(!existsSync(join(values.root,'apps',`${grant.name}.${record.id}.json`)))continue;
     try{
       let changed=false;
       if(Date.parse(grant.rh2.expiresAt)-Date.now()<=7*86400000){grant.rh2={...grant.rh2,...(await connectionCall(record,'rh2','POST',`/api/v3/automation/installations/${grant.rh2.installationId}/renew`,{},grant.rh2.accessToken)).data};changed=true;save();}
       if(grant.teams)changed=await renewTeams(grant.teams)||changed;
-      // A renewed credential reaches its program by a restart with a regenerated config (the service's, for its registrations).
-      if(changed){const host=record.grants.find(g=>g.name===childOf(grant));if(host&&existsSync(join(values.root,'apps',`${host.name}.${record.id}.json`))){await stopChild(host.name);start(host);}}
+      if(changed)restart.add(childOf(grant));
       if(!grant.teams?.pendingRenewal)recover(`expiry.${grant.name}`);
     }catch(error){issue(`expiry.${grant.name}`,error.code??'renewal-unavailable');}
   }
+  // A renewed credential reaches its program by a restart with a regenerated config (the service's, for its registrations):
+  // once per pass, however many of the program's registrations renewed in it.
+  for(const name of restart){const host=record.grants.find(g=>g.name===name);if(host&&existsSync(join(values.root,'apps',`${host.name}.${record.id}.json`))){await stopChild(host.name);start(host);}}
+  // An adopted service's connection holds no issuer installation of its own: the Workplace's issuer registration is its
+  // deployment's (connection.mjs adoptWorkplaceService).
+  if(!record.issuerCredential)return;
   try{await renewTeams(record.issuerCredential);if(!record.issuerCredential.pendingRenewal)recover('issuer-renewal');}catch(error){issue('issuer-renewal',error.code??'renewal-unavailable');}
 }
 for(const signal of ['SIGTERM','SIGINT'])process.on(signal,()=>void stop());
+// Windows delivers no SIGTERM to a handler: a successor or a disconnect asks this runner to stop through its stop file.
+setInterval(()=>{try{if(JSON.parse(readFileSync(stopFile,'utf8')).pid===process.pid)void stop();}catch{}},500).unref();
 for(const grant of record.grants)start(grant);
 let lastRenew=0;
 // Teams verifies the Workplace's tokens against its own JWKS (ADR 0070): nothing is relayed for them here.
@@ -115,4 +149,4 @@ while(!stopped){
   }catch(error){issue('issuer',error.code??error.status??'connection-unavailable');await syncAlerts();}
   await new Promise(done=>setTimeout(done,2000));
 }
-async function stop(){if(stopped)return;stopped=true;await Promise.all([...children.keys()].map(stopChild));record.stoppedAt=new Date().toISOString();save();unlinkSync(lock);process.exit(0);}
+async function stop(){if(stopped)return;stopped=true;await Promise.all([...children.keys()].map(stopChild));record.stoppedAt=new Date().toISOString();save();unlinkSync(lock);rmSync(stopFile,{force:true});process.exit(0);}

package/bin/orchestrator.mjs

@@ -45,8 +45,8 @@ 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','alert-role','webhook-url','webhook-listen'].map(key=>[key,{type:'string'}]));
-  options['no-start']={type:'boolean'};options.registrations={type:'boolean'};
+  const options=Object.fromEntries(['root','ticket-file','modules-root','source','context','teams-token-file','teams-url','team','alert-role','webhook-url','webhook-listen','adopt'].map(key=>[key,{type:'string'}]));
+  options['no-start']={type:'boolean'};options.registrations={type:'boolean'};options['adopt-module']={type:'string',multiple:true};options['adopt-program']={type:'string',multiple:true};
   try{
     const {values}=parseArgs({args:process.argv.slice(3),options});
     if(values.registrations)process.stdout.write(`${SERVICE_REGISTRATIONS}\n`);
@@ -56,7 +56,7 @@ if (process.argv[2] === 'workflow') {
 } else if (process.argv[2] === 'disconnect') {
   const {parseArgs}=await import('node:util');
   const {disconnectWorkplace}=await import('../connection.mjs');
-  try{const {values}=parseArgs({args:process.argv.slice(3),options:{root:{type:'string'},connection:{type:'string'}}});process.stdout.write(JSON.stringify(await disconnectWorkplace(values),null,2)+'\n');}
+  try{const {values}=parseArgs({args:process.argv.slice(3),options:{root:{type:'string'},connection:{type:'string'},'uninstall-adopted':{type:'boolean'}}});process.stdout.write(JSON.stringify(await disconnectWorkplace(values),null,2)+'\n');}
   catch(error){process.stderr.write(`disconnect: ${error.message}\n`);process.exitCode=1;}
 } else if (process.argv[2] === 'mcp-server') {
   // a session's orchestrator tools on stdio, bound by its environment (mcp/mount.mjs mounts this through the stable

package/bin/runtime.mjs

@@ -837,13 +837,18 @@ async function main() {
   process.on('SIGINT', () => { void stop('SIGINT'); void finish(); });
   try {
     starting = (async () => {
+      // The control door answers for this incarnation's lease, never for its
+      // platforms: it binds before any adapter connects, so a platform's slow
+      // reads (rh2's sequential Room views take seconds) cannot outlast the
+      // caller's startup confirmation and get a live daemon killed. A stop it
+      // admits still joins `starting` before quiescing anything.
+      control = await startDaemonControl({ root, lease: daemonLease, stop, complete: () => { void finish(); } });
       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; }

package/board/agent-declarations.mjs

@@ -78,7 +78,7 @@ export function recordCardAgentChanges(board,target){
   acknowledgeCardAgentChanges(board.root,changes.map(change=>change.receipt));
 }
 
-/** Mirror a retained assignment (including reviewer roles created on the launch/adoption path) once per state. */
+/** Mirror a retained assignment (including reviewer roles created on the launch path) once per state. */
 export function recordCardAgentAssignment(board,assignment){
   if(!assignment)return;
   recordCardAgentChanges(board,assignment.target);

package/board/args.mjs

@@ -3,7 +3,7 @@ import { resolve } from 'node:path';
 
 export const MULTI = new Set(['parent', 'skill', 'worker', 'child', 'ids', 'rm', 'tag', 'pr', 'pr-head', 'reviewed-sha', 'finding', 'source']);
 export const FLAGS = new Set(['json', 'triage', 'no-notify', 'no-start', 'all', 'force', 'help', 'mine', 'archived', 'subtasks', 'reclaim', 'dry-run',
-  'once', 'goal', 'no-goal', 'off', 'switch', 'delete', 'no-attachments', 'include-logs', 'verbose', 'side']);
+  'once', 'goal', 'no-goal', 'off', 'switch', 'delete', 'no-attachments', 'include-logs', 'verbose', 'side', 'plan']);
 // flags that take every following word up to the next flag (Hermes's nargs='+')
 export const GREEDY = new Set(['ids', 'rm']);
 
@@ -11,6 +11,13 @@ export function parse(argv) {
   const out = { _: [] };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
+    // One word holding flags (a shell variable the shell did not split: zsh's `$args`, or a quoted "--pr URL --pr-head
+    // SHA") is refused, never read as text or as a flag named by the whole word: VO-3760's five `--pr` declarations
+    // reached the board as one word " --pr … --pr-head …" that a comment stored as its text (and `--file` dropped),
+    // so its review was requested without two of its PRs.
+    if (/^\s+--[A-Za-z]/.test(a) || (a.startsWith('--') && /\s/.test(a.slice(2).split('=')[0]))) {
+      throw new Error(`One argument holds flags and their values together: ${JSON.stringify(a.length > 120 ? `${a.slice(0, 117)}...` : a)}. Pass each flag and each value as its own word (a shell variable holding several is split with \${=args} in zsh, or built as an array: "\${args[@]}" in bash). Nothing was done.`);
+    }
     if (!a.startsWith('--') || a === '--') { out._.push(a); continue; }
     const [key, inline] = a.slice(2).split(/=(.*)/s);
     // init toggles document commits; completion/review names a git revision.

package/board/call.mjs

@@ -35,8 +35,8 @@ 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 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)));
+export function ownCall(fn, name = fn.name || 'own work') {
+  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)), name);
 }
 
 /** The caller as its address names it, or null. */