@volter/supercode-orchestrator 0.5.204 → 0.5.206

package/board/tools.mjs

@@ -7,7 +7,9 @@ import { mkdirSync, statSync, writeFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
 import { DEFAULT_BOARD, actorOf, event, json, openBoard, setActor, tx } from './store.mjs';
 import * as engine from './engine.mjs';
+import { assertSourceReceipt } from './ci.mjs';
 import { completionOwnerOf, isLatestReviewer, loadWorkflow } from './workflow.mjs';
+import { attachmentRecord, readAttachment } from './attachment-read.mjs';
 
 const ok = (fields = {}) => JSON.stringify({ ok: true, ...fields });
 const error = (message) => JSON.stringify({ error: message });
@@ -30,6 +32,7 @@ const ORCHESTRATOR_ONLY = new Set(['kanban_list', 'kanban_unblock']);
 
 /** One board tool call. `root` is the home; `env` the worker's task environment (`HERMES_KANBAN_*`). */
 export async function boardTool(root, name, args = {}, env = {}) {
+  try { assertSourceReceipt(args); } catch (e) { return error(e.message); }
   const own = env.HERMES_KANBAN_TASK || null;
   const runId = env.HERMES_KANBAN_RUN_ID ? Number(env.HERMES_KANBAN_RUN_ID) : null;
   const author = env.HERMES_PROFILE || 'worker';
@@ -112,7 +115,7 @@ export async function boardTool(root, name, args = {}, env = {}) {
           }
         }
         if (env.HERMES_SESSION_ID && own === tid) metadata = { ...(metadata ?? {}), worker_session_id: env.HERMES_SESSION_ID };
-        await engine.complete(board, tid, { summary, result, metadata, commit: args.commit ?? null, ci_run: args.ci_run ?? null, branch: args.branch ?? null, pr: args.pr ?? null, pr_head: args.pr_head ?? null, reviewed_sha: args.reviewed_sha ?? null });
+        await engine.complete(board, tid, { summary, result, metadata, commit: args.commit ?? null, branch: args.branch ?? null, pr: args.pr ?? null, pr_head: args.pr_head ?? null, reviewed_sha: args.reviewed_sha ?? null });
         return ok({ task_id: tid, status: 'done' });
       }
       case 'kanban_block': {
@@ -122,12 +125,12 @@ export async function boardTool(root, name, args = {}, env = {}) {
       }
       case 'kanban_request_state': {
         const stale = ownRun(); if (stale) return error(stale);
-        await engine.requestStateMany(board, targets, { state: args.state, reason: args.reason, on: args.on ?? null, waiting_on: args.waiting_on ?? null, evidence: args.evidence ?? null, commit: args.commit ?? null, ci_run: args.ci_run ?? null, branch: args.branch ?? null, pr: args.pr ?? null, pr_head: args.pr_head ?? null, reviewed_sha: args.reviewed_sha ?? null, deployed_sha: args.deployed_sha ?? null });
+        await engine.requestStateMany(board, targets, { state: args.state, reason: args.reason, on: args.on ?? null, waiting_on: args.waiting_on ?? null, evidence: args.evidence ?? null, commit: args.commit ?? null, branch: args.branch ?? null, pr: args.pr ?? null, pr_head: args.pr_head ?? null, reviewed_sha: args.reviewed_sha ?? null });
         return ok({ task_id: tid, task_ids: targets, requested: args.state, changed: false });
       }
       case 'kanban_request_review': {
         const stale = ownRun(); if (stale) return error(stale);
-        await engine.requestReview(board, tid, { summary: args.summary ? redact(String(args.summary)) : null, metadata: args.metadata ? redact(args.metadata) : null, commit: args.commit ?? null, ci_run: args.ci_run ?? null, branch: args.branch ?? null, pr: args.pr ?? null, pr_head: args.pr_head ?? args.commit ?? null, reviewer: args.reviewer ?? null, expectedRunId: own === tid && runId ? runId : null });
+        await engine.requestReview(board, tid, { summary: args.summary ? redact(String(args.summary)) : null, metadata: args.metadata ? redact(args.metadata) : null, commit: args.commit ?? null, branch: args.branch ?? null, pr: args.pr ?? null, pr_head: args.pr_head ?? args.commit ?? null, reviewer: args.reviewer ?? null, expectedRunId: own === tid && runId ? runId : null });
         return ok({ task_id: tid, status: 'review' });
       }
       case 'kanban_request_changes': {
@@ -172,11 +175,15 @@ export async function boardTool(root, name, args = {}, env = {}) {
         return ok({ task_id: tid, attachment_id: id, path });
       }
       case 'kanban_attachments':
+        if (args.attachment_id !== undefined) {
+          const row = tx(board, (db) => attachmentRecord(db, tid, args.attachment_id));
+          return ok(await readAttachment(root, slug, row, { offset: args.offset, length: args.length, version: args.version }));
+        }
         return ok({ task_id: tid, attachments: tx(board, (db) => engine.attachments(db, tid)).map((a) => ({ id: a.id, filename: a.filename, size: a.size, content_type: a.content_type, path: a.stored_path })) });
       case 'kanban_create': {
         const workspace = args.workspace_kind ? `${args.workspace_kind}${args.workspace_path ? `:${args.workspace_path}` : ''}` : undefined;
         const made = engine.createCard(board, await engine.prepareCard(board, {
-          title: args.title, body: args.body ? redact(String(args.body)) : null, assignee: args.assignee ?? null, parents: [args.parents ?? []].flat(), tenant: args.tenant ?? null,
+          title: args.title, body: args.body ? redact(String(args.body)) : null, assignee: args.assignee ?? null, reviewer: args.reviewer ?? null, parents: [args.parents ?? []].flat(), tenant: args.tenant ?? null,
           priority: args.priority ?? 0, workspace, project: args.project ?? null, triage: Boolean(args.triage), idempotencyKey: args.idempotency_key ?? null,
           maxRuntime: args.max_runtime_seconds ?? null, initialStatus: args.initial_status ?? null, skills: args.skills ?? null, model: args.model ?? null, provider: args.provider ?? null,
           goal: args.goal_mode ? { maxTurns: args.goal_max_turns ?? null } : null, createdBy: author,

package/board/workflow.mjs

@@ -5,6 +5,7 @@
 // the engine's primitives (the rows Hermes's tables hold); the I/O an action asks for (stopping a worker, closing a
 // pane, sending a session a message, cleaning a workspace) is answered as effects the caller runs after commit.
 import { current } from './call.mjs';
+import { detachedCard, detachedSession } from './custody.mjs';
 import { notRuntime } from './owner-files.mjs';
 import { machineCall } from './doors.mjs';
 import { execFile } from 'node:child_process';
@@ -20,6 +21,21 @@ import { cardCommitsOn, isLocalWorkspace, isWorkspacePath } from './workspace.mj
 import { identifyNotice } from './notices.mjs';
 
 const loaded = new Map();
+// the owner's read door holds the workflow the owner reads (owner-door.mjs), told when it is read again
+const workflowWatchers = new Set();
+const hold = (root, entry) => {
+  const again = loaded.get(root)?.orchestration !== entry.orchestration;
+  loaded.set(root, entry);
+  if (again) for (const watcher of workflowWatchers) watcher(root, entry);
+};
+/** `watcher(root, entry)` is told each workflow this process holds, now and whenever one is read again; answers its stop. */
+export function watchWorkflows(watcher) {
+  workflowWatchers.add(watcher);
+  for (const [root, entry] of loaded) watcher(root, entry);
+  return () => workflowWatchers.delete(watcher);
+}
+/** Hold the workflow another thread of this process read for `root` (the owner's, on its read door). */
+export function holdWorkflow(root, entry) { loaded.set(root, { ...entry, root }); }
 const homes = new Map(); // root → Promise<orchestration>: the home as the IR reads it, held until it changes
 
 /**
@@ -49,15 +65,15 @@ export async function loadWorkflow(root) {
     entry = workflowEntry(orchestration);
     entry.root = root;
     entry.orchestration = orchestration;
-    loaded.set(root, entry);
+    hold(root, entry);
   }
   current().workflows.set(root, entry);
   return entry;
 }
 
 // What the board's view of a home is decoded from: the workflow, each profile's config, credentials and the agent
-// layer, and which profiles there are. A session store or a run log changing is no change to it.
-const DECODED = /^(?:(?:profiles\/[^/]+\/)?(?:config\.yaml|\.env|agents\.json)|workflow\.yaml|profiles(?:\/[^/]+)?)$/;
+// layer, persona, and which profiles there are. A session store or a run log changing is no change to it.
+const DECODED = /^(?:(?:profiles\/[^/]+\/)?(?:config\.yaml|\.env|agents\.json|AGENTS\.md)|workflow\.yaml|profiles(?:\/[^/]+)?)$/;
 
 /**
  * Follow the home's own files, so the held view is read again on its next use after one it is decoded from changes:
@@ -75,7 +91,7 @@ export function followHome(root, { onChange = () => {}, onLost = () => {} } = {}
   const linked = new Map(); // target folder → watcher
   const followLinks = () => {
     const targets = new Map();
-    const decoded = ['workflow.yaml', 'config.yaml', '.env', 'agents.json'];
+    const decoded = ['workflow.yaml', 'config.yaml', '.env', 'agents.json', 'AGENTS.md'];
     const watchIn = (folder, name) => { if (!targets.has(folder)) targets.set(folder, new Set()); targets.get(folder).add(name); };
     let realRoot = root;
     try { realRoot = realpathSync(root); } catch { /* the home's own watch reports it */ }
@@ -143,7 +159,7 @@ export function workflowFor(root) {
 /** Use `entry` for `root` (a caller that read the IR itself). */
 export function useWorkflow(root, entry) {
   entry.root = root;
-  loaded.set(root, entry);
+  hold(root, entry);
   current().workflows.set(root, entry);
   return entry;
 }
@@ -170,6 +186,11 @@ export function completionOwnerOf(db, id) {
   return creatorOf(db, id);
 }
 
+/** A card's explicitly named review profile, retained in its own history. */
+export function reviewerOf(db, id) {
+  return json(one(db, "SELECT payload FROM task_events WHERE task_id=? AND kind IN ('created','reviewer_set') ORDER BY id DESC LIMIT 1", id)?.payload, {})?.reviewer ?? null;
+}
+
 export function latestReview(db, id) {
   const row = one(db, "SELECT id,started_at,metadata FROM task_runs WHERE task_id=? AND json_extract(metadata,'$.supercode.role')='reviewer' ORDER BY id DESC LIMIT 1", id);
   if (!row) return null;
@@ -363,7 +384,8 @@ export function runWorkingSeconds(row, at = now()) {
   return Math.max(0, end - Number(row.started_at ?? end) - Number(json(row.metadata,{})?.supercode?.stopped_seconds??0));
 }
 
-function timeOf(db, task) {
+/** Elapsed role totals need no review candidate or workflow guard scope. */
+export function timeOf(db, task) {
   const t = now();
   const out = { coding: 0, reviewing: 0, auditing: 0, triaging: 0 };
   const key = { implementer: 'coding', reviewer: 'reviewing', auditor: 'auditing', triager: 'triaging' };
@@ -394,6 +416,14 @@ export function scopeOf(db, board, task, { params, event = {}, extra = {}, lazy
   const lastRun = once(() => one(db, 'SELECT * FROM task_runs WHERE task_id = ? AND ended_at IS NOT NULL ORDER BY ended_at DESC, id DESC LIMIT 1', task.id));
   const lastCompleted = once(() => one(db, "SELECT * FROM task_runs WHERE task_id = ? AND outcome = 'completed' ORDER BY ended_at DESC LIMIT 1", task.id));
   const asked = once(() => json(one(db, "SELECT payload FROM task_events WHERE task_id = ? AND kind = 'review_requested' ORDER BY id DESC LIMIT 1", task.id)?.payload, {}) ?? {});
+  const entry = current().workflows.get(board.root) ?? loaded.get(board.root);
+  // Read the coding role, never the latest run of any role: after a review or a
+  // reassignment that run may belong to a different harness than the coder's.
+  const coding = once(() => one(db, "SELECT id,profile,metadata FROM task_runs WHERE task_id=? AND json_extract(metadata,'$.supercode.role')='implementer' ORDER BY id DESC LIMIT 1", task.id));
+  const codingSession = once(() => json(coding()?.metadata, {})?.supercode ?? {});
+  const codingProfile = once(() => coding()?.profile ?? asked().implementer ?? task.assignee);
+  const coderProfile = once(() => entry?.profiles?.[codingProfile()]);
+  const configuredCoder = once(() => coderProfile()?.worker);
   const changes = once(() => json(one(db, "SELECT payload FROM task_events WHERE task_id = ? AND kind = 'changes_requested' ORDER BY id DESC LIMIT 1", task.id)?.payload, {}) ?? {});
   const interruption = once(() => json(one(db, `SELECT payload FROM task_events WHERE task_id = ? AND kind IN ('blocked', 'block_loop_detected', 'dependency_wait', 'gave_up',
     'unblocked', 'changes_requested', 'review_reopened', 'status', 'reclaimed', 'stale', 'timed_out', 'crashed', 'spawn_failed', 'rate_limited', 'session_lost')
@@ -415,6 +445,7 @@ export function scopeOf(db, board, task, { params, event = {}, extra = {}, lazy
     status,
     blocked_by: blocks,
     paused: json(state.paused, null),
+    detached: json(state.detached, null),
     archived: Boolean(state.archived),
     every: state.every ?? null,
     next_run_at: state.next_run_at ?? null,
@@ -436,6 +467,15 @@ export function scopeOf(db, board, task, { params, event = {}, extra = {}, lazy
     get counters() { return { failures: Number(task.consecutive_failures || 0), block_recurrences: Number(task.block_recurrences || 0), goal_turns: Number(session().goal_turns || 0) }; },
     goal_mode: Boolean(task.goal_mode),
     get implementer() { return asked().implementer ?? task.assignee; },
+    get implementer_harness() { return codingSession().harness ?? configuredCoder()?.harness ?? null; },
+    get implementer_model() { return codingSession().model ?? (codingProfile() === task.assignee ? task.model_override : asked().implementer_model) ??
+      configuredCoder()?.model ?? coderProfile()?.residue?.config?.model?.default ?? null; },
+    get implementer_run() { return coding() ? { id: coding().id, profile: coding().profile, harness: codingSession().harness ?? null,
+      model: codingSession().model ?? null, machine: codingSession().machine ?? null } : null; },
+    get implementer_machine() { return Object.hasOwn(asked(), 'implementer_machine') ? asked().implementer_machine : task.machine ?? null; },
+    get implementer_model_override() { return Object.hasOwn(asked(), 'implementer_model_override') ? asked().implementer_model_override : task.model_override ?? null; },
+    get implementer_provider_override() { return Object.hasOwn(asked(), 'implementer_provider_override') ? asked().implementer_provider_override : task.provider_override ?? null; },
+    get reviewer() { return reviewerOf(db, task.id); },
     get last_reviewer() { return changes().reviewer ?? null; },
     get arc() { return task.subtask_of ? one(db, `SELECT t.id, ${related}, t.title, t.body, t.assignee FROM tasks t LEFT JOIN supercode_cards c ON c.task_id = t.id WHERE t.id = ?`, task.subtask_of) ?? null : null; },
     // the cards filed as its subtasks (`create --subtask-of`), in the order they were filed
@@ -485,13 +525,7 @@ export function scopeOf(db, board, task, { params, event = {}, extra = {}, lazy
     Object.defineProperty(card, key, { get: read, enumerable: true, configurable: true });
     if (!lazy) read();
   }
-  const derived = loaded.get(board.root)?.workflow?.derived ?? {};
-  for (const [key, expr] of Object.entries(derived)) {
-    // Preflight neither evaluates nor exposes a derived source value from a stale/missing observation.
-    const value = deferSources && needsSources(expr, derived) ? undefined : evaluate(expr, { card, event, params, now: now() });
-    Object.defineProperty(card, key, { value, writable: true, enumerable: true, configurable: true });
-  }
-  return {
+  const scope = {
     card,
     requester: actorOf(),
     event,
@@ -499,8 +533,15 @@ export function scopeOf(db, board, task, { params, event = {}, extra = {}, lazy
     now: now(),
     board: board.label ?? board.slug,
     matches: (text, p) => (text === null || text === undefined ? false : pattern(p).test(String(text))),
+    lanes: entry ? lanesIn(entry) : {},
+    profile_harnesses: Object.fromEntries(Object.entries(entry?.profiles ?? {}).filter(([, profile]) => profile?.worker?.harness)
+      .map(([name, profile]) => [name, profile.worker.harness])),
     ...extra,
   };
+  // Derived facts see the same names as transitions, including the home's
+  // lanes. The pinned entry remains the basis if the home reloads mid-call.
+  for (const [key, expr] of Object.entries(entry?.workflow?.derived ?? {})) card[key] = deferSources && needsSources(expr, entry.workflow.derived) ? undefined : evaluate(expr, scope);
+  return scope;
 }
 
 // ------------------------------------------------------------------ events
@@ -528,13 +569,19 @@ function noticeRun(db, task) {
     : all(db, 'SELECT id, metadata FROM task_runs WHERE task_id = ? ORDER BY id DESC', task.id).find((r) => json(r.metadata, {})?.supercode?.session_id) ?? null;
 }
 
-function queueTransitionNotice(db, board, entry, task, from, name, payload, beforeRun, effects) {
+function queueTransitionNotice(db, board, entry, task, from, name, payload, beforeRun, effects, noticeSession = null) {
   const after = cardOf(db, task.id), to = statusOf(db, after);
+  // A verified adoption starts a new run before binding its session. Its notice
+  // belongs to that new run and verified identity, never the last ended session
+  // that noticeRun found before the transition.
+  const targetRun = noticeSession && after.current_run_id
+    ? one(db, 'SELECT id, metadata FROM task_runs WHERE id = ?', after.current_run_id) : beforeRun;
   const state = (t, status) => JSON.stringify([status, t.current_run_id, t.paused, t.archived, t.blocked_by]);
   const beforeState = json(beforeRun?.metadata, {})?.supercode?.state;
   const afterState = beforeRun && json(one(db, 'SELECT metadata FROM task_runs WHERE id=?', beforeRun.id)?.metadata, {})?.supercode?.state;
-  if (!beforeRun || (state(task, from) === state(after, to) && beforeState === afterState) || effects.some((e) => e.kind === 'session_notice' && e.runId === beforeRun.id)) return;
-  const session = json(beforeRun.metadata, {})?.supercode;
+  if (!targetRun || (state(task, from) === state(after, to) && beforeState === afterState) || effects.some((e) => e.kind === 'session_notice' && e.runId === targetRun.id)) return;
+  const session = noticeSession ?? json(targetRun.metadata, {})?.supercode;
+  if (detachedSession(db, session)) return;
   const address = session?.address ?? (session?.session_id && session.machine ? `sc:${session.machine}:${session.harness ?? 'claude-code'}:${session.session_id}` : null);
   if (!address && !session?.launch_key && !session?.pane) return;
   // The session that made this change learns it from its own command's answer; a notice about
@@ -542,16 +589,19 @@ function queueTransitionNotice(db, board, entry, task, from, name, payload, befo
   // confirmed is not told either: its next run resumes it with the card's state in its prompt.
   if (address && address === actorOf()) return;
   if (session?.close_confirmed_at) return;
-  const scope = scopeOf(db, board, after, { params: entry.params, event: { ...payload, verb: name, from, to }, extra: { run: { id: beforeRun.id } } });
-  const body = render(entry.workflow.notify?.worker?.run_changed ?? '{{card.id}}: {{event.verb}} changed run {{run.id}} ({{event.from}} → {{event.to}}). Stop work under the previous run; follow the board’s current state. {{event.reason ?? ""}}', scope);
+  const scope = scopeOf(db, board, after, { params: entry.params, event: { ...payload, verb: name, from, to }, extra: { run: { id: targetRun.id } } });
+  const defaultNotice = noticeSession
+    ? '{{card.id}}: verified adoption started run {{run.id}} ({{event.from}} → {{event.to}}). Follow the board’s current state before continuing.'
+    : '{{card.id}}: {{event.verb}} changed run {{run.id}} ({{event.from}} → {{event.to}}). Stop work under the previous run; follow the board’s current state. {{event.reason ?? ""}}';
+  const body = render(entry.workflow.notify?.worker?.run_changed ?? defaultNotice, scope);
   const source = one(db, 'SELECT MAX(id) AS id FROM task_events WHERE task_id = ?', task.id)?.id;
-  const text = identifyNotice({ id: source, kind: name, run_id: beforeRun.id, created_at: now() }, body);
-  const effect = { kind: 'session_notice', id: task.id, runId: beforeRun.id, address, text, sourceEvent: source, verb: name, messageKey: `board-run-notice-${randomBytes(16).toString('hex')}` };
+  const text = identifyNotice({ id: source, kind: name, run_id: targetRun.id, created_at: now() }, body);
+  const effect = { kind: 'session_notice', id: task.id, runId: targetRun.id, address, text, sourceEvent: source, verb: name, messageKey: `board-run-notice-${randomBytes(16).toString('hex')}` };
   const inserted = run(db, 'INSERT INTO supercode_effects (effect) VALUES (?)', JSON.stringify(effect));
   effects.push({ ...effect, durableId: Number(inserted.lastInsertRowid) });
-  const current = json(one(db, 'SELECT metadata FROM task_runs WHERE id = ?', beforeRun.id)?.metadata, {}) ?? {};
+  const current = json(one(db, 'SELECT metadata FROM task_runs WHERE id = ?', targetRun.id)?.metadata, {}) ?? {};
   current.supercode = { ...current.supercode, lifecycle_notice_pending: Number(inserted.lastInsertRowid) };
-  run(db, 'UPDATE task_runs SET metadata = ? WHERE id = ?', JSON.stringify(current), beforeRun.id);
+  run(db, 'UPDATE task_runs SET metadata = ? WHERE id = ?', JSON.stringify(current), targetRun.id);
 }
 
 /**
@@ -644,7 +694,7 @@ export function validateEvent(db, board, entry, id, name, { roles = [], payload
   return { task, from, taken, scope, beforeRun: localOnly ? null : noticeRun(db, task) };
 }
 
-export function fire(db, board, entry, id, name, { roles = [], payload = {}, extra = {} } = {}) {
+export function fire(db, board, entry, id, name, { roles = [], payload = {}, extra = {}, noticeSession = null } = {}) {
   const checked = validateEvent(db, board, entry, id, name, { roles, payload, extra });
   if (!checked) return fireRun(db, board, entry, id, name, { roles, payload, extra });
   const { task, from, taken, scope, beforeRun } = checked;
@@ -658,8 +708,10 @@ export function fire(db, board, entry, id, name, { roles = [], payload = {}, ext
   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);
+    record(db,id,'dispatch_released',{reason:`explicit ${name}`,incident:scope.card.last_events.run_incident?.payload?.run ?? null,...(ended ? { ended_run: ended } : {}),
+      ...(ended && name === 'set' && payload.field === 'assignee' && (payload.value ?? null) !== (task.assignee ?? null)
+        ? { reassigned_from: task.assignee ?? null, reassigned_to: payload.value ?? null, abandon_waiting_input: true } : {})});
+  queueTransitionNotice(db, board, entry, task, from, name, payload, beforeRun, effects, noticeSession);
   return { from, to: statusOf(db, cardOf(db, id)), moved: to !== from, effects };
 }
 
@@ -690,7 +742,7 @@ function cardOf(db, id) {
   const row = one(db, 'SELECT * FROM tasks WHERE id = ?', id);
   if (!row) throw new Error(`no card ${id}`);
   const ours = one(db, 'SELECT * FROM supercode_cards WHERE task_id = ?', id);
-  return { ...row, blocked_by: json(ours?.blocked_by, []) ?? [], paused: json(ours?.paused, null), archived: Boolean(ours?.archived), skills: json(row.skills, []) ?? [], machine: ours?.machine ?? null, subtask_of: ours?.subtask_of ?? null };
+  return { ...row, blocked_by: json(ours?.blocked_by, []) ?? [], paused: json(ours?.paused, null), detached: json(ours?.detached, null), archived: Boolean(ours?.archived), skills: json(row.skills, []) ?? [], machine: ours?.machine ?? null, subtask_of: ours?.subtask_of ?? null };
 }
 
 // one transition: the old status's exit actions, the move, the transition's actions, the new status's entry actions
@@ -724,6 +776,7 @@ export function setStatus(db, workflow, id, status) {
 /** Take every `always` transition that holds, from wherever the card is, until none does. */
 export function settle(db, board, entry, id, effects = []) {
   const { workflow, params } = entry;
+  if (detachedCard(db, id)) return effects;
   settleRelations(db, board, entry, id, effects);
   for (let hops = 0; hops < 16; hops += 1) {
     const task = cardOf(db, id);
@@ -813,7 +866,9 @@ const FORMAT = {
   blocked: ({ e, after, source }) => ({ reason: e.reason ?? null, on: e.on ?? null, waiting_on: e.waiting_on ?? null, recurrences: Number(after.block_recurrences || 0), source_status: source }),
   block_loop_detected: ({ e, after, source, params }) => ({ reason: e.reason ?? null, kind: e.kind ?? null, recurrences: Number(after.block_recurrences || 0), limit: params.block_recurrence_limit, source_status: source }),
   dependency_wait: ({ e, source }) => ({ reason: e.reason ?? null, on: e.on ?? null, source_status: source }),
-  review_requested: ({ e, before, after }) => ({ summary: firstLine(e.summary), ci: e.ci ?? null, pr: e.ci?.pr ?? null, commit: e.ci?.commit ?? null, implementer: before.assignee, reviewer: after.assignee !== before.assignee ? after.assignee : (e.reviewer ?? null) }),
+  review_requested: ({ e, before, after }) => ({ summary: firstLine(e.summary), ci: e.ci ?? null, pr: e.ci?.pr ?? null, commit: e.ci?.commit ?? null,
+    implementer: before.assignee, implementer_machine: before.machine ?? null, implementer_model: before.implementer_model ?? null,
+    implementer_model_override: before.model_override ?? null, implementer_provider_override: before.provider_override ?? null, reviewer: after.assignee }),
   // 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 }),
@@ -922,9 +977,15 @@ const ACTIONS = {
     } else record(ctx.db, on ?? ctx.id, kind, payload && Object.keys(payload).length ? payload : null, on ? null : ctx.runId);
   },
   assign(ctx, { field, value }) {
+    if (field === 'reviewer') {
+      if (value != null && (typeof value !== 'string' || !ctx.entry.profiles?.[value]?.worker?.harness)) throw new Error('A card reviewer names a runnable profile in this home.');
+      record(ctx.db, ctx.id, 'reviewer_set', { reviewer: value ?? null }, ctx.runId);
+      return;
+    }
     if (field === 'machine') {
       const task = one(ctx.db, 'SELECT t.current_run_id,t.workspace_kind,c.workspace_anchor,c.machine FROM tasks t JOIN supercode_cards c ON c.task_id=t.id WHERE t.id=?', ctx.id);
       if (task.current_run_id) throw new Error('End the current run before moving its card.');
+      if ((value ?? null) === task.machine) return;
       if (task.workspace_kind !== 'scratch' && (!task.workspace_anchor || isWorkspacePath(task.workspace_anchor))) throw new Error('declare the repository and branch with workflow specify --workspace before moving a legacy path card');
       if ((value ?? null) !== task.machine) run(ctx.db, 'UPDATE tasks SET workspace_path=NULL WHERE id=?', ctx.id);
       cardField(ctx, 'machine', value ?? null);
@@ -984,6 +1045,7 @@ const ACTIONS = {
     run(ctx.db, 'UPDATE tasks SET current_run_id = NULL, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL WHERE id = ?', ctx.id);
   },
   claim(ctx, role, scope) {
+    if (detachedCard(ctx.db, ctx.id)) throw new Error('a detached card must receive a verified adoption before starting another run');
     const task = cardOf(ctx.db, ctx.id);
     const t = now();
     const ttl = Number(ctx.entry.params.claim_ttl_seconds) || 900;
@@ -1139,7 +1201,7 @@ export function retireSupersededRuns(db, id, runId, session) {
       OR (? IS NOT NULL AND json_extract(metadata, '$.supercode.pane') = ?))`,
     runId, session.machine ?? null, session.session_id ?? null, session.session_id ?? null, session.pane ?? null, session.pane ?? null)) {
     const whole = json(old.metadata, {}) ?? {}, s = whole.supercode;
-    if (!s || s.machine !== session.machine || !((session.session_id && s.session_id === session.session_id) || (session.pane && s.pane === session.pane))) continue;
+    if (!s || detachedSession(db, s) || s.machine !== session.machine || !((session.session_id && s.session_id === session.session_id) || (session.pane && s.pane === session.pane))) continue;
     if (old.task_id !== id && one(db, 'SELECT 1 FROM tasks WHERE current_run_id = ?', old.id)) throw new Error(`session is still owned by active run ${old.id} of ${old.task_id}`);
     if (s.pane && s.pane === session.pane) whole.supercode = { ...s, close_transferred_to: runId, close_requested: null };
     run(db, "UPDATE task_runs SET status='superseded', outcome='superseded', ended_at=?, claim_lock=NULL, claim_expires=NULL, worker_pid=NULL, metadata=? WHERE id=?", now(), JSON.stringify(whole), old.id);
@@ -1159,6 +1221,7 @@ export function requestSessionClose(db, id, { runId = null, slot = null, through
     if ((runId != null && row.id !== runId) || (through != null && row.id > through)) continue;
     const whole = json(row.metadata, {}) ?? {};
     const session = whole.supercode;
+    if (detachedSession(db, session)) continue;
     if ((!session?.pane && !session?.launch_key && !(session?.surface === 'native' && session.session_id)) || session.close_transferred_to || session.close_confirmed_at || (slot != null && (session.slot ?? 'worker') !== slot)) continue;
     if (session.close_requested && !session.closed_at) continue;
     whole.supercode = { ...session, close_requested: session.close_requested ?? now() };

package/board/ztrack.mjs

@@ -7,6 +7,10 @@
 // triggers name the rows it touched. Only the cards whose text changed are rendered, and each is
 // spliced into the document at its indexed span. A document edited by hand is re-read only in the
 // region the edit touched. So a write costs what it changes, not the size of the board.
+//
+// A listing answered on the owner's read door (owner-door.mjs) opens the board read-only on a connection of its own and
+// reads it in one SQLite read transaction: WAL gives it the rows as one committed state, and no writer waits on it or
+// it on a writer. The documents are taken with that state (readSnapshot), never locked.
 import { current } from './call.mjs';
 import { fenced } from './fence.mjs';
 import { createRequire } from 'node:module';
@@ -14,7 +18,7 @@ import { createHash, randomBytes } from 'node:crypto';
 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, storageFault, STORAGE_TRIES } from './store.mjs';
+import { actorOf, contention, event, json, now, principalOf, storageFault, STORAGE_TRIES, unreadable } from './store.mjs';
 import { GitDocument } from './git-document.mjs';
 import { unimported } from './legacy-store.mjs';
 import { noteStep, recordSlow } from '@volter/supercode-harness-sdk/slow-log';
@@ -68,11 +72,13 @@ const timedStatement = (sql, fn) => {
   finally { noteStatement(sql, started, before); }
 };
 import { fire, workflowFor } from './workflow.mjs';
-import { LIST_REVISION, listRevision, TASK_SUMMARY_INDEX, TASK_SUMMARY_INDEX_SQL } from './listing.mjs';
+import { byOwner, LIST_REVISION, listRevision, TASK_SUMMARY_INDEX, TASK_SUMMARY_INDEX_SQL } from './listing.mjs';
 
 const require = createRequire(import.meta.url);
 const hash = (text) => createHash('sha256').update(text).digest('hex');
 const read = (path) => existsSync(path) ? readFileSync(path, 'utf8') : '';
+// What says a document changed: a write in place moves its size or times, a replacement its inode.
+const stampOf = (path) => { try { const s = statSync(path); return `${s.ino}:${s.size}:${s.mtimeMs}:${s.ctimeMs}`; } catch { return 'missing'; } };
 const lf = (text) => text.replace(/\r\n?/g, '\n');
 const quote = (s) => `"${String(s).replaceAll('"', '""')}"`;
 const nativeId = (id) => /^t-[a-f0-9]+$/.test(id) ? id.replace('t-', 't_') : id;
@@ -94,6 +100,9 @@ const sqliteContention = (error) => contention(error); // resolved at call time:
 const RETRY = new Error('board changed while this operation read it; retry');
 // The current archive's size before it rotates, unless the board declares its own (`archive.max_lines`).
 const ARCHIVE_LINES = 2000;
+// How many read transactions a listing begins before it leaves the board to its owner, each begun again only because a
+// document changed while it was read (readSnapshot).
+const SNAPSHOT_TRIES = 8;
 const isArchive = (role) => role === 'archived' || String(role ?? '').startsWith('archived:');
 
 const BOARD_TABLES = `
@@ -109,7 +118,7 @@ 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, declared = null, seed = null, init, root, slug, held = false }) {
+export function openZtrackBoard(marker, { create = false, document = null, declared = null, seed = null, init, root, slug, held = false, readOnly = false }) {
   if (!existsSync(marker)) {
     if (!create) throw new Error(`no ztrack board ${marker}`);
     mkdirSync(dirname(marker), { recursive: true });
@@ -123,18 +132,20 @@ export function openZtrackBoard(marker, { create = false, document = null, decla
     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, held });
+  const backing = new ZtrackBoard({ ...config, seed, marker, init, root, slug, held, readOnly });
   return { db: backing.db, tx: (fn) => backing.tx(fn), publishPending: () => backing.git?.publishPending(), unimported: () => backing.unimported(), close: () => backing.close(), document: backing.path,
     documentsChanged: () => backing.documentsChanged(), documentsUnwatched: (unwatched) => { backing.unwatched = unwatched; }, saidOnOpen: () => backing.sayLate() };
 }
 
 
 class ZtrackBoard {
-  constructor({ document, seed, marker, init, root, slug, commit = false, manager = null, archive = {}, held = false }) {
+  constructor({ document, seed, marker, init, root, slug, commit = false, manager = null, archive = {}, held = false, readOnly = false }) {
     // held by the board owner (store.mjs holdBoards): opened once, its documents' stamps read again only when the
     // owner's watch says they changed or may have lost events (documentsChanged), and on every read while it keeps no
     // watch on them (unwatched); git's lateness held and refreshed on its own commits
     this.held = held; this.docsChanged = true; this.importDue = true; this.knownStamps = null;
+    // a listing's read-only view (readSnapshot): it makes, migrates, recovers, pulls and commits nothing
+    this.readOnly = readOnly;
     this.path = resolve(dirname(marker), document);
     this.archive = `${this.path}.archive.md`;
     this.baseDocs = [{ role: 'open', path: this.path }, { role: 'archived', path: this.archive }];
@@ -147,7 +158,7 @@ class ZtrackBoard {
     // `"manager"`: the board's manager (its principal or session address), whose writes it commits itself as part of its
     // own work; the backing commits only the writes the manager does not make.
     this.manager = manager;
-    this.git = commit ? new GitDocument(this.baseDocs.map((doc) => doc.path), (base, theirs, ours, path) => { try { return this.codec.mergeBoardDocument(base, theirs, ours, path)?.text ?? null; } catch { return null; } }) : null;
+    this.git = commit && !readOnly ? new GitDocument(this.baseDocs.map((doc) => doc.path), (base, theirs, ours, path) => { try { return this.codec.mergeBoardDocument(base, theirs, ours, path)?.text ?? null; } catch { return null; } }) : null;
     // what a fetch brought is written in the board's next transaction: one soon, on this loop, if none comes
     if (this.git) this.git.onTaken = () => setImmediate(() => { try { if (!this.closed) this.tx(() => {}); } catch (error) { current().err(`board: ${error.message}\n`); } });
     // A publish that is behind is said once per call, on whichever workflow verb opened the board: a refused push
@@ -158,18 +169,25 @@ class ZtrackBoard {
     else if (this.git) this.sayLate(timedStep('board open git behind', () => this.git.behind()));
     this.seed = seed; this.root = root; this.slug = slug; this.init = init;
     this.file = `${marker}.board.db`;
-    mkdirSync(dirname(this.path), { recursive: true });
+    // the store is the owner's to make, import and lay out: a listing that finds none leaves the board to it
+    if (readOnly && !(existsSync(this.file) && statSync(this.file).size > 0)) throw byOwner(`${this.file} is not laid out yet`);
+    if (!readOnly) mkdirSync(dirname(this.path), { recursive: true });
     const legacy = `${marker}.runtime.db`;
     // A 0-byte file is no store: a read through the sqlite3 CLI creates one at a path that has none (on 2026-10-01 a
     // `sqlite3 <store> "select …"` made the empty file the next release then opened instead of importing).
-    if (existsSync(this.file) && statSync(this.file).size === 0) unlinkSync(this.file);
+    if (!readOnly && existsSync(this.file) && statSync(this.file).size === 0) unlinkSync(this.file);
     if (!existsSync(this.file)) this.create(legacy);
-    this.conn = timedStep('board open connection', () => new DatabaseSync(this.file));
-    this.refuseUnimported(legacy);
+    this.conn = timedStep('board open connection', () => {
+      if (!readOnly) return new DatabaseSync(this.file);
+      try { return new DatabaseSync(this.file, { readOnly: true }); } catch (error) { throw unreadable(error) ? byOwner(error.message) : error; }
+    });
+    if (!readOnly) this.refuseUnimported(legacy);
     this.errors = new Map(); this.statements = new Map(); this.hashes = new Map();
     this.active = false; this.overlay = false; this.seen = null; this.refused = new Set();
-    timedStep('board open schema', () => this.prepareConnection());
-    timedStep('board open errors', () => this.loadErrors());
+    if (!readOnly) {
+      timedStep('board open schema', () => this.prepareConnection());
+      timedStep('board open errors', () => this.loadErrors());
+    }
     const self = this;
     this.db = {
       [LIST_REVISION]: () => self.read(() => listRevision(self.conn)),
@@ -185,10 +203,49 @@ class ZtrackBoard {
       exec(sql) { const run = () => timedStatement(sql, () => self.conn.exec(sql)); return self.active ? self.noting(run) : self.tx(run); },
       close() { self.close(); },
     };
+    if (readOnly) {
+      try { timedStep('board read: snapshot', () => this.readSnapshot()); }
+      catch (error) { this.conn.close(); throw error; }
+      return;
+    }
     // A board's first open in this process recovers what its store accepted and derives what git owes for it (tx), so
     // a board that is only read, or whose owner runs no round, still finishes an earlier process's commit.
     if (seed || this.git?.underived) this.tx(() => {});
   }
+
+  // A listing's view, taken once at its open and kept until its close: the store's rows as of one read transaction, and
+  // every document as it stood when that transaction began. A document is written only after the transaction that
+  // published it committed, so a document that stood unchanged from before the transaction began until after it was
+  // read is one the transaction already describes: its published text, the text a pending publication replaces (the
+  // rows stay authoritative), or a hand edit, which is shown through connection-local copies of the card tables as
+  // every reader shows one. A document that changed in between is read again with a new transaction. Nothing here waits:
+  // WAL serves the read transaction beside any writer, and no busy timeout is set. A store not in WAL or not laid out,
+  // one a read-only connection cannot begin reading (store.mjs unreadable) or documents that keep changing leave the
+  // listing to the owner.
+  readSnapshot() {
+    const contended = (fn) => { try { return fn(); } catch (error) { throw unreadable(error) ? byOwner(error.message) : error; } };
+    if (String(contended(() => this.conn.prepare('PRAGMA journal_mode').get())?.journal_mode).toLowerCase() !== 'wal') throw byOwner(`${this.file} is not in WAL mode`);
+    for (let attempt = 0; attempt < SNAPSHOT_TRIES; attempt++) {
+      const stamps = () => this.docs.map((doc) => `${doc.path}\0${stampOf(doc.path)}`).join('\n');
+      const before = contended(stamps);
+      this.conn.exec('BEGIN');
+      let stale;
+      try {
+        // the transaction's first read begins its snapshot
+        if (!contended(() => this.one("SELECT 1 FROM main.sqlite_master WHERE type = 'index' AND name = ?", TASK_SUMMARY_INDEX))) throw byOwner(`${this.file} is not laid out yet`);
+        this.loadErrors();
+        stale = this.staleDocuments({ pending: true });
+        if (stamps() !== before) { this.conn.exec('ROLLBACK'); this.hashes.clear(); continue; }
+      } catch (error) { try { this.conn.exec('ROLLBACK'); } catch { /* not begun */ } throw error; }
+      if (!stale.length) return;
+      this.tables = this.shapes();
+      let plan;
+      try { plan = this.observe(stale); } catch { return; } // the next write reports it
+      this.applyPlan(plan, { overlay: true });
+      return;
+    }
+    throw byOwner('its documents changed during every read');
+  }
   /** The publish's lateness, said once per call (a held board's from its held reading, never by asking git). */
   sayLate(late = this.git?.lateness ?? null) {
     const said = current().said;
@@ -246,14 +303,9 @@ class ZtrackBoard {
     // What a transaction touched, for the renderer (cards whose text may change: anything beyond run fields and scheduling clocks). Plain inserts: a trigger's
     // own conflict clause yields to the outer statement's, so duplicates are removed when read.
     this.conn.exec('CREATE TEMP TABLE IF NOT EXISTS board_dirty (name TEXT NOT NULL, key TEXT NOT NULL); CREATE TEMP TABLE IF NOT EXISTS board_touched (id TEXT)');
-    this.tables = new Map();
-    const names = this.conn.prepare("SELECT name FROM main.sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE 'board_%'").all().map((row) => row.name);
+    this.tables = this.shapes();
     const trigger = (name, when, body) => this.conn.exec(`CREATE TEMP TRIGGER IF NOT EXISTS ${quote(name)} ${when} BEGIN ${body} END`);
-    for (const name of names) {
-      const columns = this.conn.prepare(`PRAGMA main.table_info(${quote(name)})`).all();
-      const keys = columns.filter((c) => c.pk).sort((a, b) => a.pk - b.pk).map((c) => c.name);
-      if (!keys.length) keys.push('rowid');
-      this.tables.set(name, { name, keys, columns: columns.map((c) => c.name) });
+    for (const { name, keys } of this.tables.values()) {
       const key = (row) => `json_array(${keys.map((k) => `${row}.${quote(k)}`).join(',')})`;
       const mark = (row) => `INSERT INTO board_dirty VALUES ('${name}', ${key(row)});`;
       trigger(`board_i_${name}`, `AFTER INSERT ON main.${quote(name)}`, mark('NEW'));
@@ -268,6 +320,18 @@ class ZtrackBoard {
     }
   }
 
+  // Each runtime table's columns and key, as the store has them.
+  shapes() {
+    const tables = new Map();
+    for (const { name } of this.conn.prepare("SELECT name FROM main.sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE 'board_%'").all()) {
+      const columns = this.conn.prepare(`PRAGMA main.table_info(${quote(name)})`).all();
+      const keys = columns.filter((c) => c.pk).sort((a, b) => a.pk - b.pk).map((c) => c.name);
+      if (!keys.length) keys.push('rowid');
+      tables.set(name, { name, keys, columns: columns.map((c) => c.name) });
+    }
+    return tables;
+  }
+
   // A store holding fewer runs than the earlier store beside it was made without the one-time import (on 2026-10-01
   // one such store, created by an opener nobody named, sent the dispatcher on to start a second session on every
   // running card). The board refuses it, so nothing runs on a board without its history.
@@ -388,6 +452,8 @@ class ZtrackBoard {
   }
 
   read(fn) {
+    // a listing's view is its snapshot's (readSnapshot): its statements read that, never the documents again
+    if (this.readOnly) return fn();
     if (this.active) return this.noting(fn);
     this.observeForRead();
     for (let attempt = 0; ; attempt++) {
@@ -397,8 +463,7 @@ class ZtrackBoard {
   }
 
   fileHash(path) {
-    let stamp;
-    try { const s = statSync(path); stamp = `${s.ino}:${s.size}:${s.mtimeMs}:${s.ctimeMs}`; } catch { stamp = 'missing'; }
+    const stamp = stampOf(path);
     const known = this.hashes.get(path);
     if (known?.stamp === stamp) return known;
     const raw = read(path);
@@ -462,6 +527,7 @@ class ZtrackBoard {
   // ------------------------------------------------------------------ writes
 
   tx(fn) {
+    if (this.readOnly) throw new Error('a listing reads the board and writes nothing');
     // A write inside a write is part of it: the pull below happened once, for the outermost one.
     if (this.active) return fn(this.db);
     // A pull request merged on the remote (a page edited in Git Notes) is in the document before this write reads it.

package/board-input.d.ts

@@ -0,0 +1,2 @@
+/** Read a remote card write's selected text file (or stdin) on the caller's machine. */
+export function prepareBoardText(argv: string[]): { argv: string[]; stdin: string | null };

package/board-input.mjs

@@ -0,0 +1,16 @@
+// A remote card write reads its text on the caller's machine, before the board door is called.
+// The board's own argument parser decides which file is used; its last value wins.
+import { readFileSync } from 'node:fs';
+import { parse } from './board/args.mjs';
+
+/** Carry a comment/create/specify text input as the owner's existing `stdin` field. */
+export function prepareBoardText(argv) {
+  const args = parse(argv);
+  const verb = args._[0];
+  const key = verb === 'comment' ? 'file' : ['create', 'specify'].includes(verb) ? 'body-file' : null;
+  const file = key === null || args.help ? undefined : args[key];
+  if (file === undefined) return { argv, stdin: null };
+  // Appending the selected flag preserves every other argument and overrides earlier occurrences. The owner
+  // reads the carried text at `-`, never an unrelated file at the caller's original path on another machine.
+  return { argv: [...argv, `--${key}`, '-'], stdin: readFileSync(file === '-' ? 0 : file, 'utf8') };
+}