@volter/supercode-orchestrator 0.5.55 → 0.5.57

package/bin/orchestrator.mjs

@@ -1,4 +1,12 @@
 #!/usr/bin/env node
+// Any command on a home whose record names another orchestrator is that orchestrator's (hand-off.mjs).
+{
+  const { handOff, homeOfArgs } = await import('../hand-off.mjs');
+  let handed;
+  try { handed = handOff(homeOfArgs(process.argv.slice(2)), process.argv.slice(2)); }
+  catch (error) { process.stderr.write(`supercode ${process.argv[2] ?? ''}: ${error.message}\n`); process.exit(1); }
+  if (handed !== null) process.exit(await handed);
+}
 // Board commands do not load daemon transports, platform adapters or the MCP server.
 if (process.argv[2] === 'workflow') {
   const [{runWorkflow},{closeWorld},{timeCommand}]=await Promise.all([import('../board/cli.mjs'),import('../orchestration.mjs'),import('@volter/supercode-harness-sdk/slow-log')]);

package/board/cli.mjs

@@ -8,7 +8,8 @@ import { taskStatusOf } from './published.mjs';
 import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { recordSlow, takeSteps } from '@volter/supercode-harness-sdk/slow-log';
-import { basename, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { homedir, tmpdir, userInfo } from 'node:os';
 import { read } from '../orchestration.mjs';
 import { actorOf, view, backingPaths, layOut, backingOf, boardExists, boardPath, DEFAULT_BOARD, event, json, listBoards, logsDir, now, openBoard, setActor, setPrincipal, principalOf, isCaller, tx } from './store.mjs';
@@ -43,7 +44,7 @@ function boardPublishing(root) {
   let here; try { here = realpathSync(root); } catch { here = resolve(root); }
   try { const listed = JSON.parse(read.stdout); const board = listed.boards?.find((b) => b.root === here); return board ? { ...board, refused: listed.refused ?? null } : null; } catch { return null; }
 }
-import { requestAdoption, alertManagers, boardAddress, boardLabel, boardSettings, callerSession, commandEnv, reconcileCallerLaunch, closeRequested, lanesOf, localMachine, observeFleet, paused, plan, startCard, stopDispatching, supercodeBin, tick, deliver, startDelivery } from './dispatch.mjs';
+import { 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 { streamBoardPublications } from './event-stream.mjs';
 import { completionOwnerOf, isLatestReviewer, loadWorkflow, requestSessionClose, scopeOf, statusOf, useWorkflow, workflowEntry, workflowFor } from './workflow.mjs';
@@ -56,7 +57,7 @@ const textFrom = (file, inline) => file === undefined ? inline : readFileSync(fi
 const HELP = `supercode workflow <verb> [--root <home>] [--board <slug>] [--json]
 
 The board's verbs, with their flags:
-  init [--backing sqlite|files|ztrack] [--document <arcs.md>]
+  init [--backing sqlite|files|ztrack] [--document <arcs.md>] [--commit] [--manager <address>] [--archive-max-lines N] [--archive-period month]
   migrate --backing ztrack --document <arcs.md> --status-map <json>
   boards list|create|rm|switch|show|rename|set-default-workdir|export|import
   create <title> [--body | --body-file PATH|-] [--assignee] [--parent]... [--workspace scratch|worktree:<repository>|dir:<repository>] [--branch] [--project]
@@ -120,7 +121,7 @@ And:
 
 const MULTI = new Set(['parent', 'skill', 'worker', 'child', 'ids', 'rm', 'tag', 'pr', 'pr-head', 'reviewed-sha', 'finding']);
 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']);
+  'once', 'goal', 'no-goal', 'off', 'switch', 'delete', 'no-attachments', 'include-logs', 'verbose', 'commit']);
 // flags that take every following word up to the next flag (Hermes's nargs='+')
 const GREEDY = new Set(['ids', 'rm']);
 
@@ -240,7 +241,7 @@ let recordedCaller = null;
 function callerAddress() {
   const id = callerSession();
   if (!id) return null;
-  return recordedCaller ?? `sc:${localMachine()}:${id === process.env.CODEX_THREAD_ID ? 'codex' : 'claude-code'}:${id}`;
+  return recordedCaller ?? boardCaller()?.address ?? `sc:${localMachine()}:${id === process.env.CODEX_THREAD_ID ? 'codex' : 'claude-code'}:${id}`;
 }
 
 const callerName = () => process.env.HERMES_PROFILE || process.env.USER || 'user';
@@ -254,7 +255,7 @@ function callerPrincipal(root, sid, { teams = false } = {}) {
   if (process.env.SUPERCODE_AGENT_ID) return `agent:${process.env.SUPERCODE_AGENT_ID}`;
   if (process.env.SUPERCODE_AUTOMATION) return `automation:${process.env.SUPERCODE_AUTOMATION}`;
   if (sid) {
-    const harness = sid === process.env.CODEX_THREAD_ID ? 'codex' : 'claude-code';
+    const harness = boardCaller()?.harness ?? (sid === process.env.CODEX_THREAD_ID ? 'codex' : 'claude-code');
     const owner = agentRunForSession(root, [`${harness}:${sid}`]);
     if (owner) return `agent:${owner.agent_id}`;
     // a session an agent declared elsewhere owns (a manager's main session) is that agent's, as Teams records it
@@ -361,11 +362,20 @@ function sayReleaseBehind() {
   if (behind) process.stderr.write(`board: error: ${behind.text}\n`);
 }
 
+/**
+ * The verbs a session on another machine may not call on a board (through its machine's board door): running the
+ * board itself (its dispatcher, its init, its repair and housekeeping, adoption) and verbs that hold the call open (a
+ * watch, a tail, an attach, the event stream). They are run on the board's machine. A verb the door started reads this
+ * one list and refuses before it does anything.
+ */
+export const NOT_FROM_ANOTHER_MACHINE = new Set(['serve', 'daemon', 'dispatch', 'init', 'adopt', 'boards', 'gc', 'repair', 'migrate', 'watch', 'tail', 'attach', 'events']);
+
 export async function runWorkflow(argv) {
   const args = parse(argv);
   const [verb, ...rest] = args._;
   if (!verb || verb === 'help' || args.help) { process.stdout.write(HELP); return 0; }
   const root = homeOf(args);
+  if (process.env.SUPERCODE_BOARD_CALL === '1' && NOT_FROM_ANOTHER_MACHINE.has(verb)) throw new Error(`${verb} is run on the board's own machine, not called from another`);
   // the dispatcher's own verbs run every round; its serve says it once when it starts
   if (!['dispatch', 'events'].includes(verb)) sayReleaseBehind();
   if (verb === 'events') return streamBoardPublications({root,after:args.after,once:args.once});
@@ -423,9 +433,41 @@ export async function runWorkflow(argv) {
       return 0;
     }
     case 'init': {
-      const backing = withBoard((b) => b.backing, true);
+      // A board on the ztrack backing is made with what its ztrack.json declares besides its document: `--commit` (the
+      // documents live in a git checkout, each write committed and pushed), its manager (`--manager`, else the first one
+      // the home's workflow names), whose own writes it does not commit, and the archive's rotation. A board already there
+      // is kept as it is: one kept by another backing, or naming another document, is refused, naming what it is, and
+      // nothing is changed; the same board again is said and left.
+      const kept = boardExists(root, slug) ? backingOf(root, slug) : null;
+      let declared = null;
+      if (args.backing === 'ztrack') {
+        if (kept && kept !== 'ztrack') throw new Error(`board ${slug} in ${root} is kept by the ${kept} backing, not ztrack; it is left as it is (\`workflow migrate --backing ztrack\` moves its cards)`);
+        if (kept && args.document) {
+          const named = JSON.parse(readFileSync(backingPaths(root, slug).ztrack, 'utf8')).document;
+          const real = (path) => { try { return join(realpathSync(dirname(resolve(path))), basename(path)); } catch { return resolve(path); } };
+          if (real(named) !== real(args.document)) throw new Error(`board ${slug} in ${root} is kept on ${named}, not ${real(args.document)}; it is left as it is`);
+        }
+        // With no --manager, the home's one manager; a home naming several is asked which (the first is an accident of
+        // order), and one naming none makes a board whose every write is committed.
+        const managers = [(await loadWorkflow(root).catch(() => null))?.params?.managers ?? []].flat().filter(Boolean);
+        if (!args.manager && managers.length > 1) throw new Error(`the home's workflow names ${managers.length} managers (${managers.join(', ')}); name the board's with --manager. Nothing was made`);
+        const archive = args['archive-max-lines'] || args['archive-period'] ? { ...(args['archive-max-lines'] ? { max_lines: Number(args['archive-max-lines']) } : {}), ...(args['archive-period'] ? { period: args['archive-period'] } : {}) } : null;
+        declared = { commit: Boolean(args.commit), manager: args.manager ?? managers[0] ?? null, archive };
+      }
+      const made = openBoard(root, slug, { create: true, document: args.document ?? null, backing: args.backing ?? null, declared });
+      // A home records the orchestrator that serves it and the supercode it drives (<home>/orchestrator.json, read by
+      // hand-off.mjs for every command on the home); an install's keeper writes it, and a home made by hand gets it
+      // here, naming this orchestrator and the supercode that ran it. A record already there is the install's and stays.
+      const record = join(root, 'orchestrator.json');
+      if (!existsSync(record)) {
+        const named = (bin) => { try { const entry = realpathSync(bin); let version = null; try { version = JSON.parse(readFileSync(join(dirname(entry), '..', 'package.json'), 'utf8')).version ?? null; } catch { /* none beside it */ } return { entry, version }; } catch { return null; } };
+        const own = named(fileURLToPath(new URL('../bin/orchestrator.mjs', import.meta.url)));
+        writeFileSync(record, `${JSON.stringify({ package: '@volter/supercode-orchestrator', version: own?.version ?? null, entry: own?.entry ?? null, supercode: process.env.SUPERCODE_BIN ? named(process.env.SUPERCODE_BIN) : null })}\n`);
+      }
+      const backing = made.backing;
+      made.close();
       const { profiles } = await laneState(root).catch(() => ({ profiles: [] }));
-      say(args, `${backing === 'sqlite' ? 'Kanban DB' : `Board (${backing} backing)`} initialized at ${boardPath(root, slug)}\n\n${profiles.length ? `Profiles of this home (any can be an --assignee): ${profiles.join(', ')}` : 'No profiles in this home.'}\nThe dispatcher: \`supercode workflow serve\`, or the orchestrator while it serves the home.`, { ok: true, board: slug, path: boardPath(root, slug), backing, profiles });
+      say(args, `${backing === 'sqlite' ? 'Kanban DB' : `Board (${backing} backing)`} ${kept ? 'already' : 'initialized'} at ${boardPath(root, slug)}\n\n${profiles.length ? `Profiles of this home (any can be an --assignee): ${profiles.join(', ')}` : 'No profiles in this home.'}\nThe dispatcher: \`supercode workflow serve\`, or the orchestrator while it serves the home.`, { ok: true, board: slug, path: boardPath(root, slug), backing, kept: Boolean(kept), profiles });
       return 0;
     }
 
@@ -1455,9 +1497,16 @@ async function serve(root, args = {}) {
   const watchRounds = async (reports) => {
     await tellReleaseBehind().catch(() => {});
     if (reports.every((r) => !r.error)) {
+      // A publication the team refused holds this home's publishing where it is (nothing after it is skipped): a fact of
+      // the same kind as rounds that stopped, so it goes where every board verb's error line reads it. Only a refusal
+      // in hand counts: the team's 4xx answer, which the daemon records with the publication (from supercode-teams
+      // 0.3.44). An attempt still being retried, or a daemon that records no answer, says nothing here.
+      const held = boardPublishing(root)?.failing;
+      const refused = held && Number(held.status) >= 400 && Number(held.status) < 500 ? held : null;
+      const heldLine = refused ? [`publishing to the team is held: the team refused ${refused.card}'s ${refused.kind} (sequence ${refused.sequence}) with ${refused.status}${refused.code ? ` ${refused.code}` : ''}: ${String(refused.error ?? '').split('\n')[0].slice(0, 200)} (tried ${refused.attempts} time(s)); nothing of this home after it is published until the team takes it`] : [];
       const temporary = `${heartbeat}.${process.pid}.tmp`;
       try {
-        writeFileSync(temporary, `${JSON.stringify({ at: new Date().toISOString(), round, pid: process.pid, version: installed(), boards: reports.map((r) => ({ board: r.board, started: r.started?.length ?? 0, queued: r.queued?.length ?? 0, failed: r.failed?.length ?? 0, ms: r.ms ?? null })), errors: reports.flatMap((r) => [...(r.failed ?? []), ...(r.unsettled ?? [])].map(([t, why]) => `${r.board} ${t}: ${String(why).split('\n')[0].slice(0, 300)}`)).slice(0, 20) })}\n`);
+        writeFileSync(temporary, `${JSON.stringify({ at: new Date().toISOString(), round, pid: process.pid, version: installed(), boards: reports.map((r) => ({ board: r.board, started: r.started?.length ?? 0, queued: r.queued?.length ?? 0, failed: r.failed?.length ?? 0, ms: r.ms ?? null })), errors: [...heldLine, ...reports.flatMap((r) => [...(r.failed ?? []), ...(r.unsettled ?? [])].map(([t, why]) => `${r.board} ${t}: ${String(why).split('\n')[0].slice(0, 300)}`))].slice(0, 20) })}\n`);
         renameSync(temporary, heartbeat);
       } catch { /* the next round writes it */ }
     }

package/board/dispatch.mjs

@@ -18,6 +18,7 @@
 // a crash between the two steps is answered by the next round.
 import { monitorsRuns, failedObservation, surfaceIncident, auditEndedRuns, originOf } from './incidents.mjs';
 import { readMachineFleet } from './machine-fleet.mjs';
+import { boardLabel, boardName } from '@volter/teams/board-name';
 let fleetRoot = null;
 import { inspectCompletionEvidence, noCodeChange, openReviewPullRequests, reviewDue, withCompletionEvidence, reviewCandidate, workflowRevision, retainWorkflowTick } from './ci.mjs';
 import { runtimeDoor } from './runtime-door.mjs';
@@ -91,12 +92,36 @@ const lastJson = (text) => {
  * What supercode reports about the fleet now: `{ ok, alive: Set<address>, online: Set<machine>, error }`. `alive` is
  * every session that can be messaged on every machine; `online` every enrolled machine connected to the team.
  */
+/**
+ * The caller of a verb the machine daemon's board door runs here (another machine's session, `sc:<machine>:<harness>:
+ * <id>`), or null when the verb was not called through the door. The door is this verb's parent: it named the caller
+ * from the calling process itself and writes `{"caller": …}` on the verb's stdin, which this process reads to its end,
+ * so nothing it starts inherits it. `SUPERCODE_BOARD_CALL` only says to read it. It is trusted as the machine's user is:
+ * any process of that user can start a verb so, as it can name a session in CLAUDE_CODE_SESSION_ID.
+ */
+let readBoardCaller;
+export function boardCaller() {
+  if (readBoardCaller !== undefined) return readBoardCaller;
+  readBoardCaller = null;
+  if (process.env.SUPERCODE_BOARD_CALL !== '1') return null;
+  let said = null;
+  try { said = JSON.parse(readFileSync(0, 'utf8')); } catch { /* nothing said */ }
+  const m = /^sc:([^:\s]+):(claude-code|codex):([^:\s]+)$/.exec(said?.caller ?? '');
+  if (!m) throw new Error('this verb was started by the board door, which named no caller for it; nothing was done');
+  readBoardCaller = { address: m[0], machine: m[1], harness: m[2], session: m[3] };
+  return readBoardCaller;
+}
+
 /**
  * The session a command runs in. Each harness names its own in a variable (Claude Code CLAUDE_CODE_SESSION_ID, Codex
  * CODEX_THREAD_ID), and a pane inherits every variable the program that started its terminal server had, so a Codex
  * pane can carry a Claude session's id too: the nearest harness among the command's ancestors says which is its own.
  */
 export function callerSession() {
+  // A verb another session called on this board (the machine daemon's board door): the daemon named its caller from the
+  // calling process itself, on the caller's own machine, and passes that address in place of the harness variables.
+  const called = boardCaller();
+  if (called) return called.session;
   const claude = process.env.CLAUDE_CODE_SESSION_ID || null;
   const codex = process.env.CODEX_THREAD_ID || null;
   if (!claude || !codex) return claude ?? codex;
@@ -1995,7 +2020,7 @@ export function fileBoardMail(board, report, taskId = null) {
 }
 
 /** The board's own address: where its notices come from and where card updates are mailed. */
-export const boardAddress = (label) => `sc:${localMachine()}:board:${label.replace(/[^A-Za-z0-9_.-]/g, '-')}`;
+export const boardAddress = (label) => `sc:${localMachine()}:board:${boardName(label)}`;
 
 /** Consecutive failed sends after which a chat-platform subscription is dropped (Hermes's notifier drops a dead chat after 12). */
 const MAX_SEND_FAILURES = 12;
@@ -2291,9 +2316,6 @@ function fireHooks(board, settings, report) {
 
 // ------------------------------------------------------------------ the board's mailbox
 
-const ENTRY = fileURLToPath(new URL('../bin/orchestrator.mjs', import.meta.url));
-const NOT_BY_MAIL = new Set(['serve', 'daemon', 'dispatch', 'init', 'adopt', 'boards', 'gc', 'repair', 'watch', 'tail', 'attach']);
-
 /** The board's mailbox on this machine: the directory supercode files mail for `address` in, or null. */
 function mailboxOf(address) {
   const config = process.env.SUPERCODE_HOME || (process.env.XDG_CONFIG_HOME ? join(process.env.XDG_CONFIG_HOME, 'supercode') : join(process.env.HOME ?? '', '.config', 'supercode'));
@@ -2307,9 +2329,10 @@ function mailboxOf(address) {
 }
 
 /**
- * Card updates filed as mail (`supercode workflow <verb> … --at <this board's address>`, from any machine): each is
- * run as its sender, the session supercode found the command running under, so a card's session gets exactly what
- * it may do on this machine; the answer goes back as a notice and the envelope is filed as read.
+ * The board's mailbox takes answers to the questions the board asked (what a card waits on, read by the card's
+ * workflow) and notices about it (a machine's event, a delivery notice about a message the board sent), each filed as
+ * read. Any other message is mail it does not take: it is refused to its sender, in its own mailbox, and filed as read
+ * only once that refusal is filed.
  */
 function readMailbox(board, address, report) {
   const box = mailboxOf(address);
@@ -2318,30 +2341,15 @@ function readMailbox(board, address, report) {
     const path = join(box, 'new', name);
     let envelope;
     try { envelope = JSON.parse(readFileSync(path, 'utf8')); } catch { continue; }
-    try { renameSync(path, join(box, 'cur', name)); } catch { continue; } // another reader took it
-    // an answer to a question the board asked is what a card waits on (read by the card's workflow), not a verb
-    if (envelope.in_reply_to) continue;
-    // A notice is news for the board, never a card update: a machine's event, or Claude Code's delivery notice about a
-    // message the board sent (filed by the relay from `sc:<machine>:claude-code:notice`, which is no session). Its sender
-    // asked for no reply (reply_via none), so it is filed as read and never answered.
-    if (envelope.kind === 'notice' || envelope.reply_via?.mode === 'none') {
-      report.mailed.push([envelope.from, envelope.from === `sc:${localMachine()}:operator:teams-events` ? 'machine_event' : 'notice']);
-      continue;
-    }
-    const argv = json(envelope.body, {})?.workflow;
-    let answer;
-    if (!Array.isArray(argv) || !argv.length || NOT_BY_MAIL.has(argv[0])) answer = `not applied: a mailed card update is one \`supercode workflow\` verb other than ${[...NOT_BY_MAIL].join(', ')}`;
-    else {
-      const clean = [];
-      for (let i = 0; i < argv.length; i += 1) { if (argv[i] === '--root' || argv[i] === '--board') i += 1; else clean.push(String(argv[i])); }
-      const sid = String(envelope.from ?? '').split(':')[3] ?? '';
-      const r = spawnSync(process.execPath, [ENTRY, 'workflow', ...clean, '--root', board.root, '--board', board.slug], {
-        encoding: 'utf8', timeout: 180_000, env: { ...process.env, CLAUDE_CODE_SESSION_ID: sid, CODEX_THREAD_ID: '' },
-      });
-      answer = `${clean.slice(0, 2).join(' ')}: ${(r.status === 0 ? r.stdout : r.stderr || r.stdout).trim().slice(-600) || `exit ${r.status}`}`;
+    const notice = envelope.kind === 'notice' || envelope.reply_via?.mode === 'none';
+    if (!envelope.in_reply_to && !notice) {
+      try {
+        fileMail(board, envelope.from, `${address} takes answers to its questions and notices only; this message was not taken.`, `board-refused-${envelope.id}`);
+      } catch (error) { report.undelivered.push(['mail', envelope.from, String(error.message).slice(-200)]); continue; }
+      report.mailed.push([envelope.from, 'refused']);
     }
-    report.mailed.push([envelope.from, argv?.[0] ?? '?']);
-    report.answers.push(send(board, address, board.label, envelope.from, answer, `board-answer-${envelope.id}`).catch((error) => { report.undelivered.push(['mail', envelope.from, String(error.message).slice(-200)]); }));
+    try { renameSync(path, join(box, 'cur', name)); } catch { continue; } // another reader took it
+    if (!envelope.in_reply_to && notice) report.mailed.push([envelope.from, envelope.from === `sc:${localMachine()}:operator:teams-events` ? 'machine_event' : 'notice']);
   }
 }
 
@@ -2351,11 +2359,8 @@ function readMailbox(board, address, report) {
 
 // ------------------------------------------------------------------ the tick
 
-/** The board's name in notices: the home's owner folder (`…/volter-manager/home` → `volter-manager`), and the slug. */
-export function boardLabel(root, slug) {
-  const home = basename(root) === 'home' ? basename(dirname(root)) : basename(root);
-  return slug && slug !== 'default' ? `${home}/${slug}` : home;
-}
+/** The board's name in notices: the home's owner folder, and the slug (@volter/teams/board-name, the rule the daemon reads too). */
+export { boardLabel };
 
 // A dispatcher told to stop (its serve's SIGTERM, SIGINT or SIGHUP) starts nothing more in the round it is in: no further
 // board, card start, board message or notice. What it leaves unfiled is not a failure; the next dispatcher files it.
@@ -2565,8 +2570,6 @@ export async function tick({ root, lanes, settings, only = null, slugs = null, d
   for (const slug of boards) {
     if (stopping) break;
     const report = { board: slug, ms: { fleet: fleetMs }, mailed: [], started: [], queued: [], failed: [], lost: [], crashed: [], timed_out: [], reclaimed: [], auto_blocked: [], promoted: 0, unassigned: [], nonspawnable: [], notified: [], undelivered: [], fleet: fleet.ok ? 'read' : fleet.error };
-    // the mailbox's answers in flight (not part of the report the caller prints)
-    Object.defineProperty(report, 'answers', { value: [], enumerable: false });
     const path = boardPath(root, slug);
     const marker = `${path}.corrupt-seen`;
     if (existsSync(marker) && readFileSync(marker, 'utf8').trim() === fingerprint(path)) { report.error = 'skipped: the board file was corrupt and has not changed since (`supercode workflow repair`)'; out.push(report); continue; }
@@ -2610,7 +2613,6 @@ export async function tick({ root, lanes, settings, only = null, slugs = null, d
       report.error = error.message;
       if (CORRUPT.test(error.message)) writeFileSync(marker, fingerprint(path));
     } finally {
-      await Promise.all(report.answers);
       board?.close();
     }
     out.push(report);

package/board/engine.mjs

@@ -985,10 +985,10 @@ export function diagnose(db, task, { failureLimit = DEFAULT_FAILURE_LIMIT, stran
       ? { kind: 'effect_failed', severity: 'warning', title: `its ${kind} failed for good after ${row.attempts} attempts: ${row.last_error ?? 'no reason recorded'}`, data: { effect: row.id, kind, attempts: row.attempts }, actions: [] }
       : { kind: 'effect_stalled', severity: 'error', title: `its ${kind} has failed ${row.attempts} times and is still tried: ${row.last_error ?? 'no reason recorded'}`, data: { effect: row.id, kind, attempts: row.attempts }, actions: [] });
   }
-  // publications of the card the machine's connector abandoned: the team refused each one past its attempts
-  for (const a of (publishing?.abandoned ?? []).filter((a) => a.card === task.id).slice(0, 20)) {
-    out.push({ kind: 'publication_abandoned', severity: 'warning', title: `its ${a.kind} (sequence ${a.sequence}) was not published to the team: refused ${a.attempts} times (${a.status} ${a.code ?? ''}): ${a.error}`, data: { publication: a.publication, sequence: a.sequence, status: a.status, code: a.code }, actions: [] });
-  }
+  // a publication of the card the team refuses: the home's publishing holds on it (none after it is published past it)
+  // and the machine's connector tries it again
+  const failing = publishing?.failing;
+  if (failing?.card === task.id) out.push({ kind: 'publication_refused', severity: 'error', title: `its ${failing.kind} (sequence ${failing.sequence}) is refused by the team (${failing.status} ${failing.code ?? ''}: ${failing.error}), tried ${failing.attempts} times; this board's publishing waits on it`, data: failing });
   // mail the board filed for the card that the mailbox still has to deliver (waiting), or gave up on (expired: it stays
   // unread there)
   if (expiredMail?.size || waitingMail?.size) {

package/board/store.mjs

@@ -168,7 +168,7 @@ function noteOrigin(root) {
   copies.set(root, origin === here ? null : origin);
 }
 
-export function openBoard(root, slug = DEFAULT_BOARD, { create = false, backing = null, document = null } = {}) {
+export function openBoard(root, slug = DEFAULT_BOARD, { create = false, backing = null, document = null, declared = null } = {}) {
   noteOrigin(root);
   const kept = backingOf(root, slug);
   if (!kept && !create) throw new Error(`no board ${slug} in ${root} (${boardPath(root, slug)})`);
@@ -176,7 +176,7 @@ export function openBoard(root, slug = DEFAULT_BOARD, { create = false, backing
   const use = kept ?? backing ?? 'sqlite';
   if (!BACKINGS.includes(use)) throw new Error(`a board's backing is ${BACKINGS.join(' | ')}, not ${use}`);
   const path = backingPaths(root, slug)[use];
-  if (use === 'ztrack') return { ...openZtrackBoard(path, { create, document, init: layOut, root, slug }), root, slug, path, backing: use };
+  if (use === 'ztrack') return { ...openZtrackBoard(path, { create, document, declared, init: layOut, root, slug }), root, slug, path, backing: use };
   if (use === 'files') return { ...openFilesBoard(path, { create, init: layOut }), root, slug, path, backing: use };
   if (!kept) mkdirSync(dirname(path), { recursive: true });
   const db = new DatabaseSync(path);

package/board/ztrack.mjs

@@ -9,7 +9,7 @@
 // region the edit touched. So a write costs what it changes, not the size of the board.
 import { createRequire } from 'node:module';
 import { createHash, randomBytes } from 'node:crypto';
-import { existsSync, linkSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { actorOf, contention, event, json, now, principalOf } from './store.mjs';
@@ -59,11 +59,18 @@ DROP TABLE IF EXISTS board_export;`;
 // written to the document). board_tasks: a subtask's key on its arc's Tasks list
 // (`<arc>:c3`) and its `source:` lines, which live only in the document.
 
-export function openZtrackBoard(marker, { create = false, document = null, seed = null, init, root, slug }) {
+export function openZtrackBoard(marker, { create = false, document = null, declared = null, seed = null, init, root, slug }) {
   if (!existsSync(marker)) {
     if (!create) throw new Error(`no ztrack board ${marker}`);
     mkdirSync(dirname(marker), { recursive: true });
-    atomic(marker, JSON.stringify({ format: 1, document: resolve(document ?? resolve(dirname(marker), 'arcs.md')) }) + '\n');
+    // What its creator declares besides the document (`init --commit --manager`, the archive's rotation) is written once,
+    // with it; a value left unnamed is not written.
+    const said = Object.fromEntries(Object.entries(declared ?? {}).filter(([, value]) => value !== null && value !== undefined && value !== false));
+    // The document by its real path (its folder's symlinks followed; the document itself may not exist yet): a commit
+    // names the document relative to its checkout, as git names the checkout's files, and a path through a symlink (a
+    // short state root) names a file outside it.
+    const named = resolve(document ?? resolve(dirname(marker), 'arcs.md'));
+    atomic(marker, JSON.stringify({ format: 1, document: join(realpathSync(dirname(named)), basename(named)), ...said }) + '\n');
   }
   const config = JSON.parse(read(marker));
   const backing = new ZtrackBoard({ ...config, seed, marker, init, root, slug });

package/hand-off.mjs

@@ -0,0 +1,46 @@
+// THE ONE PLACE A HOME'S ORCHESTRATOR IS DECIDED (D152 row 11). Every command on a home ends in an orchestrator's entry
+// (bin/orchestrator.mjs), whichever way it came: a shell's or a pane's supercode, the native binary (its \`workflow\`,
+// \`orchestrator start\`, \`apps\`, \`access\` and its cold write door all run \`node <entry> … --root <home>\` with the
+// entry it finds: SUPERCODE_ORCHESTRATOR_ENTRY, else the \`supercode-orchestrator\` on PATH, the machine's own), the
+// machine daemon's follower and board door, \`supercode --quiet workflow …\`. A home whose install pins its own
+// orchestrator names it in its record (<home>/orchestrator.json, written by the install's keeper and by init): the entry
+// a command reached hands the command to the one named, driving the supercode named beside it, and runs it itself only
+// when it is that one or when the home has no record (a home made by hand, served by the machine's own). So no home is
+// served by two orchestrators. Nothing in Rust changes (D155); an orchestrator older than this one hands nothing off, so
+// the machine's own moves to this release with the landing.
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** The home a command (the whole of it, after the entry) names: --root, wherever it stands (the gateway's form,
+ *  `node bin/orchestrator.mjs --root <home>`, has no verb before it); for `import`, which writes the home it names
+ *  with --into, that; else the environment the orchestrator reads (SUPERCODE_ORCHESTRATOR_HOME, HERMES_HOME).
+ *  (`export` names the home it reads with --from and writes none.) */
+export function homeOfArgs(argv, env = process.env) {
+  const flag = argv[0] === 'import' ? '--into' : '--root';
+  const at = argv.findIndex((arg) => arg === flag || arg.startsWith(`${flag}=`));
+  const named = at < 0 ? env.SUPERCODE_ORCHESTRATOR_HOME ?? env.HERMES_HOME : argv[at].startsWith(`${flag}=`) ? argv[at].slice(flag.length + 1) : argv[at + 1];
+  return named ? resolve(named) : null;
+}
+
+/** The command (\`argv\`, after node and the entry) handed to the orchestrator the home's record names: its exit code, or
+ *  null when this orchestrator serves it (it is the one named, or the home has no record). */
+export function handOff(root, argv) {
+  if (!root) return null;
+  let record;
+  try { record = JSON.parse(readFileSync(join(root, 'orchestrator.json'), 'utf8')); } catch { return null; }
+  const own = realpathSync(fileURLToPath(new URL('./bin/orchestrator.mjs', import.meta.url)));
+  const version = (() => { try { return JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8')).version; } catch { return 'unknown'; } })();
+  let named;
+  try { named = realpathSync(record.entry); } catch { throw new Error(`${root} is served by orchestrator ${record.version ?? 'unknown'} (${record.entry ?? 'its record names none'}), which is not on this machine; this one is ${version}. Nothing was run`); }
+  const supercode = record.supercode?.entry;
+  if (!supercode || !existsSync(supercode)) throw new Error(`${root} is served by supercode ${record.supercode?.version ?? 'unknown'} (${supercode ?? 'its record names none'}), which is not on this machine. Nothing was run`);
+  if (named === own) { process.env.SUPERCODE_BIN = supercode; return null; }
+  return new Promise((done) => {
+    const child = spawn(process.execPath, [named, ...argv], { stdio: 'inherit', env: { ...process.env, SUPERCODE_BIN: supercode } });
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(signal, () => { try { child.kill(signal); } catch { /* gone */ } });
+    child.on('error', (error) => { process.stderr.write(`supercode: could not run orchestrator ${record.version ?? ''} (${named}): ${error.message}\n`); done(1); });
+    child.on('close', (code, signal) => done(signal ? 1 : code ?? 1));
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.55",
+  "version": "0.5.57",
   "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.60",
-    "@volter/teams": "0.2.18",
+    "@volter/teams": "0.2.19",
     "@volter/ztrack": "^2.4.23",
     "yaml": "^2.9.0"
   },