@volter/supercode-orchestrator 0.4.160 → 0.5.1

package/board/wake.mjs

@@ -3,8 +3,8 @@
 import { watch, existsSync, readFileSync, readdirSync, writeFileSync, renameSync, unlinkSync, realpathSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { spawn } from 'node:child_process';
-import { tmpdir } from 'node:os';
+import { followFleet } from './event-fleet.mjs';
+import { boardEventRelay } from './event-relay.mjs';
 import { fileURLToPath } from 'node:url';
 
 export function signalBoardWrite(root, actor) {
@@ -20,12 +20,14 @@ export function signalBoardWrite(root, actor) {
 /** One coalescing queue shared by standalone serve and the hosted dispatcher. */
 export function watchBoard({ root, binary, env, log = () => {} }) {
   const watchers = new Map();
-  let pending = null, waiter = null, closed = false, child = null, retry = null, lastError = null, catalogue = null;
+  let pending = null, waiter = null, closed = false;
+  let relay = null;
   const wake = (source, at = Date.now()) => {
     if (closed) return;
     if (!pending) pending = { at, sources: new Set() };
     pending.at = Math.min(pending.at, at);
     pending.sources.add(source);
+    if (!source.startsWith('session-events')) void relay?.wake();
     waiter?.();
   };
   const directory = (path, key, accept) => {
@@ -61,7 +63,12 @@ export function watchBoard({ root, binary, env, log = () => {} }) {
     directory(join(root, 'kanban'), 'board-registry', name => ['boards', 'ztrack.json', 'current'].includes(name));
     directory(boards, 'board-registry', () => true);
     const dirs = [join(root, 'kanban'), ...(existsSync(boards) ? readdirSync(boards).map(name => join(boards, name)) : [])];
+    file(join(root,'kanban.db'),'board-storage');
+    file(join(root,'kanban.db-wal'),'board-storage');
     for (const dir of dirs) {
+      file(join(dir,'kanban.db'),'board-storage');
+      file(join(dir,'kanban.db-wal'),'board-storage');
+      directory(join(dir,'board'),'board-storage',name=>name.endsWith('.json'));
       file(join(dir, 'ztrack.json'), 'board-config');
       try {
         const config = JSON.parse(readFileSync(join(dir, 'ztrack.json'), 'utf8'));
@@ -82,57 +89,11 @@ export function watchBoard({ root, binary, env, log = () => {} }) {
       }
     }
   };
-  // The retained Teams catalogue includes local and remote session changes.
-  // This is a read-only stream, with no model or new native harness session.
-  const follow = () => {
-    if (closed) return;
-    let buffer = '', error = '';
-    const command = env.SUPERCODE_TEAMS_ENTRY ? process.execPath : binary;
-    const args = [...(env.SUPERCODE_TEAMS_ENTRY ? [env.SUPERCODE_TEAMS_ENTRY] : []), 'sessions', 'list', '--watch', '--json', '--limit', '200'];
-    child = spawn(command, args, { cwd: tmpdir(), env, stdio: ['ignore', 'pipe', 'pipe'] });
-    child.stdout.setEncoding('utf8').on('data', chunk => {
-      buffer += chunk;
-      if (buffer.length > 8 * 1024 * 1024) { error = 'catalogue frame exceeds 8 MiB'; child.kill(); return; }
-      let end;
-      while ((end = buffer.indexOf('\n')) >= 0) {
-        const line = buffer.slice(0, end); buffer = buffer.slice(end + 1);
-        try {
-          const event = JSON.parse(line);
-          lastError = null;
-          if (['heartbeat', 'ping', 'keepalive'].includes(event.type)) continue;
-          if (event.type === 'catalog_reset' && Array.isArray(event.data?.items)) {
-            // Transcript revisions and sort order are not scheduling events.
-            // The safety sweep reads quiet timestamps; wake for session identity,
-            // availability and available delivery/control doors changing now.
-            const next = JSON.stringify(event.data.items.map(item => ({
-              id:item.id, harness:item.harness, machines:[...(item.machine_ids ?? [])].sort(),
-              bindings:(item.bindings ?? []).map(binding => ({ id:binding.id, machine:binding.machine_id,
-                incarnation:binding.incarnation_id, runtime:binding.native_runtime_id, session:binding.native_session_id,
-                harness:binding.harness, state:binding.state, capabilities:[...(binding.native_capabilities ?? [])].sort(),
-              })).sort((a,b)=>String(a.id).localeCompare(String(b.id))), actions:item.actions,
-              presence:item.activity?.presence, turn:item.activity?.turn,
-              status:item.live_status, delivery:item.delivery,
-            })).sort((a,b)=>String(a.id).localeCompare(String(b.id))));
-            if (next === catalogue) continue;
-            catalogue = next;
-          }
-          wake('session-catalogue');
-        } catch { /* CLI diagnostics are not events */ }
-      }
-    });
-    child.stderr.setEncoding('utf8').on('data', chunk => { error = (error + chunk).slice(-500); });
-    child.on('error', failure => { error = failure.message; });
-    child.on('close', () => {
-      child = null;
-      if (!closed) {
-        const reason = error.trim() || 'connection closed';
-        if (reason !== lastError) log(`dispatch session stream ended: ${reason}; reconnecting, safety sweep remains active`);
-        lastError = reason;
-        retry = setTimeout(follow, 5000);
-      }
-    });
-  };
-  refresh(); follow();
+  refresh();
+  const supercodeHome = env.SUPERCODE_HOME || (env.XDG_CONFIG_HOME ? join(env.XDG_CONFIG_HOME,'supercode') : join(env.HOME ?? '', '.config','supercode'));
+  relay = boardEventRelay({root,supercodeHome,log});
+  const fleet = followFleet({root,supercodeHome,wake,log});
+  void relay.wake();
   return {
     refresh,
     wake,
@@ -148,9 +109,9 @@ export function watchBoard({ root, binary, env, log = () => {} }) {
       return result ? { at: result.at, sources: [...result.sources] } : null;
     },
     close() {
-      closed = true; waiter?.(); clearTimeout(retry);
+      closed = true; waiter?.(); fleet.close(); relay.close();
       for (const handle of watchers.values()) handle.close();
-      watchers.clear(); child?.kill('SIGTERM');
+      watchers.clear();
     },
   };
 }

package/board/workflow.mjs

@@ -64,8 +64,8 @@ export function statusOf(db, task) {
 /** Creation history, not an editable display name or notification subscriber. */
 export function creatorOf(db, id) {
   const payload = json(one(db, "SELECT payload FROM task_events WHERE task_id=? AND kind='created' ORDER BY id LIMIT 1", id)?.payload, {}) ?? {};
-  const address = payload.creator ?? payload.by;
-  return payload.source !== 'document' && /^(?:sc:[^:]+:[^:]+:|hermes-run:)/.test(address ?? '') ? address : null;
+  if (payload.source === 'document') return null;
+  return [payload.created_by,payload.creator,payload.by].find(ref => /^(?:person:|agent:|automation:|session:sc:|sc:[^:]+:[^:]+:|hermes-run:)/.test(ref ?? '')) ?? null;
 }
 
 export function completionOwnerOf(db, id) {
@@ -221,7 +221,7 @@ function onlyTicks(was, body) {
 /** Seconds a card's runs spent by role, and the rest of its life as `waiting`. */
 export function runWorkingSeconds(row, at = now()) {
   const end = Number(row.ended_at ?? at);
-  return Math.max(0, end - Number(row.started_at ?? end));
+  return Math.max(0, end - Number(row.started_at ?? end) - Number(json(row.metadata,{})?.supercode?.stopped_seconds??0));
 }
 
 function timeOf(db, task) {
@@ -316,8 +316,8 @@ export function scopeOf(db, board, task, { params, event = {}, extra = {} } = {}
     last_completed: lastCompleted ?? null,
     events_since: (t, kinds = []) => all(db, `SELECT kind FROM task_events WHERE task_id = ? AND created_at >= ?${kinds.length ? ` AND kind IN (${kinds.map(() => '?').join(', ')})` : ''}`, task.id, t, ...kinds),
     // the latest event of each kind on the card: kind → { created_at, payload }
-    last_events: Object.fromEntries(all(db, 'SELECT e.kind, e.created_at, e.payload FROM task_events e JOIN (SELECT kind, MAX(id) AS id FROM task_events WHERE task_id = ? GROUP BY kind) l ON l.id = e.id', task.id)
-      .map((r) => [r.kind, { created_at: r.created_at, payload: json(r.payload, {}) ?? {} }])),
+    last_events: Object.fromEntries(all(db, 'SELECT e.id, e.kind, e.created_at, e.payload FROM task_events e JOIN (SELECT kind, MAX(id) AS id FROM task_events WHERE task_id = ? GROUP BY kind) l ON l.id = e.id', task.id)
+      .map((r) => [r.kind, { id: r.id, created_at: r.created_at, payload: json(r.payload, {}) ?? {} }])),
     comments_since: (t) => all(db, 'SELECT author, body, created_at FROM task_comments WHERE task_id = ? AND created_at >= ?', task.id, t),
     // the latest commit naming this card on its work branches and default branch, in its workspace's repository (a
     // subtask's: its arc's), as epoch seconds
@@ -437,6 +437,12 @@ export function fire(db, board, entry, id, name, { roles = [], payload = {}, ext
   const to = take(db, board, entry, task, from, taken, scope, effects);
   settle(db, board, entry, id, effects);
   projectStatus(db, board, entry, id);
+  // A manager's or creator's explicit act releases a hold, and a run it ends is their decision: the ended-run audit
+  // never turns it into an incident that waits for a second act
+  const ended = task.current_run_id && one(db, 'SELECT ended_at FROM task_runs WHERE id = ?', task.current_run_id)?.ended_at != null ? task.current_run_id : null;
+  if ((scope.card.dispatch_hold || ended) && roles.some(role => ['manager','creator'].includes(role)) &&
+      (['resume','reclaim','replace_session','reopen','reopen_review'].includes(name) || (name === 'set' && ['assignee','machine','model'].includes(payload.field))))
+    record(db,id,'dispatch_released',{reason:`explicit ${name}`,incident:scope.card.last_events.run_incident?.payload?.run ?? null,...(ended ? { ended_run: ended } : {})});
   queueTransitionNotice(db, board, entry, task, from, name, payload, beforeRun, effects);
   return { from, to: statusOf(db, cardOf(db, id)), moved: to !== from, effects };
 }
@@ -586,6 +592,8 @@ const FORMAT = {
   // the reviewer is the lane that reviewed (the card's assignee while in review), unless the verdict names one
   changes_requested: ({ e, before, after }) => ({ reason: e.reason ?? null, reviewer: e.reviewer ?? before.assignee ?? null, implementer: after.assignee }),
   review_reopened: ({ after, to }) => ({ status: to, implementer: after.assignee }),
+  review_voided: ({ e, before }) => ({ reason: e.reason, review_request: before.last_events.review_requested?.id ?? null,
+    review_run: before.latest_review?.id ?? null, verdict: Math.max(before.last_events.review_pass?.id ?? 0, before.last_events.changes_requested?.id ?? 0) || null }),
   // what arrived (an unblock says it), and where the card resumes
   unblocked: ({ e, to }) => ({ reason: e.reason ?? null, ...(to !== 'ready' ? { status: to, resume_status: to } : {}) }),
   gave_up: ({ e, after, params, outcome }) => ({ error: String(e.error ?? '').slice(0, 500) || null, failures: Number(after.consecutive_failures || 0), limit: after.max_retries ?? params.failure_limit, outcome }),
@@ -694,6 +702,18 @@ const ACTIONS = {
       return;
     }
     if (!ASSIGNABLE.has(field)) throw new Error(`the workflow assigns ${field}, which is not a card field it may set`);
+    if (field === 'assignee') {
+      // A model override names a model of the harness it was chosen for; a lane of another harness cannot run it
+      // (a Claude model left on a Codex lane fails every turn), so it goes with the old lane, on the record
+      const task = one(ctx.db, 'SELECT assignee, model_override, provider_override FROM tasks WHERE id = ?', ctx.id);
+      const harnessOf = (name) => name ? ctx.entry.profiles?.[name]?.worker?.harness ?? null : null;
+      const before = harnessOf(task?.assignee), after = harnessOf(value);
+      if (task?.model_override && before && after && before !== after) {
+        run(ctx.db, 'UPDATE tasks SET model_override = NULL, provider_override = NULL WHERE id = ?', ctx.id);
+        record(ctx.db, ctx.id, 'model_override_cleared', { model: task.model_override, provider: task.provider_override ?? null,
+          from: task.assignee, from_harness: before, to: value, to_harness: after }, ctx.runId);
+      }
+    }
     run(ctx.db, `UPDATE tasks SET ${field} = ? WHERE id = ?`, typeof value === 'boolean' ? Number(value) : value ?? null, ctx.id);
   },
   count(ctx, counter) {
@@ -1052,6 +1072,7 @@ export function storedStatus(db, board, entry, id) {
 export function projectStatus(db, board, entry, id) {
   if (!entry.workflow.stored_as?.length) return;
   const { status, stored } = storedStatus(db, board, entry, id);
-  run(db, 'UPDATE tasks SET status = ? WHERE id = ?', stored, id);
-  run(db, 'INSERT INTO supercode_cards (task_id, stage) VALUES (?, ?) ON CONFLICT(task_id) DO UPDATE SET stage = excluded.stage', id, status);
+  // Only a change is written: an unchanged write still commits, and a commit wakes the dispatcher that called this.
+  run(db, 'UPDATE tasks SET status = ? WHERE id = ? AND status IS NOT ?', stored, id, stored);
+  run(db, 'INSERT INTO supercode_cards (task_id, stage) VALUES (?, ?) ON CONFLICT(task_id) DO UPDATE SET stage = excluded.stage WHERE supercode_cards.stage IS NOT excluded.stage', id, status);
 }

package/board/workspace.mjs

@@ -1,9 +1,18 @@
 // Filesystem/RPC work happens before a board transaction; the ownership check is pure.
-import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { basename, dirname } from 'node:path';
-import { Workspaces, inspectCheckout, repositoryId, teamsHome } from '@volter/supercode-teams/workspaces';
-import { localMachine, normalMachine, supercodeBin, commandEnv } from './dispatch.mjs';
+import { runtimeDoor } from './runtime-door.mjs';
+import { localMachine, normalMachine, commandEnv } from './dispatch.mjs';
+
+// Repository identities are portable input values; the daemon owns their checkout resolution.
+function repositoryId(value) {
+  let s=String(value??'').trim().replace(/\.git\/?$/,'').replace(/\/$/,'');
+  if(/^[^/@]+@[^:]+:/.test(s))s=s.replace(/^[^@]+@/,'').replace(':','/');
+  else if(/^[a-z]+:\/\//i.test(s)){const url=new URL(s);s=url.host+url.pathname;}
+  s=s.replace(/^github\.com\//i,'');
+  if(!/^[\w.-]+(?:\/[\w.-]+)+$/.test(s)||s.split('/').some(p=>p==='.'||p==='..'))throw new Error('repository must name a portable Git remote identity');
+  return s;
+}
 export const isWorkspacePath = value => /^(\/|~|[A-Za-z]:[\\/])/.test(value ?? '');
 // The dispatcher's latest presence reading (observeFleet): a machine it reads as offline is not asked.
 let presence = null;
@@ -12,17 +21,10 @@ function workspaceDoor(machine, verb, value, options = {}) {
   if (machine && presence?.known === true && normalMachine(machine) !== localMachine() && !presence.online.has(normalMachine(machine))) {
     throw new Error(`workspace on ${machine}: machine ${normalMachine(machine)} is offline`);
   }
-  if (!machine || normalMachine(machine) === localMachine()) {
-    const map = new Workspaces(teamsHome());
-    if (verb === 'inspect') return inspectCheckout(value);
-    if (verb === 'register') return map.register(value);
-    return map.resolve(value, options.branch, options);
-  }
-  const args = ['teams', 'workspace', verb, value, '--machine', machine];
-  for (const key of ['branch', 'card']) if (options[key]) args.push(`--${key}`, options[key]);
-  for (const key of ['solo', 'create']) if (options[key]) args.push(`--${key}`);
-  const r = spawnSync(supercodeBin(), args, { env: commandEnv(), encoding: 'utf8', timeout: 60_000 });
-  if (r.status !== 0) throw new Error(`workspace on ${machine}: ${(r.stderr || r.stdout || r.error?.message).trim()}`);
+  const local = !machine || normalMachine(machine) === localMachine();
+  const params = verb === 'list' ? {} : verb === 'inspect' || verb === 'register' ? {path:value} : {repository:value,...options};
+  const r = runtimeDoor(local?null:machine,`harness.v1.workspaces.${verb}`,params,{env:commandEnv()});
+  if (r.code !== 0) throw new Error(`workspace on ${machine}: ${(r.stderr || r.stdout || r.error?.message).trim()}`);
   return JSON.parse(r.stdout);
 }
 export function declareWorkspace(kind, value, machine, branch = null) {
@@ -40,7 +42,8 @@ export function declareWorkspace(kind, value, machine, branch = null) {
  *  keeps its work in each of them (its own worktree aside). Another machine's map is not read from here. */
 export function branchCheckouts(machine, branch) {
   if (!branch || (machine && normalMachine(machine) !== localMachine())) return [];
-  return new Workspaces(teamsHome()).list().filter((row) => (branch === '*' || row.branch === branch) && existsSync(row.path));
+  const listed = workspaceDoor(null, 'list', null);
+  return (Array.isArray(listed) ? listed : listed.workspaces ?? listed.items ?? []).filter((row) => (branch === '*' || row.branch === branch) && existsSync(row.path));
 }
 /** The registered checkout of `repository` on `branch` on `machine`: where a card changing several repositories
  *  keeps its work in each of them. */

package/commands.mjs

@@ -15,12 +15,12 @@ export function parseCommand(text) {
  * message. Text because the orchestrator does not own the worker's system
  * prompt (§0.3). One line, stable, greppable by the mock worker in tests.
  */
-export function frame(profile, key, sender, senderName, at, text) {
+export function frame(profile, key, sender, senderName, at, text, identity = null) {
   const where = [key.platform, key.kind, key.chat_id, key.thread_id ? `thread ${key.thread_id}` : null].filter(Boolean).join(' ');
   // In a Room the author reads as the token that addresses them (`aaron <@prn_…>`): written back, it is a mention RH2
   // records and notifies, so the agent learns the form from every line it hears.
   const who = key.platform === 'rh2' && /^prn_[a-z0-9]+$/.test(String(sender)) ? `${senderName ?? sender} <@${sender}>` : senderName ? `${senderName} (${sender})` : sender;
-  return `[channel: ${where} · from: ${who} · at: ${at} · profile: ${profile}]\n${text}`;
+  return `[channel: ${where} · from: ${who} · identity: ${identity?.classification==='proven'?`${identity.principal.name} (${identity.principal.id}; proven)`:identity?.label??'unresolved'} · at: ${at} · profile: ${profile}]\n${text}`;
 }
 
 export const REPLY = Object.freeze({

package/conversations.mjs

@@ -0,0 +1,108 @@
+// The agent layer as the reducer computes it (docs/architecture/orchestrator.md §2.10): which agent a
+// profile is, conversations separate from sessions (G5, amended by M3), the speaker policy that picks
+// the receiving agents on a shared surface (G1), and usage summed against budgets (G3).
+// Pure: no I/O and no clock; time comes from the caller's `now`.
+
+import { surfaceKeyString } from './ir.mjs';
+
+/** A named agent of this home: declared in `agents`, or a profile's own agent of the same name. */
+export function isAgent(state, name) {
+  return Boolean(name && (state.agents?.[name] || state.profiles?.[name]));
+}
+
+/** The profile an agent runs as. */
+export function profileOfAgent(state, agent) {
+  return state.agents?.[agent]?.profile ?? (state.profiles?.[agent] ? agent : null);
+}
+
+/** The binding slot an agent holds on a surface: the surface's key for a profile's own agent, else qualified. */
+export function agentSlot(profileName, agent, keyString) {
+  return !agent || agent === profileName ? keyString : `${keyString}@${agent}`;
+}
+
+export const conversationId = (key) => `thread:${surfaceKeyString(key)}`;
+
+/** The thread a surface shows, created on first sight with the routed agent as its default speaker. */
+export function ensureConversation(state, key, routedAgent, now) {
+  const id = conversationId(key);
+  state.conversations ??= {};
+  return state.conversations[id] ??= {
+    id, kind: 'thread', surface: key, participants: [],
+    speaker: { kind: 'addressed', default: routedAgent }, history: { kind: 'platform' },
+  };
+}
+
+/** Add a participant (an agent's name, or a person as `<platform>:<user id>`); its first role stays. */
+export function addParticipant(conversation, principal, role, now) {
+  const live = conversation.participants.find((p) => p.principal === principal && !p.until);
+  if (!live) conversation.participants.push({ principal, role, since: now });
+}
+
+const mentioned = (text, name) => new RegExp(`(^|[^\\w@])@${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'i').test(text ?? '');
+
+/**
+ * The agents that receive a line (G1). `addressed`: the agents the line mentions, else the holder a
+ * transfer left, else the default; `all`: every agent in the conversation; `round_robin`: the next in
+ * order; `selector`: the selecting agent, which answers with a transfer; `floor`: what the meeting's
+ * adapter named. Never a hidden model call.
+ */
+export function receivingAgents(state, conversation, ev, routedAgent) {
+  const policy = conversation.speaker ?? { kind: 'addressed' };
+  const agentsIn = conversation.participants.filter((p) => !p.until && isAgent(state, p.principal)).map((p) => p.principal);
+  const fallback = conversation.holder ?? policy.default ?? routedAgent;
+  switch (policy.kind) {
+    case 'all': return agentsIn.length ? agentsIn : [fallback];
+    case 'round_robin': {
+      const order = (policy.order ?? []).filter((a) => isAgent(state, a));
+      if (!order.length) return [fallback];
+      const next = order[(order.indexOf(conversation.last_speaker) + 1) % order.length];
+      return [next];
+    }
+    case 'selector': return [isAgent(state, policy.selector) ? policy.selector : fallback];
+    case 'floor': return [isAgent(state, ev.speaker_agent) ? ev.speaker_agent : fallback];
+    default: {
+      const candidates = [...new Set([...agentsIn, ...Object.keys(state.agents ?? {}), ...Object.keys(state.profiles ?? {})])];
+      const named = candidates.filter((a) => mentioned(ev.text, a));
+      return named.length ? named : [fallback];
+    }
+  }
+}
+
+/** Store a session's usage, recomputed whole from its native records. */
+export function recordUsage(state, session, agent, usage) {
+  state.usage ??= {};
+  state.usage[session] = { ...(agent ? { agent } : {}), usage };
+}
+
+const tokens = (u) => (u.input_tokens ?? 0) + (u.output_tokens ?? 0);
+
+/** An agent's use within a budget's window (`run`: this session only). */
+export function usedWithin(state, agent, period, now, session = null) {
+  const day = now.slice(0, 10), month = now.slice(0, 7);
+  let total = 0, cost = 0;
+  for (const [ref, record] of Object.entries(state.usage ?? {})) {
+    if (period === 'run' ? ref !== session : record.agent !== agent) continue;
+    for (const u of record.usage ?? []) {
+      if (period === 'day' && !u.at.startsWith(day)) continue;
+      if (period === 'month' && !u.at.startsWith(month)) continue;
+      total += tokens(u);
+      cost += u.cost?.amount ?? 0;
+    }
+  }
+  return { tokens: total, cost };
+}
+
+/** The budget a start or resume would exceed, as a sentence, or null. A gate, never a pause. */
+export function budgetRefusal(state, profile, agent, now, session = null) {
+  const layers = [state.profiles?.default?.budgets ?? [], profile === state.profiles?.default ? [] : profile?.budgets ?? []];
+  for (const budget of layers.flat()) {
+    const used = usedWithin(state, agent, budget.period, now, session);
+    if (budget.limit?.tokens != null && used.tokens >= budget.limit.tokens) {
+      return `${agent} has used ${used.tokens} of its ${budget.limit.tokens}-token ${budget.period} budget`;
+    }
+    if (budget.limit?.cost != null && used.cost >= budget.limit.cost.amount) {
+      return `${agent} has spent ${used.cost} of its ${budget.limit.cost.amount} ${budget.limit.cost.currency} ${budget.period} budget`;
+    }
+  }
+  return null;
+}

package/cron.mjs

@@ -13,6 +13,7 @@
 import { surfaceKeyString } from './ir.mjs';
 import { homeChannel } from './ir.mjs';
 import { endBinding, ensureRuntime, leaseId, newObligation, permissionResponse, reply, startWorker } from './reducer.mjs';
+import { budgetRefusal } from './conversations.mjs';
 
 /** Retry delays after the 1st, 2nd and 3rd send attempt (§4.3 "retry pending obligations"). */
 export const BACKOFF_MINUTES = Object.freeze([1, 2, 4]);
@@ -805,7 +806,20 @@ function launchFire(state, profile, job, fire, prompt, now, effects) {
     deliverResult(state, profile, { job, fire }, fire.error, true, now, effects);
     return;
   }
-  if (job.attach_to_session === true && attachFire(state, profile, job, fire, prompt, now, effects)) return;
+  // Which session the fire runs in (C8): `current` (the conversation it delivers to — Hermes's attach_to_session),
+  // `main` (its agent's main conversation), `session:<id>` (that one), else `isolated`: a session of its own.
+  const sessionTarget = job.session_target ?? (job.attach_to_session === true ? 'current' : 'isolated');
+  if (sessionTarget === 'current' && attachFire(state, profile, job, fire, prompt, now, effects)) return;
+  if (sessionTarget === 'main' && attachTo(state, profile, mainBinding(profile), job, fire, prompt, now, effects)) return;
+  if (sessionTarget.startsWith('session:') && attachTo(state, profile, Object.entries(profile.bindings).find(([ks, b]) => !b.ended_at && !ks.includes('#') && b.worker.session_id === sessionTarget.slice(8)), job, fire, prompt, now, effects)) return;
+  // G3: a fire of an agent over its budget does not start; it fails with the reason, which is told
+  const refused = budgetRefusal(state, profile, profile.name, now);
+  if (refused) {
+    finishFire(profile, fire, job, 'failed', now, `not started: ${refused}`, effects);
+    deliverResult(state, profile, { job, fire }, fire.error, true, now, effects);
+    effects.push({ type: 'budget_refused', profile: profile.name, agent: profile.name, reason: refused });
+    return;
+  }
   const rt = ensureRuntime(state);
 
   const key = { platform: 'cron', kind: 'dm', chat_id: job.id };
@@ -815,17 +829,24 @@ function launchFire(state, profile, job, fire, prompt, now, effects) {
     key,
     worker: { harness: profile.worker.harness, session_id: fire.id, locator: null },
     started_at: now, last_activity_at: now, ended_at: null, end_reason: null,
-    handoff: null, recurrence: { job_id: job.id }, residue: { fire_id: fire.id },
+    agent: profile.name, recurrence: { job_id: job.id }, residue: { fire_id: fire.id },
   };
   fire.started_at = now;
   const worker = { ...profile.worker, model: job.model ?? profile.worker.model, cwd: job.workdir ?? profile.worker.cwd };
   // The prompt rides the queue: `handleWorker`'s `started` case flushes it once
   // the lease exists, the same path an inbound message takes.
   (rt.queues[leaseId(profile.name, ks)] ??= []).push({ text: prompt, at: now, context_from: job.context_from ?? null, skills: job.skills ?? [], job_id: job.id });
-  effects.push({ type: 'runtime_start', profile: profile.name, keyString: ks, worker, prompt });
+  effects.push({ type: 'runtime_start', profile: profile.name, keyString: ks, worker, prompt, agent: profile.name });
   effects.push({ type: 'save' });
 }
 
+/** The agent's main conversation on this profile: the live channel binding with the latest activity. */
+function mainBinding(profile) {
+  return Object.entries(profile.bindings)
+    .filter(([ks, b]) => !b.ended_at && !ks.includes('#') && !b.recurrence && !['cron', 'webhook'].includes(b.key.platform))
+    .sort(([, a], [, b]) => String(b.last_activity_at ?? '').localeCompare(String(a.last_activity_at ?? '')))[0];
+}
+
 /**
  * `attach_to_session`: the fire is a turn in the live session of the conversation it delivers to, taken the way an
  * inbound message there is: it steers the running turn where the worker takes input mid-turn, waits behind it
@@ -839,13 +860,18 @@ function attachFire(state, profile, job, fire, prompt, now, effects) {
   const found = Object.entries(profile.bindings).find(([ks, b]) => !b.ended_at && !ks.includes('#')
     && b.key.platform === target.platform && String(b.key.chat_id ?? '') === String(target.chat_id ?? '')
     && String(b.key.thread_id ?? '') === String(target.thread_id ?? ''));
+  return attachTo(state, profile, found, job, fire, prompt, now, effects);
+}
+
+/** The fire as a turn in a live binding's session (steering, queued or sent), when there is one. */
+function attachTo(state, profile, found, job, fire, prompt, now, effects) {
   if (!found) return false;
   const [keyString, binding] = found;
   const rt = ensureRuntime(state);
   const lid = leaseId(profile.name, keyString);
   if (!rt.leases[lid] && !rt.turns[lid] && !rt.starting[lid]) {
     if (binding.worker.session_id) binding.residue.resume_runtime_id ??= binding.residue.runtime_id ?? binding.worker.session_id;
-    startWorker(state, profile, keyString, effects);
+    if (!startWorker(state, profile, keyString, effects, now)) return false;
   }
   binding.last_activity_at = now;
   const text = `[scheduled: ${job.name ?? job.id}] ${prompt}`;

package/gates.mjs

@@ -78,7 +78,7 @@ function scriptEnv() {
  * else with python3; the cwd is the job's workdir, else the scripts folder.
  * Returns `{ok, output}`; a failure's output is the reason, in Hermes's words.
  */
-export async function runJobScript(profile, scriptPath, workdir = null, { env = process.env, signal = null, secrets = [] } = {}) {
+export async function runJobScript(profile, scriptPath, workdir = null, { env = process.env, signal = null, secrets = [], automation = null } = {}) {
   const raw = String(scriptPath ?? '');
   if (raw.includes('\0')) return { ok: false, output: `Blocked: script path contains a NUL byte: ${JSON.stringify(raw)}` };
   const scriptsDir = join(profile.dir, 'scripts');
@@ -100,7 +100,8 @@ export async function runJobScript(profile, scriptPath, workdir = null, { env =
     const out = { stdout: [], stderr: [] };
     const size = { stdout: 0, stderr: 0 };
     let finished = false;
-    const child = spawn(argv[0], argv[1], { cwd, env: { ...scriptEnv(), HERMES_HOME: profile.dir }, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    // A scheduled script is an automation: what it files names the automation, never an agent or the OS user (C4)
+    const child = spawn(argv[0], argv[1], { cwd, env: { ...scriptEnv(), HERMES_HOME: profile.dir, ...(automation ? { SUPERCODE_AUTOMATION: automation } : {}) }, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
     const kill = () => { try { process.kill(-child.pid, 'SIGKILL'); } catch { /* already gone */ } };
     const end = (result) => {
       if (finished) return;

package/hermes-cli.mjs

@@ -40,7 +40,10 @@ export function hermesInstall() {
 export function hermesToolEnv(profileDir) {
   const install = hermesInstall();
   const env = { HERMES_HOME: profileDir };
-  if (install?.bin) env.PATH = `${install.bin}:${process.env.PATH ?? ''}`;
+  // Hermes's folder may hold other programs (a global supercode beside it): the worker's `supercode` stays the one
+  // this daemon runs, ahead of it
+  const own = process.env.SUPERCODE_BIN ? dirname(process.env.SUPERCODE_BIN) : null;
+  if (install?.bin) env.PATH = [own, install.bin, process.env.PATH ?? ''].filter(Boolean).join(':');
   return env;
 }
 
@@ -102,7 +105,12 @@ elif op in ("allow", "revoke"):
             save_env_value(var, ",".join(current + [a["user_id"]]))
     else:
         store.revoke(a["platform"], a["user_id"])
-        _sync_allowlist_remove(a["platform"], a["user_id"])
+        if _allowlist_env_for_platform(a["platform"]):
+            _sync_allowlist_remove(a["platform"], a["user_id"])
+        elif a["user_id"] in current:
+            # a platform Hermes does not name (rh2) keeps its list where allow wrote it; Hermes's remover returns early
+            from hermes_cli.config import save_env_value
+            save_env_value(var, ",".join(x for x in current if x != a["user_id"]))
     out = True
 elif op in ("admin_add", "admin_remove"):
     from hermes_cli.config import load_config, save_config
@@ -341,6 +349,15 @@ export async function memorySnapshot(profileDir) {
   return runHermes(profileDir, { op: 'snapshot' });
 }
 
+/** memorySnapshot for a synchronous caller (the board's launch). An unreadable store contributes nothing. */
+export function memorySnapshotSync(profileDir) {
+  const install = hermesInstall();
+  if (!install?.python) return '';
+  const run = spawnSync(install.python, ['-c', HERMES_TOOL], { input: JSON.stringify({ op: 'snapshot' }), encoding: 'utf8', timeout: 30_000, cwd: install.source, env: hermesEnv(install, profileDir) });
+  try { const out = hermesAnswer('snapshot', { stdout: run.stdout ?? '', stderr: run.stderr || run.error?.message || '' }); return typeof out === 'string' ? out : ''; }
+  catch { return ''; }
+}
+
 /**
  * A schedule string as Hermes parses it (`{ kind: once|interval|cron, … }`), or null when no Hermes is
  * installed; throws Hermes's own refusal. Synchronous: schedules are parsed where a job is built.

package/index.d.ts

@@ -101,6 +101,43 @@ export type UserId = string;
 export type JobId = string;
 export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
 
+// C7 host APIs refer to the neutral Teams identity contract. Profile records remain the ontology's.
+export type AgentIdentity = import('@volter/teams/http-client').AgentRecord;
+export function resolveAgentProfile(profiles: Record<string, Profile>, name: string, overlays?: Array<Record<string, unknown>>): {profile: string; layers: string[]; resolved: Record<string, unknown>};
+export function profileDifferences(intended: unknown, actual: unknown): Array<{field: string; intended: unknown; actual: unknown}>;
+export function sessionAgent(options: {starter?: {kind?: string; id?: string; agent?: string | null}; declared?: string | null; asAgent?: string | null; profileAgent?: string | null}): string | null;
+export function agentStateHome(root: Path, org: string, id: string): Path;
+export function recordNativeAgentSession(root: Path, runtimeRef: string, session: string): Record<string, unknown> | null;
+export function materializeAgentHome(root: Path, org: string, id: string, profile: Profile): Path;
+export function declareAgentIntent(options: {root: Path; org: string; server: string; profiles: Record<string, Profile>; profile: string; key: string; machine?: string | null}): Record<string, unknown>;
+export function ensureRootAgent(options: {root: Path; org: string; server: string; profiles: Record<string, Profile>; profile?: string; context?: string; machine?: string | null}): AgentIdentity;
+export function ensureCardAgent(options: {root: Path; org: string; server: string; profiles: Record<string, Profile>; profile: string; card: string; role: string; sponsor?: string | null; context?: string; machine?: string | null; starterSession?: string | null}): {identity: AgentIdentity; intended: ReturnType<typeof resolveAgentProfile>; assignment: string; assignments: Array<Record<string, unknown>>; org: string};
+export function ensureProfileAgent(options: {root: Path; org: string; server: string; profiles: Record<string, Profile>; profile: string; context?: string; machine?: string | null}): ReturnType<typeof ensureCardAgent>;
+export function ensureForkAgent(options: {root: Path; org: string; server: string; profiles: Record<string, Profile>; parent: string; session: string; name: string; key: string; context?: string; machine?: string | null}): ReturnType<typeof ensureCardAgent>;
+export function agentRunForKey(root: Path, org: string, agent: string, key: string): Record<string, unknown> | null;
+export function agentIntent(root: Path, org: string, id: string): Record<string, unknown> | null;
+export function assignAgent(root: Path, org: string, id: string, assignment: {kind: string; target: string; role: string}): string;
+export function reassignAgent(root: Path, org: string, assignment: string, to: string, options?: {context?: string}): Record<string, unknown>;
+export function activeAgentAssignments(root: Path): Array<Record<string, unknown>>;
+export function finishAgentAssignment(root: Path, org: string, assignment: string, reason: string): void;
+export function synchronizeAgentEnds(root: Path, org: string, options?: {context?: string}): Array<{agent: string; error: string}>;
+export function recordAgentRun(root: Path, org: string, id: string, run: {session: string; machine?: string | null; run: string | number; profile?: unknown; main?: boolean; starterSession?: string | null}): void;
+export function pendingAgentRuns(root: Path, org: string): Array<Record<string, unknown>>;
+export function synchronizeAgentRun(root: Path, org: string, row: {agent_id: string; session_ref: string; machine?: string | null; main?: boolean | number; starter_session?: string | null}, options?: {context?: string; intended?: unknown}): import('@volter/teams/http-client').SessionIdentity & {runtime: unknown};
+export function agentRunForSession(root: Path, references: Array<string | null | undefined>): Record<string, unknown> | null;
+export function agentPreamble(agent: ReturnType<typeof ensureCardAgent>, options?: {main?: boolean; previous?: Array<{session: string; machine?: string | null; ended_at?: number | null; end_reason?: string | null}>}): string;
+export function agentEnvironment(agent: ReturnType<typeof ensureCardAgent>, options: {root: Path; context?: string; session?: string | null; main?: boolean}): Record<string, string>;
+/** The Org for agent identity; `offline` when no Teams context is selected or reachable (situation 16). */
+export function agentScope(context?: string): {server: string; org: string; principal: string | null; offline?: true; reason?: string};
+export function teamsUnavailable(error: unknown): boolean;
+/** Locally minted identities (`identity.synced === false`), declared later under the same id. */
+export function localCardAgent(options: Parameters<typeof ensureCardAgent>[0]): ReturnType<typeof ensureCardAgent> & {synced: false};
+export function localProfileAgent(options: Parameters<typeof ensureProfileAgent>[0]): ReturnType<typeof ensureCardAgent> & {synced: false};
+export function localAgentRecord(root: Path, org: string, id: string): ReturnType<typeof ensureCardAgent> | null;
+export function localAgentSessions(root: Path, org: string, id: string): Array<{session: string; machine: string | null; ended_at: number | null; end_reason: string | null}>;
+export function synchronizeLocalAgents(options: {root: Path; profiles: Record<string, Profile>; context?: string; machine?: string | null}): Array<{agent: string; error: string}>;
+export function agentProfileMismatch(intent: unknown, resolved: unknown): import('@volter/teams/agent-profile').ProfileComparison;
+
 export type ChatType = 'dm' | 'group' | 'channel' | 'thread';
 
 export interface RuntimeState {
@@ -137,6 +174,8 @@ export type OrchestratorEvent =
       text: string; attachments: Attachment[]; at: Instant; adapter: Platform; guild_id: string | null;
       /** The platform's id for this message: the threading, reaction and edit target (ORC-1 F4). */
       message_id: string | null;
+      /** Enriched from the public identity record by the loop; never trusted from an adapter. */
+      identity?: Awaited<ReturnType<import('@volter/teams/http-client').TeamClient['identity']['resolve']>>['data'];
       /** Our own echo (§4.1 step 0 drops it), a bot sender (`null` = the SDK's "unknown"), and whether we were @-mentioned. */
       is_me: boolean; is_bot: boolean | null; mention: boolean;
     }
@@ -173,7 +212,7 @@ export function expired(binding: Binding, reset: SessionReset, now: Instant): En
 export function leaseId(profile: ProfileName, keyString: string): string;
 
 export namespace events {
-  function inbound(fields: Omit<Extract<OrchestratorEvent, { type: 'inbound' }>, 'type' | 'attachments' | 'adapter' | 'guild_id' | 'sender_name' | 'message_id' | 'is_me' | 'is_bot' | 'mention'> & { attachments?: Attachment[]; adapter?: Platform; guild_id?: string | null; sender_name?: string | null; message_id?: string | null; is_me?: boolean; is_bot?: boolean | null; mention?: boolean }): Extract<OrchestratorEvent, { type: 'inbound' }>;
+  function inbound(fields: Omit<Extract<OrchestratorEvent, { type: 'inbound' }>, 'type' | 'identity' | 'attachments' | 'adapter' | 'guild_id' | 'sender_name' | 'message_id' | 'is_me' | 'is_bot' | 'mention'> & { attachments?: Attachment[]; adapter?: Platform; guild_id?: string | null; sender_name?: string | null; message_id?: string | null; is_me?: boolean; is_bot?: boolean | null; mention?: boolean }): Extract<OrchestratorEvent, { type: 'inbound' }>;
   function tick(at: Instant, inactivity_s?: number | null, max_parallel?: number | null): Extract<OrchestratorEvent, { type: 'tick' }>;
   function worker(fields: Omit<Extract<OrchestratorEvent, { type: 'worker' }>, 'type'>): Extract<OrchestratorEvent, { type: 'worker' }>;
   function adapterStatus(fields: Omit<Extract<OrchestratorEvent, { type: 'adapter' }>, 'type' | 'error'> & { error?: string | null }): Extract<OrchestratorEvent, { type: 'adapter' }>;
@@ -184,7 +223,7 @@ export namespace events {
 }
 
 export function parseCommand(text: string): { name: string; args: string } | null;
-export function frame(profile: ProfileName, key: SurfaceKey, sender: UserId, senderName: string | null, at: Instant, text: string): string;
+export function frame(profile: ProfileName, key: SurfaceKey, sender: UserId, senderName: string | null, at: Instant, text: string, identity?: Extract<OrchestratorEvent,{type:'inbound'}>['identity'] | null): string;
 export const COMMANDS: Set<string>;
 export const REPLY: Record<string, string | ((arg: string) => string)>;
 
@@ -301,6 +340,8 @@ export class Orchestrator {
   stop(): Promise<void>;
   tick(at?: Instant): Promise<Effect[]>;
   drainHosted(): Promise<void>;
+  /** A fork starts in a registered, unoccupied conversation on this execution host. */
+  forkRuntime(options: {profile: ProfileName; keyString: string; parent: string; locator: import('@volter/supercode-harness-sdk').SessionLocator; name: string; key: string; machine?: string | null}): Promise<{agent: AgentIdentity; locator: import('@volter/supercode-harness-sdk').SessionLocator; runtime: unknown}>;
   dispatch(event: OrchestratorEvent): Promise<Effect[]>;
   enqueue(event: OrchestratorEvent): void;
   /** §7: effects produced by an MCP tool call, run on the loop's own queue. */

package/index.mjs

@@ -36,3 +36,7 @@ export { LOCK_FILE, thisHost, pidIsLive, leaseIsHere, leaseIsLive, readLease } f
 export { adoptHome, adoptPersona, adoptSkills, managedSkills, skillSources, profileDirs, AGENTS_SKILLS } from './hermes-home.mjs';
 export { hermesAccess, recordIncident, hermesToolEnv, hermesInstall } from './hermes-cli.mjs';
 export { holdGatewayLock, gatewayLockHeld, acquireTokenLock, releaseTokenLock, looksLikeGateway, TOKEN_SCOPES } from './hermes-locks.mjs';
+
+export { resolveAgentProfile, profileDifferences, sessionAgent } from "./agent-profiles.mjs";
+export { agentScope, teamsUnavailable, localCardAgent, localProfileAgent, localAgentRecord, localAgentSessions, synchronizeLocalAgents, declareAgentIntent, ensureRootAgent, ensureCardAgent,ensureProfileAgent,ensureForkAgent,agentRunForKey, agentIntent, assignAgent, reassignAgent,activeAgentAssignments,finishAgentAssignment,synchronizeAgentEnds,recordAgentRun, recordNativeAgentSession,pendingAgentRuns, synchronizeAgentRun, agentRunForSession,agentPreamble, agentEnvironment, agentProfileMismatch } from "./agents.mjs";
+export { agentStateHome,materializeAgentHome } from './agent-home.mjs';