@volter/supercode-orchestrator 0.5.228 → 0.5.229

package/README.md

@@ -19,6 +19,17 @@ stage's own transition, which ends the run in the default workflow. See the
 [private manual reading](../../docs/evidence/board-manual-claim-2026-10-09.md)
 for scope and limits; existing inconsistent claims are not repaired automatically.
 
+The candidate board supports manager-set pause deadlines and an independent
+backlog flag. `workflow pause CARD --reason "why" --until 2h` stops its attempt;
+another pause changes the deadline without ending a second run. Manual resume
+or expiry takes the same `resume` transition and retains its conversation.
+`workflow backlog CARD --reason "why"` accepts settled work for later;
+`workflow plan CARD` returns it to Todo for ordinary capacity admission.
+Backlog blocks every start and holds no execution capacity. Existing homes need
+compatible rules and storage before adoption. The
+[resting-state contract](../../docs/reference/board-resting-states.md) covers
+authority, migration revisions, remaining holds and deliberate replacement.
+
 Completing a task with `--commit` inherits its arc's workspace when the task is
 scratch. When that workspace belongs to another machine, the board verifies the
 commit against the declared repository's pushed branch head through GitHub,
@@ -81,7 +92,9 @@ Other SDK callers that persist runtime state set `preserve_workflow: true` on
 `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. 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
+rolls back to a fresh generation started from the predecessor's selection, so the parked predecessor is ended
+(TERM, then KILL) once the successor's first round is clean, and each end is said in the owner's log; one that does not
+exit is named in `board-generation.json` and the owner's status until it does. 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).
 
@@ -113,7 +126,10 @@ supercode workflow attachment-get <card> <attachment-id> --at sc:<host>:board:<n
 The npm front door serves `attachment-get`. Without `--at`, use `--root <home>`
 and optionally `--board <slug>`. `--out` names a local file; its parent directory
 must exist. A completed download replaces that file. An interrupted download
-retains a separate partial file and reports its path; there is no automatic resume.
+keeps every byte it received in a partial file beside `--out` (named for the
+output, card, attachment and version) and reports its path; running the same
+command again continues from that partial's end, as long as the attachment's
+version is unchanged.
 The board host needs an orchestrator that serves `attachment-read` and its normal
 running board owner. Remote reads keep the board door's caller and grant checks.
 

package/activation.mjs

@@ -81,7 +81,7 @@ export function declareWorkerHome({ harness, env, cwd, log = () => {} }) {
  * person's `--add-root` makes, on a root that covers that one folder and nothing under it (`exact_only`: the connector
  * captures a session only when its recorded folder is that folder, after realpath). A worker's session is recorded in the
  * folder it was started in, so the exact root captures it, and no subfolder is published by it. Whether a root covers
- * the folder is the CLI's own rule (`teams roots --cwd`: rootCovers in roots.mjs, as `agent launch --status` reads it).
+ * the folder is the CLI's own rule (`teams roots --cwd`: rootCovers in root-path.mjs, as `agent launch --status` reads it).
  *
  * A folder a root already covers (one a person connected by hand, wherever it is) is captured, and nothing more is done.
  * Otherwise one folder is still every session recorded in it, so only a folder the orchestrator owns is connected: one

package/adapters/agent-mailbox.mjs

@@ -1,3 +1,5 @@
+import { registerWorkOperations, measureWork } from "@volter/supercode-harness-sdk/work-ledger";
+registerWorkOperations([{"kind":"pass","operation":"channel.inbound"},{"kind":"pass","operation":"channel.poll"}]);
 // A channel carried to an agent's one mailbox (docs/adr/0008-agent-mailbox.md, decisions 15 and 16).
 //
 // Any channel adapter (connect(emit) / send(target, content)) is the transport. Each line a person posts is filed as
@@ -64,6 +66,7 @@ export class AgentMailboxBridge {
 
   /** One line from the channel, filed as mail to the agent. */
   async inbound(event) {
+    return measureWork("pass", "channel.inbound", async () => {
     if (event.is_me || !event.message_id) return;
     const marker = `${this.platform}:${event.message_id}`;
     const result = await this.client.messageSession({ harness: 'agent', session_id: this.agent }, event.text, {
@@ -87,6 +90,9 @@ export class AgentMailboxBridge {
       this.threads.set(thread, { chat_id: event.key.chat_id, root: event.key.thread_id ?? event.message_id });
       this.save();
     }
+
+
+    });
   }
 
   /** The mailbox marker a line replies to, or none for a root. */
@@ -98,6 +104,7 @@ export class AgentMailboxBridge {
 
   /** The agent's answers, filed in this bridge's mailbox, posted in their threads. */
   async pollAnswers() {
+    return measureWork("pass", "channel.poll", async () => {
     while (this.running) {
       try {
         const inbox = await this.client.sessionInbox({ fromName: this.fromName });
@@ -120,5 +127,8 @@ export class AgentMailboxBridge {
       }
       await this.sleep(this.pollMs);
     }
+
+
+    });
   }
 }

package/adapters/api-server.mjs

@@ -1,3 +1,5 @@
+import { registerWorkOperations, measureWork } from "@volter/supercode-harness-sdk/work-ledger";
+registerWorkOperations([{"kind":"door","operation":"gateway.http"}]);
 // The `api_server`-compatible HTTP surface (ORC-9): Hermes's own client API,
 // served by this loop, behind the same three-method adapter trait
 // (`connect(emit)` / `send(target, content)` / `close()`).
@@ -314,6 +316,7 @@ export class ApiServerAdapter {
   }
 
   async route(req, res) {
+    return measureWork("door", "gateway.http", async () => {
     const url = new URL(req.url ?? '/', 'http://localhost');
     const path = url.pathname;
     const method = (req.method ?? 'GET').toUpperCase();
@@ -577,6 +580,9 @@ export class ApiServerAdapter {
     }
 
     return send(404, errorBody(`Unknown route: ${method} ${path}`, 'not_found'));
+
+
+    });
   }
 
   /** `_session_response`'s client-safe projection (`api_server.py:4283-4302`). */

package/agents.mjs

@@ -1,18 +1,52 @@
 // Teams identity, orchestrator intent and assignments: one boundary, joined by the immutable agent id.
 import { DatabaseSync } from 'node:sqlite';
-import { mkdirSync, existsSync } from 'node:fs';
+import { mkdirSync, existsSync, statSync } from 'node:fs';
 import { join, basename } from 'node:path';
 import { createHash, randomBytes } from 'node:crypto';
+import { setImmediate as yieldToOwner } from 'node:timers/promises';
 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';
+import { listRevision } from './board/listing.mjs';
 // 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';
+// The agent store, held open once per file for the process. A board's delivery pass reads and records every run and
+// card assignment the home ever had (synchronizeAgents, about 600 runs and 400 assignments on volter-org); opening the
+// file for each call, with its schema script, its column check and its cleanup on every open, and closing it (the last
+// close checkpoints and removes the WAL) held the board worker 32229 at about half a core on yuerans-macbook-pro
+// (2026-10-28: synchronizeAgents 56% of its busy time, its opens, schema runs and closes the most of that).
+// Callers keep their open/close shape: the connection handed out ignores close(). Every transaction here is opened and
+// committed or rolled back in one synchronous stretch, so no two callers interleave inside one; a connection left in a
+// transaction by a caller that threw before its rollback is rolled back before it is handed out again. A file replaced
+// or removed underneath (another inode) is opened again.
+const heldStores=new Map();
+function heldStore(path,open,key=path){
+  let held=heldStores.get(key),inode=null;
+  try{inode=statSync(path).ino;}catch{inode=null;}
+  if(held&&(inode===null||held.inode!==inode)){heldStores.delete(key);try{held.db.close();}catch{/* already gone */}held=null;}
+  if(!held){
+    const db=open();
+    const statements=new Map();
+    held={db,inode:statSync(path).ino,handle:{
+      connection: db,
+      prepare:sql=>{let statement=statements.get(sql);if(!statement){statement=db.prepare(sql);statements.set(sql,statement);}return statement;},
+      exec:sql=>db.exec(sql),
+      close(){/* held for the process */},
+      get isTransaction(){return db.isTransaction;},
+    }};
+    heldStores.set(key,held);
+  }
+  if(held.db.isTransaction)held.db.exec('ROLLBACK');
+  return held.handle;
+}
 function store(root){
-  mkdirSync(root,{recursive:true,mode:0o700});const db=new DatabaseSync(join(root,'agent-state.sqlite'));
+  const path=join(root,'agent-state.sqlite');
+  return heldStore(path,()=>{
+    mkdirSync(root,{recursive:true,mode:0o700});const db=new DatabaseSync(path);
+  try{
   db.exec(`PRAGMA busy_timeout=5000; PRAGMA journal_mode=WAL;
   CREATE TABLE IF NOT EXISTS agent_intents(org TEXT NOT NULL,id TEXT NOT NULL,key TEXT NOT NULL,profile_ref TEXT NOT NULL,profile_json TEXT NOT NULL,declared INTEGER NOT NULL DEFAULT 0,declaration_json TEXT,created_at INTEGER NOT NULL,PRIMARY KEY(org,id),UNIQUE(org,key));
   CREATE TABLE IF NOT EXISTS agent_declaration_heads(org TEXT NOT NULL,key TEXT NOT NULL,agent_id TEXT NOT NULL,generation INTEGER NOT NULL DEFAULT 0,PRIMARY KEY(org,key));
@@ -29,8 +63,49 @@ function store(root){
   const columns=new Set(db.prepare('PRAGMA table_info(agent_runs)').all().map(row=>row.name));
   if(!columns.has('conversation'))db.exec('ALTER TABLE agent_runs ADD COLUMN conversation INTEGER NOT NULL DEFAULT 0');
   if(!columns.has('started_at'))db.exec('ALTER TABLE agent_runs ADD COLUMN started_at INTEGER NOT NULL DEFAULT 0');
+  db.exec(`CREATE INDEX IF NOT EXISTS agent_runs_session ON agent_runs(session_ref);
+    CREATE INDEX IF NOT EXISTS agent_runs_open ON agent_runs(org,session_ref) WHERE ended_at IS NULL;
+    CREATE INDEX IF NOT EXISTS agent_runtime_ref ON agent_runtime_sessions(runtime_ref);
+    CREATE INDEX IF NOT EXISTS agent_runs_owner ON agent_runs(org,agent_id);
+    CREATE INDEX IF NOT EXISTS agent_runs_usage_pending ON agent_runs(org) WHERE usage_json IS NULL;`);
+  trackAgentRecords(db);
   db.prepare('DELETE FROM agent_card_assignment_changes WHERE recorded=1').run();
-  return db;
+  }catch(error){try{db.close();}catch{/* the open failed */}throw error;}
+    return db;
+  });
+}
+// The delivery pass observes changed ownership/binding facts as well as board runs. No durable
+// queue is added: a restart reseeds from authoritative rows; failed work stays in its pending set.
+const agentRecords = new WeakMap();
+function trackAgentRecords(db) {
+  const state = { epoch: 0, floor: 0, sessions: new Map(), targets: new Map() };
+  agentRecords.set(db, state);
+  db.function('supercode_agent_changed', (kind, key) => {
+    if (key == null) return;
+    const map = state[kind], epoch = ++state.epoch;
+    map.delete(key); map.set(key, epoch);
+    if (map.size > 4096) { const first = map.keys().next().value; state.floor = Math.max(state.floor,map.get(first)); map.delete(first); }
+  });
+  for (const [table,column,kind] of [['agent_runs','session_ref','sessions'], ['agent_runtime_sessions','runtime_ref','sessions'],
+    ['agent_assignments','target','targets'], ['agent_card_scope_transitions','target','targets'], ['agent_card_assignment_changes','target','targets']]) {
+    for (const [verb,rows] of [['INSERT',['NEW']],['UPDATE',['OLD','NEW']],['DELETE',['OLD']]]) {
+      const body = rows.map(row => `SELECT supercode_agent_changed('${kind}',${row}.${column});`).join(' ');
+      db.exec(`CREATE TEMP TRIGGER supercode_agent_${table}_${verb.toLowerCase()} AFTER ${verb} ON main.${table} BEGIN ${body} END`);
+    }
+  }
+  for (const [verb,rows] of [['INSERT',['NEW']],['UPDATE',['OLD','NEW']],['DELETE',['OLD']]]) {
+    const body = rows.map(row => `SELECT supercode_agent_changed('targets',target) FROM agent_assignments WHERE org=${row}.org AND agent_id=${row}.id;`).join(' ');
+    db.exec(`CREATE TEMP TRIGGER supercode_agent_intents_${verb.toLowerCase()} AFTER ${verb} ON main.agent_intents BEGIN ${body} END`);
+  }
+}
+/** Changed local agent records, with foreign commits/replaced stores treated as unknown. */
+export function agentRecordChanges(root, previous = null) {
+  const db = store(root), connection = db.connection, state = agentRecords.get(connection), revision = listRevision(connection);
+  const token = { ...revision, epoch: state.epoch };
+  const reset = !previous || previous.connection !== token.connection || previous.data !== token.data
+    || previous.mainSchema !== token.mainSchema || previous.tempSchema !== token.tempSchema || previous.epoch < state.floor;
+  const changed = map => reset ? null : previous.epoch === state.epoch ? [] : [...map].filter(([,epoch]) => epoch > previous.epoch).map(([key]) => key);
+  return { token, reset, sessions: changed(state.sessions), targets: changed(state.targets) };
 }
 const digest=value=>createHash('sha256').update(value).digest('hex');
 const minted=async(key,machine)=>{
@@ -43,12 +118,14 @@ const minted=async(key,machine)=>{
 };
 export function agentIntent(root,org,id){const db=store(root);try{const row=db.prepare('SELECT * FROM agent_intents WHERE org=? AND id=?').get(org,id);return row?{...row,profile:JSON.parse(row.profile_json),assignments:db.prepare("SELECT * FROM agent_assignments WHERE org=? AND agent_id=? AND state='active'").all(org,id)}:null;}finally{db.close();}}
 /** Ownership moves and their board obligation commit together in the assignment owner's store. */
-function retainCardAgentChange(db,old,to,profile){
+function retainCardAgentChange(db,old,to,profile,decision=null){
   if(old?.kind!=='card'||old.agent_id===to)return;
   const fromProfile=db.prepare('SELECT profile_ref FROM agent_intents WHERE org=? AND id=?').get(old.org,old.agent_id)?.profile_ref??null;
-  db.prepare('INSERT INTO agent_card_assignment_changes(target,payload) VALUES (?,?)').run(old.target,JSON.stringify({org:old.org,assignment:old.id,role:old.role,from:old.agent_id,to,profile:profile??null,from_profile:fromProfile,changed_at:Date.now()}));
+  db.prepare('INSERT INTO agent_card_assignment_changes(target,payload) VALUES (?,?)').run(old.target,JSON.stringify({org:old.org,assignment:old.id,role:old.role,from:old.agent_id,to,profile:profile??null,from_profile:fromProfile,changed_at:Date.now(),...(decision?{decision}: {})}));
 }
-export function assignAgent(root,org,id,{kind,target,role}){
+/** A card role's one assignment, keyed by the card and its role: the only record that names the role's agent. */
+export const cardRoleAssignment=(card,role)=>digest(JSON.stringify(['card',card,role]));
+export function assignAgent(root,org,id,{kind,target,role},{existingAgent=null}={}){
   const db=store(root),key=digest(JSON.stringify([kind,target,role]));try{
     db.exec('BEGIN IMMEDIATE');
     if(kind==='card'&&org==='local'&&db.prepare('SELECT 1 FROM agent_card_scope_transitions WHERE target=?').get(target)){
@@ -56,6 +133,8 @@ export function assignAgent(root,org,id,{kind,target,role}){
       throw Object.assign(new Error('card agent scope was adopted; local declarations are refused'),{code:'card_scope_adopted'});
     }
     const old=db.prepare('SELECT * FROM agent_assignments WHERE org=? AND id=?').get(org,key);
+    if(existingAgent&&old?.agent_id!==existingAgent)
+      throw Object.assign(new Error(`the established ${role} assignment changed before binding ${existingAgent}`),{continuationRequired:true});
     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());
     const profile=db.prepare('SELECT profile_ref FROM agent_intents WHERE org=? AND id=?').get(org,id)?.profile_ref;
     retainCardAgentChange(db,old,id,profile);
@@ -68,20 +147,21 @@ export function cardAgentAssignments(root,target=null){const db=store(root);try{
 /** Adoption remains authoritative after its delivery receipt is acknowledged. One read pins scope and native state. */
 export function cardAgentScopeTransition(root,target){
   const path=join(root,'agent-state.sqlite');if(!existsSync(path))return null;
-  const db=new DatabaseSync(path,{readOnly:true});
+  // read-only, held as the store is (store above); its read transaction ends with each call
+  const db=heldStore(path,()=>{const db=new DatabaseSync(path,{readOnly:true});try{db.exec('PRAGMA busy_timeout=5000');}catch(error){db.close();throw error;}return db;},`${path}\0read-only`);
   try{
-    db.exec('PRAGMA busy_timeout=5000; BEGIN');
+    db.exec('BEGIN');
     if(!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='agent_card_scope_transitions'").get())return null;
     const transition=db.prepare('SELECT from_org,to_org AS org,changed_at FROM agent_card_scope_transitions WHERE target=?').get(target);
     if(!transition)return null;
     const assignments=db.prepare("SELECT a.*,i.profile_ref AS profile FROM agent_assignments a LEFT JOIN agent_intents i ON i.org=a.org AND i.id=a.agent_id WHERE a.kind='card' AND a.target=? AND a.org=? ORDER BY a.role,a.id").all(target,transition.org);
     return {...transition,assignments};
-  }finally{db.close();}
+  }finally{if(db.isTransaction)db.exec('COMMIT');}
 }
 /** A board consumes these in receipt order before mirroring the assignment's present owner or end. */
 export function pendingCardAgentChanges(root,target){const db=store(root);try{return db.prepare('SELECT sequence,payload FROM agent_card_assignment_changes WHERE recorded=0 AND target=? ORDER BY sequence').all(target).map(row=>({receipt:Number(row.sequence),...JSON.parse(row.payload)}));}finally{db.close();}}
 /** The board committed facts and dedupe watermark before acknowledging; only pending receipts remain here. */
-export function acknowledgeCardAgentChanges(root,receipts){const db=store(root);try{
+export function acknowledgeCardAgentChanges(root,receipts){if(!receipts.length)return;const db=store(root);try{
   db.exec('BEGIN IMMEDIATE');
   for(const receipt of receipts)db.prepare('DELETE FROM agent_card_assignment_changes WHERE sequence=?').run(receipt);
   db.exec('COMMIT');
@@ -96,7 +176,7 @@ export async function reassignAgent(root,org,assignment,to,{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');
-    retainCardAgentChange(db,old,to,target.profile);
+    retainCardAgentChange(db,old,to,target.profile,{kind:'reassign_agent',from:old.agent_id,to});
     db.prepare('DELETE FROM agent_end_outbox WHERE org=? AND agent_id=?').run(org,to);
     if(old.agent_id!==to&&!db.prepare("SELECT 1 FROM agent_assignments WHERE org=? AND agent_id=? AND state='active'").get(org,old.agent_id))
       db.prepare('INSERT OR IGNORE INTO agent_end_outbox(org,agent_id,reason,created_at) VALUES (?,?,?,?)').run(org,old.agent_id,`last assignment reassigned to ${to}`,Date.now());
@@ -160,7 +240,7 @@ export function agentRunForKey(root,org,agent,key) {
   const db=store(root);try{return db.prepare('SELECT * FROM agent_runs WHERE org=? AND agent_id=? AND run_id=? ORDER BY rowid DESC LIMIT 1').get(org,agent,key)??null;}finally{db.close();}
 }
 const declarationHead=(root,org,key)=>{const db=store(root);try{return db.prepare('SELECT agent_id FROM agent_declaration_heads WHERE org=? AND key=?').get(org,key)?.agent_id??null;}finally{db.close();}};
-const endedHere=(root,org,id)=>{const db=store(root);try{return !!db.prepare('SELECT 1 FROM agent_runs WHERE org=? AND agent_id=? AND end_reason IS NOT NULL LIMIT 1').get(org,id);}finally{db.close();}};
+export const endedHere=(root,org,id)=>{const db=store(root);try{return !!db.prepare('SELECT 1 FROM agent_runs WHERE org=? AND agent_id=? AND end_reason IS NOT NULL LIMIT 1').get(org,id);}finally{db.close();}};
 function recordDeclaration(root,org,id,declaration){
   const db=store(root);try{db.prepare('UPDATE agent_intents SET declaration_json=?,declared=0 WHERE org=? AND id=? AND declaration_json IS NOT ?').run(JSON.stringify(declaration),org,id,JSON.stringify(declaration));}finally{db.close();}
 }
@@ -173,6 +253,8 @@ async function localAgent(options,{key,name,declaration,assignment,parent=null,s
   const rootIntent=await declareAgentIntent({root,org,server,profiles,profile:rootProfile,key:'root',machine,refresh:false});
   recordDeclaration(root,org,rootIntent.id,{kind:'root',profile:rootProfile,name:basename(root),parent:null});
   let intent=key==='root'?rootIntent:await declareAgentIntent({root,org,server,profiles,profile,key,machine});
+  if(options.existingAgent&&(intent.id!==options.existingAgent||endedHere(root,org,intent.id)))
+    throw Object.assign(new Error(`established role belongs to ${options.existingAgent}; no successor identity was authorized`), { continuationRequired: true });
   // An agent ended here is never started again: its end is on its runs here (handOffAgents), and the key's next generation
   // is minted in its place, with fresh memory.
   if(key!=='root'&&endedHere(root,org,intent.id))intent=await nextAgentGeneration(root,intent,machine);
@@ -183,7 +265,7 @@ async function localAgent(options,{key,name,declaration,assignment,parent=null,s
   const identity={id:intent.id,kind:'agent',org,name,path:above?`${above.path}/${name}`:name,parent:above?.id??null,
     lineage:{starter},profile,state:'active',
     synced:!!intent.declared,main_session:null,revision:0};
-  const assigned=assignAgent(root,org,intent.id,assignment);
+  const assigned=assignAgent(root,org,intent.id,assignment,{existingAgent:options.existingAgent});
   return {identity,intended:intent.intended,assignment:assigned,assignments:[assignment],org,synced:false};
 }
 export async function localCardAgent(options){
@@ -194,7 +276,17 @@ export async function localCardAgent(options){
   }
   // A card role's assignment the manager moved to another agent (`workflow reassign --agent`) runs as that agent: the
   // active assignment names it, not the key's own head, and an agent whose end was synchronized here is not used.
-  const held=activeAgentAssignments(root).find(item=>item.org===org&&item.kind==='card'&&item.target===card&&item.role===role);
+  const held=activeAgentAssignments(root).find(item=>item.org===org&&item.id===cardRoleAssignment(card,role));
+  // Check before localAgent can mint the stable key or advance an ended identity's generation. Reopening a card
+  // or observing an ownership mismatch is not a deliberate new-session decision (ADR 0248).
+  if(options.existingAgent){
+    const head=held?.agent_id??declarationHead(root,org,`${server}/${org}/card/${card}/${role}`);
+    // The refusal names the deliberate doors for this failing role (ADR 0248): a reassignment names its role, so the
+    // advice never reaches another role's slot.
+    const ended=endedHere(root,org,options.existingAgent);
+    if(head!==options.existingAgent||ended)
+      throw Object.assign(new Error(`established ${role} conversation belongs to ${options.existingAgent}${ended?', which has ended':''}; a successor starts only on a deliberate manager or owner decision (ADR 0248): \`supercode workflow replace-session ${card} --reason "<why>"\` authorizes the role's next agent generation, or \`supercode workflow reassign ${card} --agent AGENT --role ${role}\` hands it to another`), { continuationRequired: true });
+  }
   if(held&&held.agent_id!==declarationHead(root,org,`${server}/${org}/card/${card}/${role}`)&&!endedHere(root,org,held.agent_id)){
     const record=localAgentRecord(root,org,held.agent_id);
     const identity=record?{...record.identity,synced:true}:{id:held.agent_id,kind:'agent',org,name:held.agent_id,path:held.agent_id,parent:null,
@@ -208,10 +300,9 @@ export async function localCardAgent(options){
     starter:options.starterSession?{kind:'session',id:options.starterSession}:{kind:'automation',id:`board:${basename(options.root)}`}});
 }
 export async function localProfileAgent(options){
-  const {root,profiles,profile,agent:declared=null,declarations={}}=options,rootProfile=profiles.default?'default':profile;
+  const {root,profiles,profile,agent:declared=null}=options,rootProfile=profiles.default?'default':profile;
   const starter={kind:'automation',id:`orchestrator:${basename(root)}`};
   if(declared&&declared!==profile){
-    const decl=declarations[declared]??{};
     return localAgent(options,{key:`agent/${declared}`,name:declared,assignment:{kind:'agent',target:declared,role:'declared'},
       declaration:{kind:'declared',agent:declared,profile},starter});
   }
@@ -266,30 +357,38 @@ export function homeAgentId(root,{org,server,name,profile=name}){
 export function localAgentSessions(root,org,id){
   const db=store(root);try{return db.prepare('SELECT session_ref AS session,machine,ended_at,end_reason FROM agent_runs WHERE org=? AND agent_id=? ORDER BY rowid DESC LIMIT 200').all(org,id);}finally{db.close();}
 }
-/** Retained starter receipts for this home's sessions, including explicit forks.
- * Ended owners remain in the join so a live child keeps its original starter. */
-export function localSessionDelegations(root, localMachine) {
-  const db = store(root);
-  try {
-    const rows = db.prepare(`SELECT r.*, json_extract(i.declaration_json,'$.starterSession') AS declared_starter
-      FROM agent_runs r LEFT JOIN agent_intents i ON i.org=r.org AND i.id=r.agent_id`).all();
-    const addresses = new Map();
-    const address = row => row.session_ref.startsWith('sc:') ? row.session_ref
-      : /^(claude-code|codex):[^:]+$/.test(row.session_ref) ? `sc:${row.machine ?? localMachine}:${row.session_ref}` : null;
-    for (const row of rows) {
-      const key = `${row.org}|${row.session_ref}`, value = address(row);
-      if (value) addresses.set(key, value);
+/** Live children and the exact retained starter receipts they name, including ended starters. */
+export async function localSessionDelegations(root, localMachine, keepReading) {
+  const address = row => row?.session_ref.startsWith('sc:') ? row.session_ref
+    : /^(claude-code|codex):[^:]+$/.test(row?.session_ref) ? `sc:${row.machine ?? localMachine}:${row.session_ref}` : null;
+  const edges = [];
+  let after = null;
+  while (keepReading()) {
+    const db = store(root);
+    const rows = db.prepare(`SELECT org,session_ref FROM agent_runs WHERE ended_at IS NULL
+      ${after ? 'AND (org,session_ref)>(?,?)' : ''} ORDER BY org,session_ref LIMIT 64`).all(...(after ?? []));
+    if (!rows.length) break;
+    after = [rows.at(-1).org, rows.at(-1).session_ref];
+    for (const key of rows) {
+      await yieldToOwner();
+      if (!keepReading()) return edges;
+      const current = store(root);
+      const row = current.prepare(`SELECT r.org,r.session_ref,r.machine,r.starter_session,
+        json_extract(i.declaration_json,'$.starterSession') AS declared_starter
+        FROM agent_runs r LEFT JOIN agent_intents i ON i.org=r.org AND i.id=r.agent_id
+        WHERE r.org=? AND r.session_ref=? AND r.ended_at IS NULL`).get(key.org, key.session_ref);
+      if (!row) continue;
+      const session = address(row), ref = row.starter_session ?? row.declared_starter;
+      if (!session || typeof ref !== 'string') continue;
+      const alias = ref.startsWith('sc:') ? null : current.prepare(`SELECT r.session_ref,r.machine
+        FROM agent_runtime_sessions a JOIN agent_runs r ON r.org=a.org AND r.session_ref=a.session_ref
+        WHERE a.org=? AND a.runtime_ref=?`).get(row.org, ref);
+      const starter = ref.startsWith('sc:') ? ref : address(alias)
+        ?? address(current.prepare('SELECT session_ref,machine FROM agent_runs WHERE org=? AND session_ref=?').get(row.org, ref));
+      if (starter) edges.push({ session, starter });
     }
-    for (const alias of db.prepare('SELECT * FROM agent_runtime_sessions').all()) {
-      const value = addresses.get(`${alias.org}|${alias.session_ref}`);
-      if (value) addresses.set(`${alias.org}|${alias.runtime_ref}`, value);
-    }
-    return rows.filter(row => row.ended_at == null).map(row => {
-      const ref = row.starter_session ?? row.declared_starter;
-      return { session: address(row), starter: typeof ref === 'string' && ref.startsWith('sc:')
-        ? ref : addresses.get(`${row.org}|${ref}`) ?? null };
-    }).filter(edge => edge.session && edge.starter);
-  } finally { db.close(); }
+  }
+  return edges;
 }
 /** Move identities minted before any Teams context into the Org that is now selected, keeping their ids. */
 function adoptLocalOrg(root,scope){
@@ -428,7 +527,15 @@ export function recordNativeAgentSession(root,runtimeRef,session) {
   return agentRunForSession(root,[runtimeRef]);
 }
 export function recordAgentRun(root,org,id,{session,machine=null,run,profile=null,main=true,starterSession=null,conversation=false}){
-  const db=store(root);try{
+  const db=store(root);
+  // A run already recorded as it is now writes nothing: the delivery pass records every run each pass, and a write
+  // transaction for each unchanged one committed hundreds of WAL frames a pass.
+  const now=db.prepare('SELECT agent_id,machine,run_id,profile_json,main,starter_session,conversation,started_at FROM agent_runs WHERE org=? AND session_ref=?').get(org,session);
+  if(now&&now.agent_id!==id)throw new Error('local session ownership cannot change agent identity');
+  const profileJson=profile?JSON.stringify(profile):null;
+  if(now&&now.machine===machine&&now.run_id===String(run)&&(profileJson===null||now.profile_json===profileJson)&&now.main===(main?1:0)
+    &&!(now.starter_session===null&&starterSession!==null)&&now.conversation===(conversation?1:0)&&now.started_at!==0)return;
+  try{
     db.exec('BEGIN IMMEDIATE');
     const old=db.prepare('SELECT agent_id FROM agent_runs WHERE org=? AND session_ref=?').get(org,session);
     if(old&&old.agent_id!==id)throw new Error('local session ownership cannot change agent identity');
@@ -467,6 +574,8 @@ export function recordUsageUnread(root,org,session,stamp){
 export function runsAwaitingUsage(root,org){
   const db=store(root);try{return db.prepare('SELECT r.*,u.stamp AS usage_unread FROM agent_runs r LEFT JOIN agent_usage_unread u ON u.org=r.org AND u.session_ref=r.session_ref WHERE r.org=? AND r.usage_json IS NULL ORDER BY u.stamp IS NOT NULL,r.rowid LIMIT 50').all(org);}finally{db.close();}
 }
+/** Only organizations with outstanding usage, not every organization in historical runs. */
+export function pendingUsageOrgs(root){const db=store(root);try{return db.prepare('SELECT DISTINCT org FROM agent_runs WHERE usage_json IS NULL').all().map(row=>row.org);}finally{db.close();}}
 /** Usage records per agent id: every session this home ran for it. */
 export function agentUsage(root){
   const db=store(root),by=new Map();

package/apply/doors.mjs

@@ -1,3 +1,5 @@
+import { measureSyncChild } from '@volter/supercode-harness-sdk/work-ledger';
+const spawnSync = (...args) => measureSyncChild(() => workLedgerNativeSpawnSync(...args));
 // The applier's doors (docs/plans/content-spec-status.md §7 "The door"): every change goes through
 // the harness's own functions, never its files. One shape per gateway:
 //
@@ -13,7 +15,7 @@
 // or inside a container. The orchestrator: its operator verbs, through the running daemon's socket when it
 // is up and the package's cold path when it is not; its folder is read through the package's own `load`.
 
-import { spawnSync } from 'node:child_process';
+import { spawnSync as workLedgerNativeSpawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { createConnection } from 'node:net';
 import { dirname, join, resolve } from 'node:path';

package/bin/agent-channel.mjs

@@ -1,3 +1,4 @@
+import { registerWorkService, closeWorkLedger } from '@volter/supercode-harness-sdk/work-ledger';
 // `supercode-orchestrator agent-channel --agent <name> --platform slack|jira`: a channel carried to an agent's one mailbox
 // (docs/adr/0008-agent-mailbox.md) through the mailbox bridge (company RFC 0026 decision 3: an engagement's Slack
 // channel and its client's ticket comments are channels of its account manager):
@@ -10,6 +11,7 @@
 import { parseArgs } from 'node:util';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { supercodeHome } from '@volter/teams/home';
 import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
 import { AgentMailboxBridge } from '../adapters/agent-mailbox.mjs';
 import { JiraCommentsAdapter } from '../adapters/jira-comments.mjs';
@@ -23,8 +25,11 @@ if (values.help || !values.agent || !values.platform) {
   console.log('supercode-orchestrator agent-channel --agent <name> --platform slack --slack-channel <id>[,<id>] [--state <file>]\n       supercode-orchestrator agent-channel --agent <name> --platform jira --site <url> --jql <jql> [--state <file>]');
   process.exit(values.help ? 0 : 2);
 }
+registerWorkService({role:'agent-channel',scope:{kind:'install',id:`${values.agent}\0${values.platform}\0${process.env.SUPERCODE_ORCHESTRATOR_HOME ?? process.env.HERMES_HOME ?? homedir()}`}});
 const log = (level, line) => (level === 'debug' ? undefined : console.error(`${new Date().toISOString()} ${level} ${line}`));
-const statePath = (name) => values.state ?? join(homedir(), '.config', 'supercode', 'agent-channels', `${values.agent}.${name}.json`);
+// under this install's supercode home (SUPERCODE_HOME, else XDG_CONFIG_HOME/supercode, else ~/.config/supercode), as every
+// other supercode state is: a daemon run with its own home keeps its channels there
+const statePath = (name) => values.state ?? join(supercodeHome(), 'agent-channels', `${values.agent}.${name}.json`);
 let adapter;
 if (values.platform === 'jira') {
   if (!values.site || !values.jql) { console.error('agent-channel: --platform jira needs --site and --jql'); process.exit(2); }
@@ -50,6 +55,6 @@ const client = new SupercodeHarnessClient(process.env.SUPERCODE_BIN ? { command:
 const bridge = new AgentMailboxBridge({ adapter, client, agent: values.agent, platform: values.platform, fromName: `${values.platform}-${values.agent}`, log, statePath: statePath(values.platform) });
 await bridge.start();
 log('info', `${values.agent}: ${values.platform} is carried to its mailbox`);
-const stop = async () => { await bridge.stop(); await adapter.close?.(); await client.close?.(); process.exit(0); };
+const stop = async () => { await bridge.stop(); await adapter.close?.(); await client.close?.(); await closeWorkLedger(); process.exit(0); };
 process.on('SIGTERM', stop);
 process.on('SIGINT', stop);