@volter/supercode-orchestrator 0.5.123 → 0.5.125

package/board/cli.mjs

@@ -26,7 +26,7 @@ import * as slowLog from '@volter/supercode-harness-sdk/slow-log';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir, tmpdir, userInfo } from 'node:os';
-import { actorOf, heldConfigWatched, heldDocumentsChanged, heldDocumentsWatched, holdBoards, retireHeldBoards, releaseHeldBoards, publishMarked, view, backingPaths, layOut, backingOf, boardExists, boardPath, DEFAULT_BOARD, event, json, listBoards, logsDir, now, openBoard, setActor, setPrincipal, principalOf, isCaller, tx } from './store.mjs';
+import { actorOf, heldConfigWatched, heldDocumentsChanged, heldDocumentsWatched, holdBoards, retireHeldBoards, releaseHeldBoards, publishMarked, view, backingPaths, layOut, backingOf, boardExists, boardPath, briefPath, DEFAULT_BOARD, event, json, listBoards, logsDir, now, openBoard, setActor, setPrincipal, principalOf, isCaller, tx } from './store.mjs';
 import { isLocalWorkspace } from './workspace.mjs';
 import { openZtrackBoard } from './ztrack.mjs';
 import * as engine from './engine.mjs';
@@ -90,7 +90,7 @@ The board's verbs, with their flags:
          [--tenant] [--priority] [--triage] [--idempotency-key] [--max-runtime 30m] [--created-by] [--skill]... [--max-retries]
          [--model] [--provider] [--goal|--no-goal] [--goal-max-turns] [--initial-status blocked|running]
   swarm <goal> --worker PROFILE:TITLE[:SKILL,SKILL]... --verifier P --synthesizer P
-  list [--mine] [--assignee] [--status] [--tenant] [--session] [--archived] [--sort]   show <id>   context <id>   runs <id>
+  list [--mine] [--assignee] [--status] [--tenant] [--session] [--archived] [--sort]   show <id>   context <id>   brief <id> [--run N]   runs <id>
   set <id> <assignee|machine|model|every> <value|none> [--provider] [--ids ...]   assign <id> <profile|none>   set-model <id> [model] [--provider]   set-goal <id>... [--goal-max-turns N] [--off]
   reassign <id> --agent AGENT [--role implementer]   (moves a card role's assignment to another agent; sessions keep their identity)
   claim <id> [--ttl]   reclaim <id> [--reason]   heartbeat <id> [--note] [--until <time|30m>]   link|unlink <parent> <child>
@@ -634,6 +634,15 @@ export async function runVerb(argv) {
       return 0;
     }
 
+    case 'brief': {
+      need(1, 'a card id');
+      const run = args.run ?? withBoard((b) => view(b, (db) => engine.getTask(db, id)?.current_run_id));
+      const file = run == null ? null : briefPath(root, slug, id, run);
+      if (!file || !existsSync(file)) throw new Error(`the board keeps no brief for ${run == null ? 'a run' : `run ${run}`} of ${id}`);
+      current().out(readFileSync(file, 'utf8'));
+      return 0;
+    }
+
     case 'context': need(1, 'a card id'); current().out(`${withBoard((b) => view(b, (db) => engine.cardContext(db, id)))}\n`); return 0;
 
     case 'runs': {
@@ -1374,7 +1383,7 @@ function ownCard(db, sessionId) {
   return engine.lastSession(db, hit.task_id)?.session_id === sessionId ? engine.getTask(db, hit.task_id) : null;
 }
 
-const READS = new Set(['list', 'ls', 'show', 'context', 'runs', 'log', 'tail', 'watch', 'stats', 'assignees', 'diagnostics', 'diag', 'attachments', 'notify-list', 'capacity', 'help', 'init']);
+const READS = new Set(['list', 'ls', 'show', 'context', 'brief', 'runs', 'log', 'tail', 'watch', 'stats', 'assignees', 'diagnostics', 'diag', 'attachments', 'notify-list', 'capacity', 'help', 'init']);
 
 /** The main session of each agent the workflow names a manager (`sc:<machine>:agent:<name>`), asked of this machine's
  *  daemon, which keeps agents' records (mail step 1c), once per call before its verb runs: a manager named by its agent

package/board/dispatch.mjs

@@ -39,7 +39,7 @@ import { homedir, hostname, tmpdir, totalmem } from 'node:os';
 import { basename, dirname, join } from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
-import { view, boardCopyOf, boardPath, claimer, claimHolds, copyRefusal, event, json, listBoards, logsDir, newClaim, now, openBoard, setActor, storageFault, tx } from './store.mjs';
+import { view, boardCopyOf, boardPath, briefPath, claimer, claimHolds, copyRefusal, event, json, listBoards, logsDir, newClaim, now, openBoard, setActor, storageFault, tx } from './store.mjs';
 import { doors, fire, loadWorkflow, resumeOf, runSpec, runWorkingSeconds, requestSessionClose, retireSupersededRuns, refreshCardInputs, refreshRelationAnswers, transitionsFor, scopeOf, statusOf, projectStatus, storedStatus, templateValue, workflowFor } from './workflow.mjs';
 import { checkWorkspace, assertWorkspaceOwner, notePresence, resolveWorkspace } from './workspace.mjs';
 import { capacity, harnessDefaults, holdings } from './capacity.mjs';
@@ -274,6 +274,21 @@ async function discoverNative(machine, harness, sessionId) {
   const complete = page.subagent_rows === 'own' && !(Array.isArray(page.failed) && page.failed.length) && !page.receipt?.truncated && page.next_cursor == null;
   return { sessions: page.sessions, complete };
 }
+/**
+ * Whether `session`'s machine holds no session of that id at all: its discovery was read whole (every source, nothing
+ * truncated) and has no row for it. A launch that stopped before its first turn (a question on its screen that no
+ * input answers) leaves a pane and no transcript, and a harness asked to resume that id exits at once. A reading not
+ * taken, or not whole, says nothing.
+ */
+async function nativeAbsent(session) {
+  if (!session?.session_id || !session.machine) return false;
+  const harness = session.harness ?? 'claude-code';
+  try {
+    const rows = await readNative(session.machine, harness, session.session_id);
+    return discoveries.get(nativeKey(session.machine, harness, session.session_id))?.complete === true
+      && !rows.some((r) => r.locator?.session_id === session.session_id);
+  } catch { return false; }
+}
 function nativeReading(rows, session) {
   const row = rows.find(r => r.locator?.session_id === session.session_id && r.locator?.harness === session.harness);
   const presence = row?.activity?.presence;
@@ -907,13 +922,13 @@ async function launchAttempt(board, entry, id, lane, fleet, settings, runId) {
       agent_profile_intent:structuredClone(agent.intended.resolved),
       agent_env:agentEnvironment(agent,{root:board.root,context:normalMachine(task.machine??localMachine())===localMachine()?localReaderContext(team.org,agent.identity.id)??undefined:undefined})});
     // The agent's own memory reaches every session of it: headless runs open its home; a pane, which may sit on
-    // another machine, gets the home's snapshot in its first prompt. A shared profile's memory is never used.
+    // another machine, gets the home's snapshot in its run's brief. A shared profile's memory is never used.
     const agentHome=materializeAgentHome(board.root,team.org,agent.identity.id,lane);
     assertRunCurrent(board,id,runId);
     if(surface==='headless')meta.agent_env.HERMES_HOME=agentHome;
     else{const memory=await memorySnapshot(agentHome).catch(()=>'');assertRunCurrent(board,id,runId);if(memory)prompt=`${prompt}\n\n${memory}`;}
     const result = surface === 'pane'
-      ? await launchPane(board, task, runId, lane, fleet, { input: prompt, slot, meta })
+      ? await launchPane(board, task, runId, lane, fleet, { input: briefByReference(board, task, runId, spec.role ?? slot, where, prompt), slot, meta })
       : await launchHeadless(board, task, runId, lane, settings, { prompt, skills: spec.skills ?? [], meta });
     tx(board,db=>{
       if(!runCurrent(db,id,runId))return; // replaced once launched: its session is the ended run's, closed as one
@@ -945,6 +960,24 @@ async function launchAttempt(board, entry, id, lane, fleet, settings, runId) {
   }
 }
 
+/**
+ * What the board types into a pane session to start a run: one short line in the board's own words naming the role,
+ * the card and where the run's brief is, with the brief itself kept in a file. A terminal harness takes its input as a
+ * paste, and Claude Code records a paste of more than two lines or about 800 characters as a `<pasted_content>`
+ * attachment with no typed words beside it, which a session rightly reads as material, not as its instruction. The
+ * line stays one line and far under that size whatever the card holds; the session on the board's machine reads the
+ * file, one elsewhere prints it through the board's door.
+ */
+export function briefByReference(board, task, runId, role, where, prompt) {
+  const file = briefPath(board.root, board.slug, task.id, runId);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${prompt}\n`, { mode: 0o600 });
+  const local = !task.machine || normalMachine(task.machine) === localMachine();
+  const from = local ? `in the file ${file}: read the whole file now`
+    : `kept by the board: print it with \`supercode workflow brief ${task.id} ${where}\` (into a file outside your repository when it is long) and read all of it now`;
+  return `The ${board.label} board started run ${runId} of card ${task.id} and you are its ${role}. Your instructions from the board are the brief ${from}, then carry it out as your own task without waiting for another message.`;
+}
+
 /** Start one card now by a person's word (a triage card's session, a manager's start): the workflow's start event. */
 export async function startCard(board, id, { roles = ['manager'], lanes, settings } = {}) {
   // the board's own published fleet projection, as a tick reads it: a manager's or creator's start that continues the
@@ -1868,6 +1901,9 @@ async function launchPane(board, task, runId, lane, fleet, { input = null, slot
       });
       // filed in its mailbox, which delivers it
       if (input) { assertRunCurrent(board, task.id, runId); await fileMail(board, addressOf(prev), input, `board-run-${task.id}-r${runId}`); }
+    } else if (prev.resumable !== false && await nativeAbsent(prev)) {
+      // nothing to resume and no context to keep: the slot's next session starts fresh
+      replaced = { session_id: prev.session_id, why: `${prev.machine} holds no ${prev.harness ?? 'claude-code'} session of that id (it never took a first turn)`, letGo: true };
     } else if (prev.resumable !== false) {
       const authorization = view(board, db => currentRun(db,task.id)?.metadata?.supercode?.restart_authorized);
       const released = view(board,db=>{
@@ -1880,7 +1916,7 @@ async function launchPane(board, task, runId, lane, fleet, { input = null, slot
       if (monitorsRuns(workflowFor(board.root)) && prev.monitor_held && !authorization && !released) throw new Error(`session ${prev.session_id} is stopped by incident ${prev.incident ?? 'unknown'}; only its manager or creator may restart it with workflow start`);
       // a resumed session is told what this run is for, as a kept one is: the run's own prompt (a reviewer resumed for
       // its next round gets that round's prompt, its arc's context with it), not only that it was resumed
-      const told = input ? `The board resumed this session for this run of card ${task.id}.\n\n${input}` : `The board resumed this session after it was lost; you are still on card ${task.id}: ${task.title}. Carry on.`;
+      const told = input ? `The board resumed this session for this run of card ${task.id}. ${input}` : `The board resumed this session after it was lost; you are still on card ${task.id}: ${task.title}. Carry on.`;
       // a session is resumed in its own harness, whatever the lane's is now
       const its = HARNESSES[prev.harness ?? 'claude-code'] ?? HARNESSES['claude-code'];
       const launchKey = `board-${task.id}-r${runId}-resume`;

package/board/store.mjs

@@ -124,6 +124,10 @@ export function boardPath(root, slug = DEFAULT_BOARD) {
 /** The directory of the board's worker logs, as Hermes lays them out. */
 export const logsDir = (root, slug = DEFAULT_BOARD) => join(boardDirOf(root, slug), 'logs');
 
+/** The file holding the brief of run `run` of card `id`: what the board hands a pane session by reference, kept with
+ *  the board's logs and removed with them. */
+export const briefPath = (root, slug, id, run) => join(logsDir(root, slug), `${id}-r${run}.brief.md`);
+
 /** The home's boards that exist: `default` when it does, and every named one. */
 export function listBoards(root) {
   const out = boardExists(root) ? [DEFAULT_BOARD] : [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.123",
+  "version": "0.5.125",
   "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": {