@volter/supercode-orchestrator 0.5.169 → 0.5.171

package/board/args.mjs

@@ -3,7 +3,7 @@ import { resolve } from 'node:path';
 
 export const MULTI = new Set(['parent', 'skill', 'worker', 'child', 'ids', 'rm', 'tag', 'pr', 'pr-head', 'reviewed-sha', 'finding']);
 export const FLAGS = new Set(['json', 'triage', 'no-notify', 'no-start', 'all', 'force', 'help', 'mine', 'archived', 'reclaim', 'dry-run',
-  'once', 'goal', 'no-goal', 'off', 'switch', 'delete', 'no-attachments', 'include-logs', 'verbose', 'commit']);
+  'once', 'goal', 'no-goal', 'off', 'switch', 'delete', 'no-attachments', 'include-logs', 'verbose', 'commit', 'side']);
 // flags that take every following word up to the next flag (Hermes's nargs='+')
 export const GREEDY = new Set(['ids', 'rm']);
 

package/board/cli.mjs

@@ -66,6 +66,7 @@ async function boardPublishing(root) {
 }
 import { dispatchingOf, knowLocalMachine, requestAdoption, alertManagers, boardAddress, boardLabel, boardSettings, boardCaller, callerSession, commandEnv, reconcileCallerLaunch, closeRequested, lanesOf, localMachine, observeFleet, paused, plan, startCard, stopDispatching, supercodeBin, tick, deliver, startDelivery } from './dispatch.mjs';
 import { watchBoard } from './wake.mjs';
+import { attachSideSession, releaseSideSession, sideArcs, sideSessions } from './side-sessions.mjs';
 import { onPanesChanged } from './machine-fleet.mjs';
 import { streamBoardPublications } from './event-stream.mjs';
 import { completionOwnerOf, followHome, isLatestReviewer, loadWorkflow, readHome, requestSessionClose, scopeOf, statusOf, useWorkflow, workflowEntry, workflowFor } from './workflow.mjs';
@@ -127,7 +128,7 @@ And:
   create … --machine M --subtask-of ARC --notify ADDRESS|--no-notify --no-start
       With a pane lane and room, a card starts at once and answers "started" with its session; else it answers why it
       waits, and its creator is told when it starts. A subtask is worked by its arc's session and never starts alone.
-  adopt <id> <session> [--assignee P] [--role ROLE]   close <id>   serve (= daemon)   list --machine M
+  adopt <id> <session> [--assignee P] [--role ROLE]   adopt <arc> <session> --side · release <arc> <session>   close <id>   serve (= daemon)   list --machine M
   notify-subscribe <id> --address sc:<machine>:<harness>:<id> [--role creator|worker|dependency]
   notify-subscribe <dependency> --for-card <your-arc>: subscribe only your arc's session to dependency notices.
   notify-unsubscribe <dependency> --for-card <your-arc>: remove that arc's subscription only.
@@ -145,7 +146,8 @@ And:
   request-state <id>... --state STATE --reason REASON: request several decisions in one retained manager mail.
   complete <id>: creator/manager accepts the independently reviewed arc; deployment CI is not a board gate.
   specify/decompose with no spec start a session on the triage card to write it. A card's own session may comment on,
-  heartbeat and request review of its card, specify or decompose it in triage, and work its subtasks. The home's
+  heartbeat and request review of its card, specify or decompose it in triage, and work its subtasks. A side session
+  (adopt --side) works the arc's subtasks and comments on the arc; the arc's run and state stay its main session's. The home's
   workflow declares who may block, pause or finish a card; request-state mails its manager without changing state.
 `;
 
@@ -365,13 +367,15 @@ export async function runVerb(argv) {
   if (sid && !READS.has(verb) && boardExists(root, slug)) {
     // binding the caller's launch is a write: only the owner, answering the caller's own verb, makes it (a local read
     // never writes)
-    await withBoardAsync(async (b) => { if (isCallersCall()) await reconcileCallerLaunch(b, sid); const own = ownCards(b.db, sid); if (own.worked.size) authorize(b.db, verb, rest, args, own); });
+    await withBoardAsync(async (b) => { if (isCallersCall()) await reconcileCallerLaunch(b, sid); const own = { ...ownCards(b.db, sid), side: sideArcs(b.db, sid) }; if (own.worked.size || own.side.size) authorize(b.db, verb, rest, args, own); });
   }
   // the board's workflow (the IR's): what each verb does, and who may send it, is its
   // every verb reads the board through its workflow (a list settles cards too), so every verb loads it
   engine.setCaller((db, cardId) => {
     const roles = rolesFor(db, cardId, sid, workflowFor(root).params);
     if (verb === 'comment' && isLatestReviewer(db, cardId, actorOf()) && !roles.includes('reviewer')) roles.push('reviewer');
+    // a side session comments on its arc as the arc's (its subtasks it works as `arc` through rolesFor)
+    if (verb === 'comment' && sid && !roles.includes('arc') && sideSessions(db, cardId).some((s) => s.session === sid)) roles.push('arc');
     return roles;
   });
   // A plain terminal acts as its signed-in person; an offline OS label grants no creator authority.
@@ -542,7 +546,7 @@ export async function runVerb(argv) {
       const t = card.task;
       const latest = [...card.runs].reverse().find((r) => r.summary)?.summary ?? null;
       if (args.json) {
-        say(args, '', { task: cardDict(t), latest_summary: latest, parents: card.parents.map((p) => p.id), children: card.children, subtasks: card.subtasks, comments: card.comments, events: card.events, runs: card.runs, time: card.time, subscriptions: card.subscriptions, diagnostics: card.diagnostics });
+        say(args, '', { task: cardDict(t), side_sessions: withBoard((b) => sideSessions(b.db, t.id)), latest_summary: latest, parents: card.parents.map((p) => p.id), children: card.children, subtasks: card.subtasks, comments: card.comments, events: card.events, runs: card.runs, time: card.time, subscriptions: card.subscriptions, diagnostics: card.diagnostics });
         return 0;
       }
       const out = [`Task ${t.id}: ${t.title}`, `  status:    ${taskStatusOf(card.stage, t.completed_at)} (lane ${card.stage}${card.stage !== t.status ? `, ${t.status} in kanban.db` : ''})`, `  assignee:  ${t.assignee || '-'}`];
@@ -572,6 +576,8 @@ export async function runVerb(argv) {
       if (card.parents.length) out.push(`  parents:   ${card.parents.map((p) => p.id).join(', ')}`);
       if (card.children.length) out.push(`  children:  ${card.children.join(', ')}`);
       if (card.subtasks.length) out.push(`  subtasks:  ${card.subtasks.map((s) => `${s.id} (${s.status})`).join(', ')}`);
+      const side = withBoard((b) => sideSessions(b.db, t.id));
+      if (side.length) out.push(`  side sessions: ${side.map((s) => s.address).join(', ')}`);
       if (t.body) out.push('', 'Body:', t.body);
       if (t.result) out.push('', 'Result:', t.result);
       else if (latest) out.push('', 'Latest summary:', latest);
@@ -847,7 +853,7 @@ export async function runVerb(argv) {
           const children = args.child.map((c) => { const [title, assignee] = c.split(/@(?=[^@]*$)/); return { title: title.trim(), assignee: assignee?.trim() || undefined }; });
           results.push({ id: t, children: await withBoardAsync((b) => engine.decompose(b, t, children, { author: args.author ?? callerAddress() ?? callerName() })) });
         } else {
-          const session = await withBoardAsync((b) => startCard(b, t, { lanes, settings }));
+          const session = await withBoardAsync((b) => startCard(b, t, { lanes, settings, roles: rolesFor(b.db, t, sid, workflowFor(root).params) }));
           results.push({ id: t, session: session.address, mode: session.mode });
         }
       }
@@ -1114,10 +1120,22 @@ export async function runVerb(argv) {
     case 'adopt': {
       need(2, 'a card id and a session');
       withBoard(b => { if (!rolesFor(b.db, id, sid, workflowFor(root).params).includes('manager')) throw new Error('Only the manager adopts an existing session.'); });
+      if (args.side) {
+        withBoard((b) => attachSideSession(b, id, rest[1]));
+        say(args, `${rest[1]} is a side session of ${id}: it works ${id}'s subtasks and comments on ${id}; ${id}'s run and state stay its main session's`, { ok: true, side: rest[1] });
+        return 0;
+      }
       withBoard((b) => requestAdoption(b, id, rest[1], { workspace: args.workspace ?? null, assignee: args.assignee ?? null, role: args.role ?? null }));
       say(args, `${id} is held for ${rest[1]}; the dispatcher verifies and binds it on its next tick (session_adopted, or adoption_failed with the reason)`, { ok: true, requested: rest[1] });
       return 0;
     }
+    case 'release': {
+      need(2, 'a card id and its side session');
+      withBoard(b => { if (!rolesFor(b.db, id, sid, workflowFor(root).params).includes('manager')) throw new Error('Only the manager releases a side session.'); });
+      withBoard((b) => releaseSideSession(b, id, rest[1]));
+      say(args, `${rest[1]} is no longer a side session of ${id}`, { ok: true, released: rest[1] });
+      return 0;
+    }
     case 'goto': {
       need(2, 'a card id and the status to take it to');
       const { _: _words, root: _r, board: _b, json: _j, at: _a, ...fields } = args;
@@ -1429,7 +1447,8 @@ function agentMain(address) { return current().agentMains.get(address) ?? null;
 /**
  * Who a caller is on card `cardId`, in the workflow's roles: a signed-in terminal person retains their creator role;
  * the manager acts from its named session; the session of the card's current run has that run's role; the card's working session between runs
- * is its `implementer`; the session working a subtask's arc is `arc`; its recorded creator also has the creator role; any other session is nobody on it.
+ * is its `implementer`; the session working a subtask's arc, and each side session attached to that arc, is `arc`; its recorded creator also has the
+ * creator role; any other session is nobody on it.
  */
 function rolesFor(db, cardId, sessionId, params = {}) {
   // a session the workflow names as the board's manager (params.managers: its addresses) is the manager on every card
@@ -1447,27 +1466,32 @@ function rolesFor(db, cardId, sessionId, params = {}) {
   if (task.subtask_of) {
     const parent = engine.getTask(db, task.subtask_of);
     const worker = parent?.current_run_id ? engine.currentRun(db, parent.id)?.metadata?.supercode : engine.lastSession(db, task.subtask_of);
-    if (worker?.session_id === sessionId) roles.push('arc');
+    if (worker?.session_id === sessionId || sideSessions(db, task.subtask_of).some((s) => s.session === sessionId)) roles.push('arc');
   }
   return roles;
 }
 
+/**
+ * What a session that works a card, or is a side session of an arc (`own.side`), may name: its own cards and their
+ * subtasks, and the subtasks of the arcs it is a side session of, and those arcs themselves only to comment on. What it
+ * may do to them is the workflow's (rolesFor).
+ */
 function authorize(db, verb, rest, args, own) {
-  const cards = [...own.worked];
+  const cards = [...new Set([...own.worked, ...own.side])];
   const named = cards.join(', ');
   const refuse = (why) => { throw new Error(`the session working ${named} ${why}`); };
   if (verb === 'create') {
-    if (!own.worked.has(args['subtask-of'])) refuse(`files subtasks of its own card only (--subtask-of ${cards.join(' or ')})`);
+    if (!own.worked.has(args['subtask-of']) && !own.side.has(args['subtask-of'])) refuse(`files subtasks of its own card only (--subtask-of ${cards.join(' or ')})`);
     return;
   }
   if (verb === 'boards') { if (!['list', 'ls', 'show', 'current', undefined].includes(rest[0])) refuse('does not change the home\'s boards'); return; }
   // verbs that act on the board rather than on a card are the manager's and the board's, never a card's session's
   // (what a session may do to a card is its workflow's: each transition's `by`)
-  if ((['pause', 'resume'].includes(verb) && !rest[0]) || ['swarm', 'dispatch', 'daemon', 'serve', 'gc', 'repair', 'adopt', 'close', 'claim', 'attach-rm', 'migrate'].includes(verb)) refuse(`does not ${verb}; the fleet's manager does`);
+  if ((['pause', 'resume'].includes(verb) && !rest[0]) || ['swarm', 'dispatch', 'daemon', 'serve', 'gc', 'repair', 'adopt', 'release', 'close', 'claim', 'attach-rm', 'migrate'].includes(verb)) refuse(`does not ${verb}; the fleet's manager does`);
   if (verb === 'set' && !(own.worked.has(rest[0]) && rest[1] === 'every')) refuse("sets only Every on its own auditor card; other properties are the manager's");
   if (args.all) refuse(`does not ${verb} every card; only its own`);
   if (['notify-subscribe', 'notify-unsubscribe'].includes(verb) && args['for-card']) {
-    if (!own.worked.has(args['for-card'])) refuse(`subscribes only its own arc (--for-card ${cards.join(' or ')})`);
+    if (!own.worked.has(args['for-card'])) refuse(`subscribes only its own arc (--for-card ${[...own.worked].join(' or ')})`);
     return;
   }
   const targets = verb === 'request-state' ? [...rest, ...(args.ids ?? [])] : [rest[0], ...(args.ids ?? [])];
@@ -1477,7 +1501,9 @@ function authorize(db, verb, rest, args, own) {
     if (isCaller(completionOwnerOf(db, card.id))) continue;
     if (verb === 'comment' && isLatestReviewer(db, card.id, actorOf())) continue;
     // the card it names is the one it addresses: any card it holds, or a subtask of one it works
-    if (!own.held.has(card.id) && !own.worked.has(card.subtask_of)) refuse(`writes only its own card${cards.length > 1 ? 's' : ''} and ${cards.length > 1 ? 'their' : 'its'} subtasks, not ${card.id}`);
+    // a side session names its arc only to comment on it; the arc's other verbs are its main session's
+    if (own.side.has(card.id) && !own.held.has(card.id) && verb !== 'comment') refuse(`only comments on ${card.id}, which it is a side session of; the arc's other verbs are its main session's and the manager's`);
+    if (!own.held.has(card.id) && !own.worked.has(card.subtask_of) && !own.side.has(card.id) && !own.side.has(card.subtask_of)) refuse(`writes only its own card${cards.length > 1 ? 's' : ''} and ${cards.length > 1 ? 'their' : 'its'} subtasks, not ${card.id}`);
   }
 }
 

package/board/side-sessions.mjs

@@ -0,0 +1,73 @@
+// Side sessions: an arc keeps its one main session (its run, its driver), and the manager may attach other sessions
+// beside it for parts of the arc (`adopt <arc> <session> --side`, `release <arc> <session>`). A side session is bound
+// to no run and to no machine (the card's machine is its main session's); it holds the `arc` role on the arc's
+// subtasks (file, comment on, complete or drop them) and may comment on the arc card, and nothing else of the arc's
+// own: its state, its run and its review stay the main session's and the manager's. An arc that ends (done or
+// cancelled) releases its side sessions in the same transaction.
+//
+// The live attachments are rows of `supercode_side_sessions`, keyed by arc and session and indexed by session, so the
+// question every verb a session runs asks ("which arcs is this session a side session of?") reads only its own rows.
+// Each attach and release is also recorded on the arc as an event (`side_session_attached`, `side_session_released`).
+import { boardCopyOf, copyRefusal, event, tx } from './store.mjs';
+import { currentRun, getTask, lastSession } from './engine.mjs';
+
+const TABLE = 'supercode_side_sessions';
+const SCHEMA = `CREATE TABLE IF NOT EXISTS ${TABLE} (task_id TEXT NOT NULL, session TEXT NOT NULL, address TEXT NOT NULL, PRIMARY KEY (task_id, session));
+CREATE INDEX IF NOT EXISTS idx_side_sessions_session ON ${TABLE}(session);`;
+// a read never writes: a board with no attachment yet has no table, and reads as none
+const present = (db) => Boolean(db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(TABLE));
+
+/** A harness session's address, `sc:<machine>:<harness>:<id>`, as `{ session, address }`; refused for anything else. */
+function sessionAddress(who) {
+  const address = String(who ?? '').trim();
+  const m = /^sc:([^:\s]+):([^:\s]+):([^:\s]+)$/.exec(address);
+  if (!m || ['agent', 'board', 'operator'].includes(m[2])) throw new Error(`a side session is named by its harness session address, sc:<machine>:<harness>:<id>, not ${address || 'nothing'}`);
+  return { session: m[3], address };
+}
+
+export function attachSideSession(board, id, who) {
+  const { session, address } = sessionAddress(who);
+  if (boardCopyOf(board)) throw copyRefusal(board, 'attaches no session');
+  tx(board, (db) => {
+    const card = getTask(db, id);
+    if (!card) throw new Error(`no card ${id}`);
+    if (card.subtask_of) throw new Error(`${id} is a subtask of ${card.subtask_of}; attach the side session to the arc, ${card.subtask_of}`);
+    // its main session: the current run's (any slot) and the card's last worker (its implementer while a review runs)
+    const main = [card.current_run_id ? currentRun(db, id)?.metadata?.supercode?.session_id : null, lastSession(db, id)?.session_id];
+    if (main.includes(session)) throw new Error(`${address} is ${id}'s main session; a side session is another session beside it`);
+    if (sideSessions(db, id).some((s) => s.session === session)) throw new Error(`${address} is already a side session of ${id}`);
+    db.exec(SCHEMA);
+    db.prepare(`INSERT INTO ${TABLE} (task_id, session, address) VALUES (?, ?, ?)`).run(id, session, address);
+    event(db, id, 'side_session_attached', { session, address });
+  });
+}
+
+export function releaseSideSession(board, id, who) {
+  const { session, address } = sessionAddress(who);
+  if (boardCopyOf(board)) throw copyRefusal(board, 'releases no session');
+  tx(board, (db) => {
+    if (!getTask(db, id)) throw new Error(`no card ${id}`);
+    if (!sideSessions(db, id).some((s) => s.session === session)) throw new Error(`${address} is no side session of ${id}`);
+    db.prepare(`DELETE FROM ${TABLE} WHERE task_id = ? AND session = ?`).run(id, session);
+    event(db, id, 'side_session_released', { session, address });
+  });
+}
+
+/** Release every side session of arc `id`, in the caller's transaction (the arc ended: `reason`). */
+export function releaseAllSideSessions(db, id, reason) {
+  for (const s of sideSessions(db, id)) {
+    db.prepare(`DELETE FROM ${TABLE} WHERE task_id = ? AND session = ?`).run(id, s.session);
+    event(db, id, 'side_session_released', { session: s.session, address: s.address, reason });
+  }
+}
+
+/** The side sessions attached to arc `id` now: `{ session, address }` each. */
+export function sideSessions(db, id) {
+  return present(db) ? db.prepare(`SELECT session, address FROM ${TABLE} WHERE task_id = ? ORDER BY rowid`).all(id).map((r) => ({ session: r.session, address: r.address })) : [];
+}
+
+/** The arcs session `sessionId` is a side session of now. */
+export function sideArcs(db, sessionId) {
+  if (!sessionId || !present(db)) return new Set();
+  return new Set(db.prepare(`SELECT task_id FROM ${TABLE} WHERE session = ?`).all(sessionId).map((r) => r.task_id));
+}

package/board/workflow.mjs

@@ -13,6 +13,7 @@ import { existsSync, readdirSync, realpathSync, watch, readFileSync } from 'node
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { actorOf, appendRunObservation, event as record, json, now } from './store.mjs';
+import { releaseAllSideSessions } from './side-sessions.mjs';
 import { evaluate, holds, render } from './expr.mjs';
 import { completionEvidence, declaredWorkBranches, namedWorkBranch, reviewCandidate } from './ci.mjs';
 import { cardCommitsOn, isLocalWorkspace, isWorkspacePath } from './workspace.mjs';
@@ -682,6 +683,8 @@ export function setStatus(db, workflow, id, status) {
   run(db, 'UPDATE tasks SET status = ? WHERE id = ?', stored, id);
   run(db, `INSERT INTO supercode_cards (task_id, stage, since, after_fired) VALUES (?, ?, ?, NULL)
            ON CONFLICT(task_id) DO UPDATE SET stage = excluded.stage, since = excluded.since, after_fired = NULL`, id, stored === status ? null : status, now());
+  // an arc that ends releases its side sessions with it (side-sessions.mjs)
+  if (['done', 'archived'].includes(stored) && !db.prepare('SELECT subtask_of FROM supercode_cards WHERE task_id = ?').get(id)?.subtask_of) releaseAllSideSessions(db, id, `${id} is ${status}`);
 }
 
 /** Take every `always` transition that holds, from wherever the card is, until none does. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.169",
+  "version": "0.5.171",
   "type": "module",
   "description": "The orchestrator runtime over the Volter Harness ontology: one typed operational model whose folder is its serialization, read and written through the harness orchestration doors (docs/ORCHESTRATOR-IR.md)",
   "exports": {
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@volter/supercode-harness-sdk": "^0.3.100",
-    "@volter/teams": "0.2.71",
+    "@volter/teams": "0.2.72",
     "@volter/ztrack": "^2.4.23",
     "yaml": "^2.9.0"
   },