@volter/supercode-orchestrator 0.4.160 → 0.5.1

package/board/engine.mjs

@@ -12,7 +12,7 @@ import { existsSync, rmSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { checkWorkspace, assertWorkspaceOwner, declareWorkspace, isLocalWorkspace } from './workspace.mjs';
 import { DatabaseSync } from 'node:sqlite';
-import { view, actorOf, claimer, event, json, newTaskId, now, tx } from './store.mjs';
+import { view, actorOf, principalOf, claimer, event, json, newTaskId, now, tx } from './store.mjs';
 import { completionPhase, inspectCompletionEvidence, observeCompletionEvidence, withCompletionEvidence } from './ci.mjs';
 import { addDependency, retireSupersededRuns, refreshCardInputs, requestSessionClose, eventTo, fire, loadWorkflow, setStatus, settle, startNew, statusOf, runEvent, workflowFor } from './workflow.mjs';
 
@@ -37,7 +37,8 @@ export function getTask(db, id) {
   const row = one(db, 'SELECT * FROM tasks WHERE id = ?', id);
   if (!row) return null;
   const ours = one(db, 'SELECT * FROM supercode_cards WHERE task_id = ?', id);
-  return { ...row, workspace_anchor: ours?.workspace_anchor ?? null, blocked_by: json(ours?.blocked_by, []) ?? [], paused: json(ours?.paused, null), archived: Boolean(ours?.archived), every: ours?.every ?? null, skills: json(row.skills, []) ?? [], machine: ours?.machine ?? null, subtask_of: ours?.subtask_of ?? null };
+  return { ...row, workspace_anchor: ours?.workspace_anchor ?? null, blocked_by: json(ours?.blocked_by, []) ?? [], paused: json(ours?.paused, null), archived: Boolean(ours?.archived), every: ours?.every ?? null, skills: json(row.skills, []) ?? [], machine: ours?.machine ?? null, subtask_of: ours?.subtask_of ?? null,
+    tags: json(ours?.tags, null) ?? (row.tenant ? [row.tenant] : []), sponsor: ours?.sponsor ?? null, sponsor_evidence: json(ours?.sponsor_evidence, null), requested_by_unverified: json(ours?.requested_by_unverified, null) };
 }
 
 function must(db, id) {
@@ -201,6 +202,10 @@ export function createCard(board, spec) {
   if (initial === 'running' && (spec.noStart || spec.adopt)) throw new Error('A held or awaiting-adoption card cannot be created initially running.');
   if (initial && !['blocked', 'running'].includes(initial)) throw new Error('initial status is blocked or running');
   if (spec.provider && !spec.model) throw new Error('a provider needs a model');
+  // Several ordered tags (C4); Hermes's single `tenant` is the first of them, as its export lowers them.
+  const tags = [...new Set([spec.tenant, ...(spec.tags ?? [])].filter((tag) => typeof tag === 'string' && tag.trim()).map((tag) => tag.trim()))];
+  // A sponsor is a person, never an agent or an automation (Teams refuses any principal that is not a person).
+  if (spec.sponsor && /^(agent_|svc_|service_)/.test(spec.sponsor)) throw new Error('a sponsor is a person; an agent or an automation cannot sponsor a card');
   return tx(board, (db) => {
     if (spec.idempotencyKey) {
       const got = one(db, "SELECT id FROM tasks WHERE idempotency_key = ? AND status != 'archived' ORDER BY created_at DESC LIMIT 1", spec.idempotencyKey);
@@ -238,18 +243,19 @@ export function createCard(board, spec) {
                tenant, idempotency_key, max_runtime_seconds, skills, max_retries, model_override, provider_override, reasoning_effort, session_id,
                project_id, goal_mode, goal_max_turns)
              VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-      id, title, spec.body ?? null, spec.assignee || null, 'todo', Number(spec.priority) || 0, actorOf() ?? spec.createdBy ?? 'user', t, ws.kind, ws.path,
-      spec.branch ?? null, spec.tenant ?? null, spec.idempotencyKey ?? null, spec.maxRuntime ?? null,
+      id, title, spec.body ?? null, spec.assignee || null, 'todo', Number(spec.priority) || 0, spec.createdBy ?? principalOf() ?? (actorOf() ? `session:${actorOf()}` : 'unidentified'), t, ws.kind, ws.path,
+      spec.branch ?? null, tags[0] ?? null, spec.idempotencyKey ?? null, spec.maxRuntime ?? null,
       spec.skills?.length ? JSON.stringify(spec.skills) : null, spec.maxRetries ?? null, spec.model ?? null, spec.provider ?? null,
       spec.reasoning ?? null, spec.sessionId ?? null, spec.project ?? null, spec.goal ? 1 : 0, spec.goal?.maxTurns ?? null);
     const machine = spec.machine ?? arc?.machine ?? null;
-    run(db, 'INSERT OR REPLACE INTO supercode_cards (task_id,machine,subtask_of,workspace_anchor,workspace_root) VALUES (?,?,?,?,?)', id, machine, arc?.id ?? null, declared.repository, checked?.mainRoot ?? null);
+    run(db, 'INSERT OR REPLACE INTO supercode_cards (task_id,machine,subtask_of,workspace_anchor,workspace_root,tags,sponsor,sponsor_evidence,requested_by_unverified) VALUES (?,?,?,?,?,?,?,?,?)', id, machine, arc?.id ?? null, declared.repository, checked?.mainRoot ?? null,
+      tags.length ? JSON.stringify(tags) : null, spec.sponsor ?? null, spec.sponsorEvidence ? JSON.stringify(spec.sponsorEvidence) : null, spec.requestedByUnverified ? JSON.stringify(spec.requestedByUnverified) : null);
     for (const p of parents) addDependency(db, entry, id, p);
     // where it starts is the workflow's `initial` (Hermes: triage, blocked, todo behind open parents, else ready)
     // the create's own words: whether it asked to be a goal card (null: the workflow decides), triage, its arc
     const status = startNew(db, board, entry, getTask(db, id), { triage: Boolean(spec.triage), initial_status: initial,
       every: spec.every ?? null, goal: spec.goal === undefined || spec.goal === null ? null : spec.goal !== false, subtask_of: arc?.id ?? null });
-    event(db, id, 'created', { creator: actorOf(), assignee: spec.assignee || null, status, parents, tenant: spec.tenant ?? null, ...(machine ? { machine } : {}), ...(arc ? { subtask_of: arc.id } : {}) });
+    event(db, id, 'created', { creator: actorOf(), created_by: one(db, 'SELECT created_by FROM tasks WHERE id=?', id)?.created_by ?? null, assignee: spec.assignee || null, status, parents, tags, ...(spec.sponsor ? { sponsor: spec.sponsor } : {}), ...(spec.requestedByUnverified ? { requested_by_unverified: spec.requestedByUnverified } : {}), ...(machine ? { machine } : {}), ...(arc ? { subtask_of: arc.id } : {}) });
     if ((spec.noStart || spec.adopt) && !arc) event(db, id, 'dispatch_held', { session: spec.adopt ?? null, reason: spec.adopt ? 'awaiting adoption' : 'created with --no-start' });
     if (parents.length) inheritSubscriptions(db, id, parents);
     if (arc) {
@@ -259,9 +265,19 @@ export function createCard(board, spec) {
     }
     if (initial === 'running' && arc && entry.workflow.run) setStatus(db, entry.workflow, id, 'running');
     else if (initial === 'running') claimIn(db, id, { ttl: claimTtl() });
+    // The creation declares its role even when dispatch is held. The existing durable effect queue
+    // keeps public-door I/O outside this transaction and retains an offline declaration for retry.
+    let declaration;
+    if(!arc) {
+      const creator=/^sc:[^:]+:(claude-code|codex|gemini|grok|pi|hermes|opencode|supercode):(.+)$/.exec(actorOf()??'');
+      const effect={kind:'declare_card_agent',id,role:'implementer',profile:spec.assignee??null,
+        context:process.env.SUPERCODE_CONTEXT??null,starter_session:creator?`${creator[1]}:${creator[2]}`:null};
+      const inserted=run(db,'INSERT INTO supercode_effects(effect) VALUES(?)',JSON.stringify(effect));
+      declaration={...effect,durableId:Number(inserted.lastInsertRowid)};
+    }
     // the body's task lines, as subtasks the creator filed, in this same write
     const subtasks = steps.map((step) => createCard(board, { ...step, subtaskOf: id, assignee: spec.assignee || null }).id);
-    return { id, existing: false, ...(subtasks.length ? { subtasks } : {}) };
+    return { id, existing: false, effects:declaration?[declaration]:[], ...(subtasks.length ? { subtasks } : {}) };
   });
 }
 
@@ -460,6 +476,10 @@ export async function runEffects(board, effects = [], { retryNotices = false } =
       if (!await sessionNotice(board, e)) continue;
     }
     else if (e.kind === 'cleanup_workspace') cleanupWorkspace(board, e.id);
+    else if (e.kind === 'declare_card_agent') {
+      const {declareCardAgentEffect}=await import('./agent-declarations.mjs');
+      if(!declareCardAgentEffect(board,e))continue;
+    }
     else if (e.kind === 'board_message') {
       const { sendBoardMessages } = await import('./dispatch.mjs');
       await sendBoardMessages(board, { undelivered: [] }, e.id);
@@ -536,7 +556,7 @@ export const requestReview = (board, id, { summary = null, metadata = null, revi
   act(board, id, 'request_review', { roles, payload: { summary, metadata, reviewer, force, run_id: expectedRunId, commit, ci_run, branch, pr, pr_head } });
 export const requestChanges = (board, id, { reason = null, reviewer = null, roles } = {}) => act(board, id, 'request_changes', { roles, payload: { reason, reviewer } });
 export const reopen = (board, id, { author = 'user', reason = null, roles } = {}) => act(board, id, 'reopen', { roles, payload: { author, reason } });
-export const reopenReview = (board, id, { roles } = {}) => act(board, id, 'reopen_review', { roles });
+export const reopenReview = (board, id, { roles, reason = null } = {}) => act(board, id, 'reopen_review', { roles, payload: { reason } });
 export const schedule = (board, id, reason = null, { roles } = {}) => act(board, id, 'schedule', { roles, payload: { reason } });
 export const promote = (board, id, { actor = 'user', reason = null, force = false, roles } = {}) => act(board, id, 'promote', { roles, payload: { actor, reason, force } });
 export const reclaim = (board, id, reason = null, { roles } = {}) => act(board, id, 'reclaim', { roles, payload: { reason } });
@@ -683,7 +703,7 @@ export const subscriptions = (db, id = null) => (id ? all(db, 'SELECT * FROM kan
 // ------------------------------------------------------------------ reading
 
 export function listCards(db, { status = null, assignee = null, machine = null, includeArchived = false } = {}) {
-  const rows = all(db, `SELECT t.*, c.machine, c.subtask_of, c.stage FROM tasks t LEFT JOIN supercode_cards c ON c.task_id = t.id
+  const rows = all(db, `SELECT t.*, c.machine, c.subtask_of, c.stage, c.tags, c.sponsor FROM tasks t LEFT JOIN supercode_cards c ON c.task_id = t.id
     WHERE (? IS NULL OR t.status = ? OR c.stage = ?) AND (? IS NULL OR t.assignee = ?) AND (? IS NULL OR c.machine = ?) AND (? OR t.status != 'archived')
     ORDER BY t.priority DESC, t.created_at ASC`, status, status, status, assignee, assignee, machine, machine, includeArchived ? 1 : 0);
   return rows.map((r) => ({ ...r, skills: json(r.skills, []) ?? [] }));
@@ -742,7 +762,7 @@ export function cardContext(db, id) {
 
 
 /** Hermes's swarm: a completed root as the shared blackboard, workers after it, a verifier after them all, a synthesizer last. */
-export function swarm(board, { goal, workers, verifier, synthesizer, tenant = null, createdBy = 'swarm-orchestrator', priority = 0, idempotencyKey = null }) {
+export function swarm(board, { goal, workers, verifier, synthesizer, tenant = null, createdBy = null, priority = 0, idempotencyKey = null }) {
   if (!String(goal ?? '').trim()) throw new Error('a swarm has a goal');
   if (!workers.length) throw new Error('a swarm has at least one --worker PROFILE:TITLE[:SKILL,SKILL]');
   const protocol = (root) => `\n\n## Swarm protocol\n- Swarm root / shared blackboard: \`${root}\`.\n- Read sibling/parent handoffs from the board's context before working.\n`

package/board/event-fleet.mjs

@@ -0,0 +1,59 @@
+// A projection of retained Teams events. Dispatch reads this projection, never a periodically fetched catalogue.
+import { readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { eventClient } from '@volter/teams/event-client';
+const pathOf=root=>join(root,'.session-events.json');
+const normalize=value=>String(value??'').toLowerCase().replace(/[^a-z0-9-]/g,'-').replace(/-+/g,'-').replace(/^-|-$/g,'');
+const wait=signal=>new Promise(resolve=>{const timer=setTimeout(resolve,5000);signal.addEventListener('abort',()=>{clearTimeout(timer);resolve();},{once:true});});
+
+export function followFleet({root,context,supercodeHome,wake,log}){
+  const abort=new AbortController();let resources={},cursor=null,connected=false,snapshot=null;
+  const persist=()=>{
+    const path=pathOf(root),temporary=`${path}.${randomUUID()}.tmp`;
+    writeFileSync(temporary,JSON.stringify({pid:process.pid,connected,cursor,resources}),{mode:0o600});renameSync(temporary,path);
+  };
+  const apply=(target,frame)=>{
+    const event=frame.data;if(!event||!['session','machine'].includes(event.resource?.kind))return false;
+    const key=`${event.resource.kind}:${event.resource.id}`,old=target[key];
+    if(old&&old.sequence>=frame.sequence)return false;
+    target[key]={sequence:frame.sequence,data:event.data};return true;
+  };
+  void(async()=>{
+    while(!abort.signal.aborted){
+      try{
+        const {team}=eventClient({context,supercodeHome});
+        // Every connection begins with a complete, ACL-filtered snapshot. A process restart cannot trust an old cache.
+        for await(const frame of team.events.follow({kinds:['session.started','session.ended','session.changed','resource.changed']}, {signal:abort.signal,after:cursor})){
+          if(frame.type==='snapshot_begin'){snapshot={};connected=false;persist();}
+          else if(frame.type==='snapshot_item')apply(snapshot??resources,frame);
+          else if(frame.type==='snapshot_end'){resources=snapshot??resources;snapshot=null;cursor=frame.cursor;connected=true;persist();wake('session-events-snapshot');}
+          else if(frame.type==='event'){const changed=apply(resources,frame);cursor=frame.cursor;connected=true;persist();if(changed)wake('session-events');}
+          else if(frame.type==='checkpoint'){const recovered=!connected;cursor=frame.cursor;connected=true;persist();if(recovered)wake('session-events-reconnected');}
+          else if(frame.terminal){cursor=null;connected=false;persist();wake('session-events-unavailable');break;}
+        }
+      }catch(error){if(!abort.signal.aborted)log(`dispatch session events unavailable: ${error.code??error.message}`);if(error.status===409)cursor=null;}
+      connected=false;persist();wake('session-events-unavailable');if(!abort.signal.aborted)await wait(abort.signal);
+    }
+  })();
+  return {close(){abort.abort();connected=false;persist();}};
+}
+
+export function readEventFleet(root){
+  let cache;try{cache=JSON.parse(readFileSync(pathOf(root),'utf8'));process.kill(cache.pid,0);}catch{return {ok:false,alive:new Set(),online:new Set(),sessions:[],native:new Map(),error:'published session events unavailable',presenceKnown:false};}
+  const machines=new Map(),online=new Set();
+  for(const [key,value] of Object.entries(cache.resources??{}))if(key.startsWith('machine:')){machines.set(value.data.id,normalize(value.data.name));if(cache.connected&&value.data.linked)online.add(normalize(value.data.name));}
+  const sessions=[],native=new Map(),alive=new Set();
+  for(const [key,value] of Object.entries(cache.resources??{}))if(key.startsWith('session:')){
+    for(const binding of value.data.bindings??[]){
+      const machine=machines.get(binding.machine_id);if(!machine||!binding.harness||!binding.native_session_id)continue;
+      const address=`sc:${machine}:${binding.harness}:${binding.native_session_id}`;
+      const known=cache.connected&&online.has(machine),state=known?(binding.state==='running'?true:binding.state==='stopped'?false:null):null;
+      const previous=native.get(address),states=[...(previous?.states??[]),state];
+      const combined=states.includes(true)?true:states.includes(null)?null:states.every(value=>value===false)?false:null;
+      native.set(address,{alive:combined,states});if(combined===true)alive.add(address);
+      sessions.push({address,machine,harness:binding.harness,session_id:binding.native_session_id,pane:binding.pane??null,name:binding.name??null,state:binding.state,identity:value.data.agent_identity??null});
+    }
+  }
+  return {ok:!!cache.connected,presenceKnown:!!cache.connected,online,alive,native,sessions,error:cache.connected?null:'published session events disconnected'};
+}

package/board/event-relay.mjs

@@ -0,0 +1,45 @@
+// App-owned source names/maps live here; the Teams core knows only a scoped event publisher.
+import { createHash } from 'node:crypto';
+import { eventClient } from '@volter/teams/event-client';
+import { boardSourceName, recordCardPublications } from './published.mjs';
+import { listBoards, openBoard } from './store.mjs';
+
+export function boardEventRelay({root,context,supercodeHome,log=()=>{}}) {
+  let work=null,dirty=false,closed=false,retry=null,reconcile=true;const sources=new Map();
+  const run=async()=>{
+    if(reconcile){
+      // Establish every native source head before any network operation. A
+      // delivery retry cannot leave later boards without their initial inventory.
+      for(const slug of listBoards(root)){const board=openBoard(root,slug);try{board.tx(db=>recordCardPublications(db,null));}finally{board.close();}}
+      reconcile=false;
+    }
+    const {team,context:audience}=eventClient({context,supercodeHome});
+    for(const slug of listBoards(root)){
+      const board=openBoard(root,slug);
+      try{
+        const key=JSON.stringify({server:audience.server,org:audience.org,principal:audience.principal,board:slug});
+        let source=sources.get(key);
+        if(!source){source=(await team.events.createSource({name:boardSourceName(root,slug)})).data.id;sources.set(key,source);}
+        const destination=createHash('sha256').update(`${key}:${source}`).digest('hex');
+        for(;;){
+          const rows=board.db.prepare('SELECT * FROM supercode_publications p WHERE NOT EXISTS (SELECT 1 FROM supercode_publication_receipts r WHERE r.event_id=p.id AND r.destination=?) ORDER BY sequence LIMIT 32').all(destination);if(!rows.length)break;
+          for(const row of rows){
+            if(closed)return;
+            const id=`event_${createHash('sha256').update(`${row.id}:${destination}`).digest('hex')}`;
+            await team.events.publish(source,{id,kind:row.kind,resource:{kind:'task',id:`${source}:${row.resource_id}`},revision:row.sequence,data:{board:slug,card:JSON.parse(row.snapshot)},actor:{session:row.actor?`session:${row.actor}`:null}},{idempotencyKey:id});
+            board.tx(db=>db.prepare('INSERT OR IGNORE INTO supercode_publication_receipts VALUES (?,?)').run(row.id,destination));
+          }
+        }
+      }finally{board.close();}
+    }
+  };
+  const wake=(refresh=true)=>{
+    reconcile ||= refresh;dirty=true;if(work||closed)return work;
+    work=(async()=>{while(dirty&&!closed){dirty=false;await run();}})().catch(error=>{
+      log(`board event delivery pending: ${error.code??error.message}`);
+      // Retry durable delivery, not a read of the board's current state.
+      retry=setTimeout(()=>wake(false),5000);retry.unref?.();
+    }).finally(()=>{work=null;});return work;
+  };
+  return {wake,close(){closed=true;clearTimeout(retry);}};
+}

package/board/event-stream.mjs

@@ -0,0 +1,104 @@
+// Public native workflow observation. Filesystem custody authorizes this door;
+// Teams separately authorizes the Org event and its installed subscribers.
+import { watch, existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, basename, join, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { listBoards, openBoard, backingPaths } from './store.mjs';
+import { recordCardPublications } from './published.mjs';
+
+const identity = root => createHash('sha256').update(realpathSync(root)).digest('hex');
+const cursorOf = (home, boards) => Buffer.from(JSON.stringify({version:1,home,boards})).toString('base64url');
+const resync = reason => Object.assign(new Error(reason), {code:'resync_required'});
+
+/** Snapshot once, then replay only committed publications on backing notifications. */
+export async function* followBoardPublications({root,after,signal}) {
+  const home=identity(root), positions={}, watchers=new Map();
+  let dirty=true, wake=null, failure=null, inventory=null;
+  const notify=()=>{dirty=true;wake?.();};
+  const directory=(path,accept)=>{
+    if(!existsSync(path))return;
+    if(watchers.has(path)){watchers.get(path).accept.push(accept);return;}
+    const entry={accept:[accept],handle:null};
+    entry.handle=watch(path,(_kind,name)=>{if(name==null||entry.accept.some(fn=>fn(String(name))))notify();});
+    entry.handle.on('error',error=>{failure=error;notify();});watchers.set(path,entry);
+  };
+  const file=path=>directory(dirname(path),name=>name===basename(path));
+  const register=slugs=>{
+    for(const entry of watchers.values())entry.accept=[];
+    directory(root,name=>['kanban.db','kanban.db-wal','kanban'].includes(name));
+    directory(join(root,'kanban'),name=>['boards','ztrack.json','board'].includes(name));
+    directory(join(root,'kanban','boards'),()=>true);
+    for(const slug of slugs){
+      const paths=backingPaths(root,slug);
+      file(paths.sqlite);file(`${paths.sqlite}-wal`);file(paths.ztrack);
+      directory(paths.files,name=>name.endsWith('.json'));
+      try {const cfg=JSON.parse(readFileSync(paths.ztrack,'utf8'));const document=resolve(dirname(paths.ztrack),cfg.document);file(document);file(`${document}.archive.md`);}catch{/* other backing */}
+    }
+  };
+  const aborted=()=>wake?.();signal?.addEventListener('abort',aborted);
+  try {
+    if(after){
+      let decoded;try{decoded=JSON.parse(Buffer.from(after,'base64url').toString());}catch{throw resync('Malformed workflow event cursor');}
+      if(decoded.version!==1||decoded.home!==home||!decoded.boards||typeof decoded.boards!=='object')throw resync('Workflow event cursor belongs to another source');
+      Object.assign(positions,decoded.boards);inventory=Object.keys(positions).sort().join('\0');
+    } else yield {type:'snapshot_begin'};
+    let initial=!after,checkpointPending=!!after;
+    while(!signal?.aborted){
+      if(failure)throw failure;
+      dirty=false;
+      const slugs=listBoards(root).sort(),current=slugs.join('\0');register(slugs);
+      if(inventory!==null&&current!==inventory)throw resync('Workflow board inventory changed');
+      inventory=current;
+      for(const slug of slugs){
+        const board=openBoard(root,slug);
+        try {
+          // External native writers do not share our transaction wrapper. Their
+          // filesystem event reconciles once into the same retained source log.
+          const boundary=board.tx(db=>{
+            recordCardPublications(db,null);
+            const log=db.prepare('SELECT id,pruned_through FROM supercode_publication_log').get();
+            const high=Number(db.prepare('SELECT MAX(sequence) AS n FROM supercode_publications').get()?.n??0);
+            const heads=initial?db.prepare('SELECT sequence FROM supercode_publication_heads ORDER BY resource_id').all().map(row=>row.sequence):[];
+            return {log:log.id,floor:Number(log.pruned_through),high,heads};
+          });
+          const position=positions[slug];
+          if(initial){
+            // The transaction's watermark fences concurrent mutations. Replay
+            // after it repairs any head updated while this inventory is read.
+            for(const sequence of boundary.heads){
+              const row=board.db.prepare('SELECT snapshot FROM supercode_publications WHERE sequence=?').get(sequence);
+              if(!row)throw resync('Workflow snapshot unavailable');
+              yield {type:'snapshot_item',data:{board:slug,card:JSON.parse(row.snapshot)}};
+            }
+            positions[slug]={log:boundary.log,sequence:boundary.high};
+          }else{
+            // A pruned floor above the cursor means changes it never read are gone; a new log id means a new store.
+            if(!position||position.log!==boundary.log||!Number.isSafeInteger(position.sequence)||position.sequence<boundary.floor||position.sequence>boundary.high)throw resync(`Workflow publication log changed: ${slug}`);
+            for(;;){
+              const rows=board.db.prepare('SELECT * FROM supercode_publications WHERE sequence>? ORDER BY sequence LIMIT 32').all(positions[slug].sequence);if(!rows.length)break;
+              for(const row of rows){positions[slug].sequence=row.sequence;yield {type:'event',id:row.id,kind:row.kind,cursor:cursorOf(home,positions),data:{board:slug,card:JSON.parse(row.snapshot)}};}
+            }
+          }
+        }finally{board.close();}
+      }
+      if(initial){initial=false;yield {type:'snapshot_end',cursor:cursorOf(home,positions)};dirty=true;}
+      else if(checkpointPending){checkpointPending=false;yield {type:'checkpoint',cursor:cursorOf(home,positions)};}
+      if(!dirty&&!signal?.aborted)await new Promise(done=>{wake=done;if(dirty||signal?.aborted)done();});
+      wake=null;
+    }
+  }finally{signal?.removeEventListener('abort',aborted);for(const {handle} of watchers.values())handle.close();}
+}
+
+export async function streamBoardPublications(options) {
+  if(options.once&&options.after)throw new Error('--once requires a fresh snapshot; omit --after');
+  const abort=new AbortController();const stop=()=>abort.abort();
+  process.once('SIGINT',stop);process.once('SIGTERM',stop);
+  try {
+    for await(const frame of followBoardPublications({...options,signal:abort.signal})){
+      if(!process.stdout.write(`${JSON.stringify(frame)}\n`))await new Promise(done=>process.stdout.once('drain',done));
+      if(options.once&&frame.type==='snapshot_end')break;
+    }
+  }catch(error){if(error.code==='resync_required'){process.stdout.write(`${JSON.stringify({type:'resync_required',reason:error.message})}\n`);return 1;}throw error;}
+  finally{process.removeListener('SIGINT',stop);process.removeListener('SIGTERM',stop);}
+  return 0;
+}

package/board/incidents.mjs

@@ -0,0 +1,57 @@
+// Service supervision retains evidence; only a manager/creator act releases dispatch.
+import { event, json, now } from './store.mjs';
+import { statusOf, creatorOf } from './workflow.mjs';
+
+export const monitorsRuns = entry => entry?.params?.run_failure_policy !== 'retry';
+export const failedObservation = name => ['exited', 'session_closed', 'session_lost', 'spawn_failed', 'orphaned', 'timed_out', 'stale'].includes(name);
+
+export function surfaceIncident(db, board, entry, id, name, evidence = {}, runId = null) {
+  const task = db.prepare('SELECT * FROM tasks WHERE id=?').get(id);
+  runId ??= task?.current_run_id;
+  if (!task || !runId) return false;
+  const row = db.prepare('SELECT * FROM task_runs WHERE id=?').get(runId);
+  if (!row || row.task_id !== id) return false;
+  const meta = json(row.metadata, {}) ?? {}, session = meta.supercode ?? {};
+  const prior = db.prepare("SELECT id FROM task_events WHERE task_id=? AND kind='run_incident' AND run_id=? ORDER BY id DESC LIMIT 1").get(id,runId);
+  const continued = db.prepare("SELECT id FROM task_events WHERE task_id=? AND kind='session_continued' AND run_id=? ORDER BY id DESC LIMIT 1").get(id,runId);
+  if (prior && !(continued?.id > prior.id)) return false;
+  const reason = evidence.error ?? row.error ?? `run ${runId} ended (${row.outcome ?? row.status}) without moving its card`;
+  const payload = { observation: name, run: runId, status: statusOf(db, task), reason,
+    session: session.session_id ?? null, machine: session.machine ?? null, pane: session.pane ?? null,
+    launch_key: session.launch_key ?? null, pid: session.pid ?? null, evidence };
+  const incident = event(db, id, 'run_incident', payload, runId);
+  event(db, id, 'dispatch_held', { reason, incident, run: runId });
+  meta.supercode = { ...session, incident, monitor_held: true, state: 'failed' };
+  db.prepare(`UPDATE task_runs SET ended_at=COALESCE(ended_at,?),status=CASE WHEN ended_at IS NULL THEN 'failed' ELSE status END,
+    outcome=COALESCE(outcome,'failed'),error=COALESCE(error,?),metadata=?,claim_lock=NULL,claim_expires=NULL WHERE id=?`)
+    .run(now(), reason, JSON.stringify(meta), runId);
+  if (task.current_run_id === runId) db.prepare('UPDATE tasks SET current_run_id=NULL,claim_lock=NULL,claim_expires=NULL,worker_pid=NULL,last_failure_error=? WHERE id=?').run(reason, id);
+  const text = `${id}: run #${runId} stopped: ${reason}. Incident event ${incident}. Evidence: ${JSON.stringify(payload)}\nThe dispatcher will start nothing. The manager or creator decides whether to start, resume or block the card; this incident remains recorded.`;
+  db.prepare('INSERT INTO task_comments(task_id,author,body,created_at) VALUES (?,?,?,?)').run(id, 'dispatcher', text, now());
+  const creator = creatorOf(db, id);
+  const reachableCreator = db.prepare("SELECT chat_id FROM kanban_notify_subs WHERE task_id=? AND json_extract(delivery_metadata,'$.role')='creator' AND platform='supercode' LIMIT 1").get(id)?.chat_id;
+  const to = [].concat(entry.params.managers ?? []).find(Boolean) ?? reachableCreator ?? (creator?.startsWith('session:sc:') ? creator.slice(8) : creator?.startsWith('sc:') ? creator : null);
+  if (to) event(db, id, 'board_message', { to, text, incident }, null);
+  else event(db, id, 'incident_delivery_pending', { incident, reason: 'no manager or reachable creator configured; incident retained on card' });
+  return true;
+}
+
+/** Older ended runs are audited before eligibility: a completed run is not permission to repeat. */
+export function auditEndedRuns(db, board, entry) {
+  if (!monitorsRuns(entry)) return;
+  for (const task of db.prepare(`SELECT t.*,r.id run_id,r.outcome,r.error,r.metadata run_metadata FROM tasks t JOIN task_runs r ON r.id=(SELECT MAX(id) FROM task_runs WHERE task_id=t.id)
+    WHERE t.current_run_id IS NULL AND r.ended_at IS NOT NULL AND t.status NOT IN ('done','archived')`).all()) {
+    const session = json(task.run_metadata, {})?.supercode;
+    const status = statusOf(db, task);
+    if (session?.status && session.status !== status) continue; // a card transition intentionally advances its work
+    const incident = db.prepare("SELECT id FROM task_events WHERE task_id=? AND run_id=? AND kind='run_incident'").get(task.id, task.run_id);
+    const release = db.prepare("SELECT id FROM task_events WHERE task_id=? AND kind='dispatch_released' ORDER BY id DESC LIMIT 1").get(task.id);
+    if (incident && session?.monitor_held && release?.id > incident.id) continue;
+    const decided = db.prepare("SELECT 1 FROM task_events WHERE task_id=? AND kind='dispatch_released' AND json_extract(payload,'$.ended_run')=?").get(task.id, task.run_id);
+    if (decided) continue; // its manager or creator ended it by an explicit act
+    const audited = db.prepare("SELECT 1 FROM task_events WHERE task_id=? AND run_id=? AND kind='audited'").get(task.id,task.run_id);
+    if (audited) continue; // Every explicitly schedules the next successful audit
+    if (['blocked','paused','reconfigured','review_passed','review','review_requested','audited'].includes(task.outcome)) continue;
+    surfaceIncident(db, board, entry, task.id, 'run_ended', { error: task.error, outcome: task.outcome }, task.run_id);
+  }
+}

package/board/published.mjs

@@ -0,0 +1,86 @@
+// The card writer commits the full snapshot and a retained delivery obligation together.
+import { createHash, randomUUID } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+export const PUBLICATION_SCHEMA = `
+CREATE TABLE IF NOT EXISTS supercode_publication_receipts (
+  event_id TEXT NOT NULL, destination TEXT NOT NULL, PRIMARY KEY(event_id,destination)
+);
+CREATE TABLE IF NOT EXISTS supercode_publications (
+  sequence INTEGER PRIMARY KEY AUTOINCREMENT, id TEXT NOT NULL UNIQUE, resource_id TEXT NOT NULL,
+  kind TEXT NOT NULL, snapshot TEXT NOT NULL, actor TEXT, created_at INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS supercode_publication_heads (
+  resource_id TEXT PRIMARY KEY, digest TEXT NOT NULL, sequence INTEGER NOT NULL, last_event_id INTEGER
+);
+CREATE TABLE IF NOT EXISTS supercode_publication_log (
+  id TEXT PRIMARY KEY, pruned_through INTEGER NOT NULL DEFAULT 0
+);`;
+// Every card's head stays; older changes beyond this many are pruned in one batch once twice as many accumulate.
+// A reader whose cursor falls below the pruned floor takes a new snapshot.
+const RETAINED_CHANGES = 1024;
+const hash = value => createHash('sha256').update(value).digest('hex');
+const parse = (value,fallback=null) => {try{return JSON.parse(value)??fallback;}catch{return fallback;}};
+const at = value => value == null ? null : new Date(Number(value)*1000).toISOString();
+const kinds = {started:'started',created:'created',completed:'completed',cancelled:'cancelled',reopened:'reopened',blocked:'blocked',unblocked:'unblocked',paused:'paused',resumed:'resumed',assigned:'assigned',linked:'linked',unlinked:'unlinked',commented:'commented',specified:'specified',review_requested:'review_requested',changes_requested:'changes_requested'};
+
+/**
+ * The ontology's Task status (contracts/ontology.md: todo, running, review, done, cancelled) of a card in a board lane.
+ * The lanes are the card machine's Hermes-shaped states: waiting lanes are `todo` (blocked is the blocked_by relation,
+ * ready is derived), and an archived card is `done` when it was completed, else `cancelled`.
+ */
+export function taskStatusOf(lane, completedAt) {
+  if (lane === 'running' || lane === 'review' || lane === 'done') return lane;
+  if (lane === 'archived') return completedAt ? 'done' : 'cancelled';
+  return 'todo';
+}
+
+export function cardSnapshot(db,row) {
+  const own=db.prepare('SELECT * FROM supercode_cards WHERE task_id=?').get(row.id)??{};
+  const comments=db.prepare('SELECT id,author,body,created_at FROM task_comments WHERE task_id=? ORDER BY id').all(row.id).map(comment=>({...comment,created_at:at(comment.created_at)}));
+  const verdicts={review_requested:'requested',approved:'approved',review_approved:'approved',changes_requested:'changes_requested',escalated:'escalated'};
+  const reviews=db.prepare("SELECT id,kind,payload,created_at FROM task_events WHERE task_id=? AND kind IN ('review_requested','approved','review_approved','changes_requested','escalated') ORDER BY id").all(row.id).map(event=>{const payload=parse(event.payload,{});return {id:event.id,verdict:verdicts[event.kind],by:payload.reviewer??payload.by??payload.profile,reason:payload.reason,at:at(event.created_at)};});
+  const attempts=db.prepare('SELECT id,profile,step_key,status,started_at,ended_at,outcome,summary,metadata,error FROM task_runs WHERE task_id=? ORDER BY id').all(row.id).map(run=>{
+    const native=parse(run.metadata,{})?.supercode??null;
+    const session=native?{machine:native.machine,harness:native.harness,session_id:native.session_id,address:native.address,pane:native.pane,surface:native.surface,state:native.state,closed_at:native.closed_at,agent:native.agent_id??null,counted:native.counted??null,profile_differences:native.agent_profile_mismatch?.differences??null}:null;
+    const metadata=parse(run.metadata,{});delete metadata.supercode;
+    return {id:String(run.id),profile:run.profile,step:run.step_key,status:run.status,started_at:at(run.started_at),ended_at:at(run.ended_at),outcome:run.outcome,error:run.error,session,handoff:run.summary||Object.keys(metadata).length?{summary:run.summary,metadata}:null};
+  });
+  const lane=own.stage??row.status;
+  return {id:row.id,title:row.title,body:row.body??'',assignee:row.assignee,status:taskStatusOf(lane,row.completed_at),lane,
+    priority:row.priority,created_by:row.created_by,created_at:at(row.created_at),started_at:at(row.started_at),completed_at:at(row.completed_at),result:row.result,skills:parse(row.skills,[]),model:row.model_override,provider:row.provider_override,
+    tags:parse(own.tags,null)??(row.tenant?[row.tenant]:[]),sponsor:own.sponsor??null,sponsor_evidence:parse(own.sponsor_evidence),requested_by_unverified:parse(own.requested_by_unverified),machine:own.machine??null,subtask_of:own.subtask_of??null,archived:!!own.archived,
+    blocked_by:parse(own.blocked_by,[]),paused:parse(own.paused),every:own.every??null,
+    workspace:{kind:row.workspace_kind,path:row.workspace_path,branch:row.branch_name,root:own.workspace_root,anchor:own.workspace_anchor},
+    parents:db.prepare('SELECT parent_id FROM task_links WHERE child_id=? ORDER BY parent_id').all(row.id).map(link=>link.parent_id),
+    reviews,children:db.prepare('SELECT child_id FROM task_links WHERE parent_id=? ORDER BY child_id').all(row.id).map(link=>link.child_id),comments,attempts};
+}
+
+/** Runs inside the backing's native transaction, including files and ztrack projections. */
+export function recordCardPublications(db,actor) {
+  const rows=db.prepare('SELECT * FROM tasks ORDER BY id').all(),present=new Set();let changed=0;
+  for(const row of rows){
+    present.add(row.id);const snapshot=JSON.stringify(cardSnapshot(db,row)),digest=hash(snapshot);
+    const previous=db.prepare('SELECT digest,last_event_id FROM supercode_publication_heads WHERE resource_id=?').get(row.id);
+    if(previous?.digest===digest)continue;
+    const last=db.prepare('SELECT id,kind FROM task_events WHERE task_id=? ORDER BY id DESC LIMIT 1').get(row.id);
+    const kind=`task.${previous?(last?.id!==previous.last_event_id?kinds[last?.kind]??'changed':'changed'):'created'}`;
+    const inserted=db.prepare('INSERT INTO supercode_publications(id,resource_id,kind,snapshot,actor,created_at) VALUES (?,?,?,?,?,?)').run(`event_${randomUUID()}`,row.id,kind,snapshot,actor,Date.now());
+    db.prepare('INSERT INTO supercode_publication_heads(resource_id,digest,sequence,last_event_id) VALUES (?,?,?,?) ON CONFLICT(resource_id) DO UPDATE SET digest=excluded.digest,sequence=excluded.sequence,last_event_id=excluded.last_event_id').run(row.id,digest,Number(inserted.lastInsertRowid),last?.id??null);changed++;
+  }
+  for(const old of db.prepare('SELECT resource_id,digest FROM supercode_publication_heads').all()){
+    if(present.has(old.resource_id)||old.digest==='removed')continue;
+    const inserted=db.prepare('INSERT INTO supercode_publications(id,resource_id,kind,snapshot,actor,created_at) VALUES (?,?,?,?,?,?)').run(`event_${randomUUID()}`,old.resource_id,'task.changed',JSON.stringify({id:old.resource_id,removed:true}),actor,Date.now());
+    db.prepare('UPDATE supercode_publication_heads SET digest=?,sequence=? WHERE resource_id=?').run('removed',Number(inserted.lastInsertRowid),old.resource_id);changed++;
+  }
+  db.prepare('INSERT INTO supercode_publication_log(id,pruned_through) SELECT ?,0 WHERE NOT EXISTS (SELECT 1 FROM supercode_publication_log)').run(`log_${randomUUID()}`);
+  const history=Number(db.prepare('SELECT count(*) AS n FROM supercode_publications WHERE sequence NOT IN (SELECT sequence FROM supercode_publication_heads)').get().n);
+  if(history>2*RETAINED_CHANGES){
+    const cut=Number(db.prepare('SELECT sequence FROM supercode_publications WHERE sequence NOT IN (SELECT sequence FROM supercode_publication_heads) ORDER BY sequence DESC LIMIT 1 OFFSET ?').get(RETAINED_CHANGES).sequence);
+    const old='SELECT id FROM supercode_publications WHERE sequence<=? AND sequence NOT IN (SELECT sequence FROM supercode_publication_heads)';
+    db.prepare(`DELETE FROM supercode_publication_receipts WHERE event_id IN (${old})`).run(cut);
+    db.prepare(`DELETE FROM supercode_publications WHERE id IN (${old})`).run(cut);
+    db.prepare('UPDATE supercode_publication_log SET pruned_through=MAX(pruned_through,?)').run(cut);
+  }
+  return changed;
+}
+export const boardSourceName = (root,slug) => `board:${hash(realpathSync(root)).slice(0,24)}:${slug}`;

package/board/runtime-door.mjs

@@ -0,0 +1,12 @@
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+const entry = fileURLToPath(new URL('../bin/runtime-door.mjs',import.meta.url));
+
+/** Public machine RPC only; no Teams binary or implementation/state-file access. */
+export function runtimeDoor(machine,method,params={}, {env=process.env,timeout=60_000,as=null}={}) {
+  const result = spawnSync(process.execPath,[entry],{
+    input:JSON.stringify({machine,method,params}),encoding:'utf8',timeout,
+    env:{...env,...(as?{SUPERCODE_CALLER:as}:{})},maxBuffer:512*1024*1024,
+  });
+  return {code:result.status,stdout:result.stdout??'',stderr:(result.stderr??'')+(result.error?.message??'')};
+}

package/board/store.mjs

@@ -17,6 +17,7 @@ import { DatabaseSync } from 'node:sqlite';
 import { openZtrackBoard } from './ztrack.mjs';
 import { isFilesBoard, openFilesBoard } from './files.mjs';
 import { signalBoardWrite } from './wake.mjs';
+import { PUBLICATION_SCHEMA, recordCardPublications } from './published.mjs';
 
 export const DEFAULT_BOARD = 'default';
 
@@ -73,7 +74,8 @@ const OURS = `CREATE TABLE IF NOT EXISTS supercode_cards (task_id TEXT PRIMARY K
 CREATE TABLE IF NOT EXISTS supercode_effects (id INTEGER PRIMARY KEY AUTOINCREMENT, effect TEXT NOT NULL);`;
 // `stage`: the card's workflow status where kanban.db stores another (a `reviewing` card is `running` to Hermes)
 // `since`: when the card entered its workflow status; `after_fired`: which of the status's `after` moves have run since
-const OURS_COLUMNS = { workspace_anchor: 'TEXT', workspace_root: 'TEXT', subtask_of: 'TEXT', stage: 'TEXT', since: 'INTEGER', after_fired: 'TEXT', blocked_by: 'TEXT', paused: 'TEXT', archived: 'INTEGER DEFAULT 0', every: 'TEXT', next_run_at: 'INTEGER' };
+// `tags`: the card's ordered tags (Hermes's `tenant` holds the first); `sponsor`, `sponsor_evidence`, `requested_by_unverified`: C4
+const OURS_COLUMNS = { workspace_anchor: 'TEXT', workspace_root: 'TEXT', subtask_of: 'TEXT', stage: 'TEXT', since: 'INTEGER', after_fired: 'TEXT', blocked_by: 'TEXT', paused: 'TEXT', archived: 'INTEGER DEFAULT 0', every: 'TEXT', next_run_at: 'INTEGER', tags: 'TEXT', sponsor: 'TEXT', sponsor_evidence: 'TEXT', requested_by_unverified: 'TEXT' };
 
 // ------------------------------------------------------------------ backings
 //
@@ -134,6 +136,7 @@ export function listBoards(root) {
 export function layOut(db, { fresh }) {
   if (fresh) db.exec(SCHEMA);
   db.exec(OURS);
+  db.exec(PUBLICATION_SCHEMA);
   const have = new Set(db.prepare('PRAGMA table_info(supercode_cards)').all().map((c) => c.name));
   for (const [column, type] of Object.entries(OURS_COLUMNS)) if (!have.has(column)) db.exec(`ALTER TABLE supercode_cards ADD COLUMN ${column} ${type}`);
 }
@@ -171,9 +174,21 @@ export function openBoard(root, slug = DEFAULT_BOARD, { create = false, backing
   if (!kept) mkdirSync(dirname(path), { recursive: true });
   const db = new DatabaseSync(path);
   db.exec('PRAGMA foreign_keys = OFF');
-  const fresh = !db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'tasks'").get();
-  if (fresh && !create) { db.close(); throw new Error(`${path} is not a board`); }
-  layOut(db, { fresh });
+  // The check and the layout are one write transaction: a board another process is laying out is not mistaken for a
+  // laid-out one (its `tasks` table made, the rest not), and a layout cut short by that process leaves nothing behind.
+  for (;;) {
+    try {
+      db.exec('BEGIN IMMEDIATE');
+      const fresh = !db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'tasks'").get();
+      if (fresh && !create) { db.exec('ROLLBACK'); db.close(); throw new Error(`${path} is not a board`); }
+      layOut(db, { fresh });
+      db.exec('COMMIT');
+      break;
+    } catch (error) {
+      try { db.exec('ROLLBACK'); } catch {}
+      if (!/locked|busy/i.test(error.message)) throw error;
+    }
+  }
   return { db, root, slug, path, backing: use, tx: (fn) => sqliteTx(db, fn), close: () => db.close() };
 }
 
@@ -182,11 +197,22 @@ export function openBoard(root, slug = DEFAULT_BOARD, { create = false, backing
  * A read inside the transaction is the state it writes over.
  */
 export const tx = (board, fn) => {
-  const result = board.tx(fn);
+  const result = board.tx(db => {const result=fn(db);recordCardPublications(db,actor);return result;});
   signalBoardWrite(board.root, actor);
   return result;
 };
-export const view = (board, fn) => fn(board.db);
+// A read that meets another process's write is retried as a write is (sqliteTx): a dispatcher service and a CLI share
+// the board, and a lost read must not become a launch failure. Inside a transaction its retry is the transaction's.
+const pause = new Int32Array(new SharedArrayBuffer(4));
+export const view = (board, fn) => {
+  for (;;) {
+    try { return fn(board.db); }
+    catch (error) {
+      if (inTx.has(board.db) || !/locked|busy/i.test(error.message)) throw error;
+      Atomics.wait(pause, 0, 0, 10);
+    }
+  }
+};
 
 // A deferred native transaction, with the whole operation retried on an optimistic conflict.
 // There is no separate application writer lock or contention timeout. A write inside one is part of it.
@@ -226,6 +252,13 @@ export function json(text, fallback = null) {
 let actor = null;
 export const actorOf = () => actor;
 export function setActor(address) { actor = address || null; }
+// C4: the principal the caller acts as (`agent:<id>`, `automation:<name>`, `person:<id>`, `session:<address>`): what a
+// card's `created_by` records, and what a relaunched agent still matches when it acts on the cards it created.
+let principal = null;
+export const principalOf = () => principal;
+export function setPrincipal(ref) { principal = ref || null; }
+/** Whether a recorded creator is the caller: its principal, its session address, or that session as an actor. */
+export const isCaller = (ref) => Boolean(ref) && [principal, actor, actor ? `session:${actor}` : null].includes(ref);
 
 export function event(db, taskId, kind, payload = null, runId = null) {
   // Session observations belong to the run machine. Legacy runs without a machine state retain

package/board/tools.mjs

@@ -181,6 +181,7 @@ export async function boardTool(root, name, args = {}, env = {}) {
           maxRuntime: args.max_runtime_seconds ?? null, initialStatus: args.initial_status ?? null, skills: args.skills ?? null, model: args.model ?? null, provider: args.provider ?? null,
           goal: args.goal_mode ? { maxTurns: args.goal_max_turns ?? null } : null, createdBy: author,
         });
+        await engine.runEffects(board,made.effects??[]);
         return ok({ task_id: made.id, existing: made.existing, status: tx(board, (db) => engine.getTask(db, made.id)).status });
       }
       case 'kanban_unblock':