@volter/supercode-orchestrator 0.4.148 → 0.4.149

package/board/engine.mjs

@@ -37,7 +37,7 @@ export function getTask(db, id) {
   const row = one(db, 'SELECT * FROM tasks WHERE id = ?', id);
   if (!row) return null;
   const ours = one(db, 'SELECT * FROM supercode_cards WHERE task_id = ?', id);
-  return { ...row, workspace_anchor: ours?.workspace_anchor ?? null, review_only: Boolean(ours?.review_only), blocked_by: json(ours?.blocked_by, []) ?? [], paused: json(ours?.paused, null), archived: Boolean(ours?.archived), every: ours?.every ?? null, skills: json(row.skills, []) ?? [], machine: ours?.machine ?? null, subtask_of: ours?.subtask_of ?? null };
+  return { ...row, workspace_anchor: ours?.workspace_anchor ?? null, blocked_by: json(ours?.blocked_by, []) ?? [], paused: json(ours?.paused, null), archived: Boolean(ours?.archived), every: ours?.every ?? null, skills: json(row.skills, []) ?? [], machine: ours?.machine ?? null, subtask_of: ours?.subtask_of ?? null };
 }
 
 function must(db, id) {
@@ -152,10 +152,36 @@ function projectOf(root, idOrSlug) {
   } catch { return null; } finally { db.close(); }
 }
 
+/**
+ * A card's Tasks are its subtasks (the document renders them as its Tasks section). Task lines written in an arc's
+ * body (`## Tasks` then `- [ ] step`, its indented lines the step's own text) are answered as the steps to file as
+ * its subtasks, and leave the body. A Tasks section with no task line is the body's own text.
+ */
+export function bodyTasks(body) {
+  const lines = String(body ?? '').split('\n');
+  const at = lines.findIndex((line) => /^#{2,3}\s+Tasks\s*$/i.test(line));
+  if (at < 0) return { body, tasks: [] };
+  let end = lines.findIndex((line, i) => i > at && /^#{1,3}\s/.test(line));
+  if (end < 0) end = lines.length;
+  const section = lines.slice(at + 1, end);
+  if (!section.some((line) => /^[-*] \[[ xX]\]/.test(line))) return { body, tasks: [] };
+  const tasks = [];
+  for (const line of section) {
+    if (!line.trim()) continue;
+    const step = /^[-*] \[ \]\s+(\S.*)$/.exec(line);
+    if (step) tasks.push({ title: step[1].trim(), body: [] });
+    else if (/^\s+\S/.test(line) && tasks.length) tasks.at(-1).body.push(line.replace(/^\s{1,4}/, ''));
+    else throw new Error("A card's Tasks section holds open task lines ('- [ ] <step>', each filed as a subtask, with its own indented lines); record finished work as a comment and move other text out of the section");
+  }
+  const rest = [...lines.slice(0, at), ...lines.slice(end)].join('\n').replace(/\n{3,}/g, '\n\n').trim();
+  return { body: rest || null, tasks: tasks.map((t) => ({ title: t.title, body: t.body.join('\n') || null })) };
+}
+
 export function createCard(board, spec) {
-  if (spec.reviewOnly !== undefined && typeof spec.reviewOnly !== 'boolean') throw new Error('reviewOnly must be a boolean');
   const title = String(spec.title ?? '').trim();
   if (!title) throw new Error('a card has a title');
+  const steps = spec.subtaskOf ? [] : bodyTasks(spec.body).tasks;
+  if (steps.length) spec = { ...spec, body: bodyTasks(spec.body).body };
   const ws = parseWorkspace(spec.workspace ?? 'scratch');
   if (spec.branch && ws.kind === 'scratch') throw new Error('a scratch workspace has no repository branch');
   const parents = [...new Set((spec.parents ?? []).filter(Boolean))];
@@ -184,10 +210,6 @@ export function createCard(board, spec) {
     if (missing.length) throw new Error(`unknown parent card(s): ${missing.join(', ')}`);
     const arc = spec.subtaskOf ? getTask(db, spec.subtaskOf) : null;
     const entry = workflowFor(board.root);
-    if (spec.reviewOnly) {
-      const permitted = entry.params.review_only_by;
-      if (arc || spec.every || initial || !Array.isArray(permitted) || !callerRoles(db, arc?.id ?? '').some(role => permitted.includes(role))) throw new Error('Only a permitted manager creates a review-only arc, without recurrence, subtasks or an initial-status override.');
-    }
     if (spec.subtaskOf && !arc) throw new Error(`no card ${spec.subtaskOf} to be a subtask of`);
     if (arc?.subtask_of) throw new Error(`${arc.id} is itself a subtask of ${arc.subtask_of}; a subtask belongs to an arc`);
     let id = newTaskId();
@@ -216,13 +238,13 @@ export function createCard(board, spec) {
       spec.skills?.length ? JSON.stringify(spec.skills) : null, spec.maxRetries ?? null, spec.model ?? null, spec.provider ?? null,
       spec.reasoning ?? null, spec.sessionId ?? null, spec.project ?? null, spec.goal ? 1 : 0, spec.goal?.maxTurns ?? null);
     const machine = spec.machine ?? arc?.machine ?? null;
-    run(db, 'INSERT OR REPLACE INTO supercode_cards (task_id,machine,subtask_of,workspace_anchor,workspace_root,review_only) VALUES (?,?,?,?,?,?)', id, machine, arc?.id ?? null, declared.repository, checked?.mainRoot ?? null, spec.reviewOnly ? 1 : 0);
+    run(db, 'INSERT OR REPLACE INTO supercode_cards (task_id,machine,subtask_of,workspace_anchor,workspace_root) VALUES (?,?,?,?,?)', id, machine, arc?.id ?? null, declared.repository, checked?.mainRoot ?? null);
     for (const p of parents) addDependency(db, entry, id, p);
     // where it starts is the workflow's `initial` (Hermes: triage, blocked, todo behind open parents, else ready)
     // the create's own words: whether it asked to be a goal card (null: the workflow decides), triage, its arc
     const status = startNew(db, board, entry, getTask(db, id), { triage: Boolean(spec.triage), initial_status: initial,
-      review_only: Boolean(spec.reviewOnly), every: spec.every ?? null, goal: spec.goal === undefined || spec.goal === null ? null : spec.goal !== false, subtask_of: arc?.id ?? null });
-    event(db, id, 'created', { creator: actorOf(), assignee: spec.assignee || null, status, review_only: Boolean(spec.reviewOnly), parents, tenant: spec.tenant ?? null, ...(machine ? { machine } : {}), ...(arc ? { subtask_of: arc.id } : {}) });
+      every: spec.every ?? null, goal: spec.goal === undefined || spec.goal === null ? null : spec.goal !== false, subtask_of: arc?.id ?? null });
+    event(db, id, 'created', { creator: actorOf(), assignee: spec.assignee || null, status, parents, tenant: spec.tenant ?? null, ...(machine ? { machine } : {}), ...(arc ? { subtask_of: arc.id } : {}) });
     if ((spec.noStart || spec.adopt) && !arc) event(db, id, 'dispatch_held', { session: spec.adopt ?? null, reason: spec.adopt ? 'awaiting adoption' : 'created with --no-start' });
     if (parents.length) inheritSubscriptions(db, id, parents);
     if (arc) {
@@ -232,7 +254,9 @@ export function createCard(board, spec) {
     }
     if (initial === 'running' && arc && entry.workflow.run) setStatus(db, entry.workflow, id, 'running');
     else if (initial === 'running') claimIn(db, id, { ttl: claimTtl() });
-    return { id, existing: false };
+    // the body's task lines, as subtasks the creator filed, in this same write
+    const subtasks = steps.map((step) => createCard(board, { ...step, subtaskOf: id, assignee: spec.assignee || null }).id);
+    return { id, existing: false, ...(subtasks.length ? { subtasks } : {}) };
   });
 }
 
@@ -345,8 +369,9 @@ export async function act(board, id, name, { roles = null, payload = {}, extra =
   const entry = await loadWorkflow(board.root);
   if (name === 'comment' && (!String(payload.body ?? '').trim() || !String(payload.author ?? '').trim())) throw new Error('a comment has an author and body');
   refreshCardInputs(board, id, { commits: ['complete', 'request_review'].includes(name) });
-  if (['complete', 'request_review', 'request_state'].includes(name)) payload = { ...payload, ci: observeCompletionEvidence(board, id, entry, payload, completionPhase(board, id, entry, name, payload, roles ?? callerRoles(board.db, id))) };
-  if (payload.ci?.required && !payload.ci.ready) throw new Error(payload.ci.reason ?? 'The PR candidate could not be verified.');
+  const evidencePhase = ['complete', 'request_review', 'request_state'].includes(name) ? completionPhase(board, id, entry, name, payload, roles ?? callerRoles(board.db, id)) : null;
+  if (evidencePhase) payload = { ...payload, ci: observeCompletionEvidence(board, id, entry, payload, evidencePhase) };
+  if (payload.ci?.required && !payload.ci.ready && (name !== 'request_state' || evidencePhase === 'review_verdict')) throw new Error(payload.ci.reason ?? 'The PR candidate could not be verified.');
   const result = tx(board, (db) => {
     roles ??= callerRoles(db, id);
     const r = fire(db, board, entry, id, name, { roles, payload, extra });
@@ -368,9 +393,14 @@ export async function requestStateMany(board, ids, payload = {}) {
   const entry = await loadWorkflow(board.root);
   const prepared = new Map(targets.map(id => {
     const roles = callerRoles(board.db, id);
-    return [id, inspectCompletionEvidence(board, id, entry, payload, completionPhase(board, id, entry, 'request_state', payload, roles))];
+    const phase = completionPhase(board, id, entry, 'request_state', payload, roles);
+    const evidence = inspectCompletionEvidence(board, id, entry, payload, phase);
+    // An ordinary request mails a decision to the manager, not a completion.
+    // Keep a failed source observation in that mail. A reviewer recording an
+    // actual verdict still has to verify the requested PR head.
+    if (phase === 'review_verdict' && evidence.required && !evidence.ready) throw new Error(evidence.reason ?? 'The reviewed PR head could not be verified.');
+    return [id, evidence];
   }));
-  for (const evidence of prepared.values()) if (evidence.required && !evidence.ready) throw new Error(evidence.reason ?? 'The reviewed PR head could not be verified.');
   const result = tx(board, db => {
     const effects = [];
     const results = targets.map(id => withCompletionEvidence(board, id, prepared.get(id), () => {
@@ -494,7 +524,7 @@ export const schedule = (board, id, reason = null, { roles } = {}) => act(board,
 export const promote = (board, id, { actor = 'user', reason = null, force = false, roles } = {}) => act(board, id, 'promote', { roles, payload: { actor, reason, force } });
 export const reclaim = (board, id, reason = null, { roles } = {}) => act(board, id, 'reclaim', { roles, payload: { reason } });
 export const archive = (board, id, { roles } = {}) => act(board, id, 'archive', { roles });
-export function specify(board, id, { title = null, body = null, workspace = null, branch = null, reviewOnly = null, author = 'user', roles } = {}) {
+export async function specify(board, id, { title = null, body = null, workspace = null, branch = null, author = 'user', roles } = {}) {
   let declaration = null;
   if (workspace != null || branch != null) {
     const task = getTask(board.db, id);
@@ -507,8 +537,11 @@ export function specify(board, id, { title = null, body = null, workspace = null
     if (declaration.kind === 'worktree') declaration.branch ??= `wt/${id}`;
     if (declaration.kind === 'dir') declaration.path = checkWorkspace(board, { ...task, workspace_kind: declaration.kind, workspace_anchor: declaration.repository, workspace_path: declaration.path, branch_name: declaration.branch }).path;
   }
-  if (reviewOnly != null && (typeof reviewOnly !== 'boolean' || !Array.isArray(workflowFor(board.root).params.review_only_by))) throw new Error('This workflow must declare review_only_by before a boolean review-only declaration is changed.');
-  return act(board, id, 'specify', { roles, payload: { title, body, author, ...(reviewOnly != null ? { review_only: reviewOnly } : {}), ...(declaration ? { workspace: declaration } : {}) } });
+  // an arc's new task lines are filed as its subtasks once the specify itself is accepted
+  const steps = body != null && !one(board.db, 'SELECT subtask_of FROM supercode_cards WHERE task_id = ?', id)?.subtask_of ? bodyTasks(body) : { body, tasks: [] };
+  const done = await act(board, id, 'specify', { roles, payload: { title, body: steps.body, author, ...(declaration ? { workspace: declaration } : {}) } });
+  for (const step of steps.tasks) createCard(board, { ...step, subtaskOf: id, assignee: getTask(board.db, id)?.assignee || null });
+  return done;
 }
 export const editResult = (board, id, { result, summary = null, metadata = undefined, roles } = {}) => act(board, id, 'edit', { roles, payload: { result, summary, metadata } });
 export const heartbeat = (board, id, note = null, { roles, until = null } = {}) => act(board, id, 'heartbeat', { roles, payload: { note, until } });
@@ -665,7 +698,6 @@ export function cardContext(db, id) {
   const task = must(db, id);
   const out = [`# Card ${task.id}: ${task.title}`, ''];
   out.push(`Status: ${task.status}. Machine: ${task.machine ?? 'unset'}. Workspace: ${task.workspace_kind}${task.workspace_anchor ? ` ${task.workspace_anchor}` : task.workspace_path ? ` ${task.workspace_path}` : ''}${task.branch_name ? ` (branch ${task.branch_name})` : ''}.${task.subtask_of ? ` A subtask of ${task.subtask_of}.` : ''}`);
-  if (task.review_only) out.push('Purpose: review-only. Record the independent verdict with request-state --state done --reason <verdict> --evidence <artifact>; its creator or manager accepts this review job.');
   if (task.body) out.push('', cap(task.body, 8 * 1024));
   const parents = all(db, 'SELECT t.id, t.title, t.result FROM tasks t JOIN task_links l ON l.parent_id = t.id WHERE l.child_id = ?', id);
   if (parents.length) {

package/board/store.mjs

@@ -73,7 +73,7 @@ const OURS = `CREATE TABLE IF NOT EXISTS supercode_cards (task_id TEXT PRIMARY K
 CREATE TABLE IF NOT EXISTS supercode_effects (id INTEGER PRIMARY KEY AUTOINCREMENT, effect TEXT NOT NULL);`;
 // `stage`: the card's workflow status where kanban.db stores another (a `reviewing` card is `running` to Hermes)
 // `since`: when the card entered its workflow status; `after_fired`: which of the status's `after` moves have run since
-const OURS_COLUMNS = { workspace_anchor: 'TEXT', workspace_root: 'TEXT', subtask_of: 'TEXT', review_only: 'INTEGER DEFAULT 0', stage: 'TEXT', since: 'INTEGER', after_fired: 'TEXT', blocked_by: 'TEXT', paused: 'TEXT', archived: 'INTEGER DEFAULT 0', every: 'TEXT', next_run_at: 'INTEGER' };
+const OURS_COLUMNS = { workspace_anchor: 'TEXT', workspace_root: 'TEXT', subtask_of: 'TEXT', stage: 'TEXT', since: 'INTEGER', after_fired: 'TEXT', blocked_by: 'TEXT', paused: 'TEXT', archived: 'INTEGER DEFAULT 0', every: 'TEXT', next_run_at: 'INTEGER' };
 
 // ------------------------------------------------------------------ backings
 //
@@ -172,18 +172,21 @@ export const tx = (board, fn) => {
 export const view = (board, fn) => fn(board.db);
 
 // A deferred native transaction, with the whole operation retried on an optimistic conflict.
-// There is no separate application writer lock or contention timeout.
+// There is no separate application writer lock or contention timeout. A write inside one is part of it.
+const inTx = new WeakSet();
 function sqliteTx(db, fn) {
+  if (inTx.has(db)) return fn(db);
   for (;;) {
     try {
       db.exec('BEGIN');
+      inTx.add(db);
       const out=fn(db);
       db.exec('COMMIT');
       return out;
     } catch(error) {
       try {db.exec('ROLLBACK');} catch {}
       if (!/locked|busy/i.test(error.message))throw error;
-    }
+    } finally { inTx.delete(db); }
   }
 }
 

package/board/tools.mjs

@@ -80,7 +80,7 @@ export async function boardTool(root, name, args = {}, env = {}) {
         return JSON.stringify({
           task: { id: t.id, title: t.title, body: t.body, assignee: t.assignee, status: t.status, tenant: t.tenant, priority: t.priority, workspace_kind: t.workspace_kind,
             workspace_path: t.workspace_path, created_by: t.created_by, created_at: t.created_at, started_at: t.started_at, completed_at: t.completed_at, result: t.result,
-            current_run_id: t.current_run_id, model_override: t.model_override, provider_override: t.provider_override, review_only: Boolean(t.review_only) },
+            current_run_id: t.current_run_id, model_override: t.model_override, provider_override: t.provider_override },
           parents: card.parents.map((p) => p.id), children: card.children,
           comments: card.comments, events: card.events.slice(-50), runs: card.runs.map((r) => ({ id: r.id, profile: r.profile, status: r.status, outcome: r.outcome, summary: r.summary, error: r.error, metadata: r.metadata, started_at: r.started_at, ended_at: r.ended_at })),
           worker_context: card.context,
@@ -176,7 +176,7 @@ export async function boardTool(root, name, args = {}, env = {}) {
           title: args.title, body: args.body ? redact(String(args.body)) : null, assignee: args.assignee ?? 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, reviewOnly: args.review_only ?? false,
+          goal: args.goal_mode ? { maxTurns: args.goal_max_turns ?? null } : null, createdBy: author,
         });
         return ok({ task_id: made.id, existing: made.existing, status: tx(board, (db) => engine.getTask(db, made.id)).status });
       }

package/board/workflow.mjs

@@ -104,7 +104,8 @@ function pattern(p) {
 }
 
 // the time of the latest commit that names `id` in its message, on any ref of the repository at `path` (a worktree's
-// pushes land on the shared remote-tracking refs), or null (asked only when an expression does)
+// pushes land on the shared remote-tracking refs), or null (asked only when an expression does). Merge commits are
+// not the card's work: merging its reviewed PR, or main into its branch, is not a newer change to review.
 const commitTimes = new Map();
 function observeLastCommit(path, id) {
   if (!path) return null;
@@ -112,7 +113,7 @@ function observeLastCommit(path, id) {
   const cached = commitTimes.get(key);
   if (cached && now() - cached.at < 15) return cached.value;
   const readCommit = (repo) => {
-    const r = spawnSync('git', ['-C', repo, 'log', '--all', '-1', '--format=%ct', '--fixed-strings', `--grep=${id}`], { encoding: 'utf8', timeout: 10_000 });
+    const r = spawnSync('git', ['-C', repo, 'log', '--all', '--no-merges', '-1', '--format=%ct', '--fixed-strings', `--grep=${id}`], { encoding: 'utf8', timeout: 10_000 });
     const value = Number(r.stdout?.trim());
     return { repo: r.status === 0, value: Number.isFinite(value) && value > 0 ? value : null };
   };
@@ -201,11 +202,8 @@ function onlyTicks(was, body) {
 
 /** Seconds a card's runs spent by role, and the rest of its life as `waiting`. */
 export function runWorkingSeconds(row, at = now()) {
-  const metadata = typeof row.metadata === 'string' ? json(row.metadata, {}) : row.metadata;
-  const session = metadata?.supercode ?? {};
   const end = Number(row.ended_at ?? at);
-  const waiting = Number(session.wait_seconds ?? 0) + (session.wait_started_at != null ? Math.max(0, end - Number(session.wait_started_at)) : 0);
-  return Math.max(0, end - Number(row.started_at ?? end) - waiting);
+  return Math.max(0, end - Number(row.started_at ?? end));
 }
 
 function timeOf(db, task) {
@@ -250,7 +248,6 @@ export function scopeOf(db, board, task, { params, event = {}, extra = {} } = {}
     ...task,
     creator_address: creatorOf(db, task.id),
     completion_owner_address: completionOwnerOf(db, task.id),
-    review_only: Boolean(state.review_only),
     latest_review: latestReview(db, task.id) ?? {},
     review_candidate: reviewCandidate(board, task.id) ?? {},
     ci: completionEvidence(board, task.id),
@@ -363,6 +360,11 @@ function queueTransitionNotice(db, board, entry, task, from, name, payload, befo
       cancellation?.outcome === 'not_issued' && cancellation?.live === false && cancellation?.pane === null) 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
+  // its own act would only hold its close until the notice is confirmed. A session whose close is
+  // 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 source = one(db, 'SELECT MAX(id) AS id FROM task_events WHERE task_id = ?', task.id)?.id;
@@ -642,17 +644,6 @@ const ACTIONS = {
     const result = fire(ctx.db, ctx.board, ctx.entry, ctx.id, name, { roles: [].concat(as), payload, extra: { lanes: lanesIn(ctx.entry) } });
     ctx.effects.push(...result.effects);
   },
-  wait_run(ctx, waiting) {
-    if (typeof waiting !== 'boolean') throw new Error('wait_run requires a boolean');
-    const at = now();
-    runSession(ctx, session => {
-      if (waiting) return { ...session, wait_started_at: session.wait_started_at ?? at };
-      if (session.wait_started_at == null) return session;
-      return { ...session, wait_started_at: null,
-        wait_seconds: Number(session.wait_seconds ?? 0) + Math.max(0, at - Number(session.wait_started_at)),
-        goal_nudged_at: at };
-    });
-  },
   record(ctx, args, scope) {
     const kind = typeof args === 'string' ? args : args?.kind;
     const given = typeof args === 'object' && args?.payload ? args.payload : null;
@@ -772,12 +763,6 @@ const ACTIONS = {
     run(ctx.db, 'DELETE FROM task_links WHERE parent_id = ? AND child_id = ?', parent, ctx.id);
   },
   specify(ctx, said) {
-    if (said?.review_only != null) {
-      const task = cardOf(ctx.db, ctx.id);
-      if (typeof said.review_only !== 'boolean' || task.current_run_id || task.subtask_of || ctx.scope.card.every) throw new Error('A review-only declaration changes only an arc with no current run or recurrence.');
-      cardField(ctx, 'review_only', said.review_only ? 1 : 0);
-      record(ctx.db, ctx.id, 'review_mode_changed', { review_only: said.review_only }, null);
-    }
     if (said?.workspace) {
       const task = cardOf(ctx.db, ctx.id), ws = said.workspace;
       if (task.current_run_id) throw new Error('end the current run before changing its workspace');
@@ -867,6 +852,8 @@ const ACTIONS = {
       requester: actorOf() ?? ctx.scope.requester,
       window_seconds: Math.max(1, Math.min(60, Number(ctx.entry.params.request_batch_seconds) || 10)),
     } : null;
+    const observation = ctx.scope.event?.ci;
+    if (batch && observation?.required && !observation.ready) text = `${String(text ?? '')}\nSource evidence could not be verified: ${observation.reason ?? 'unavailable'}. The decision request is retained.`;
     record(ctx.db, ctx.id, 'board_message', { to: String(to), text: batch ? String(text ?? '') : `${String(text ?? '')}\n\nAnswer with reply_to ${id}.`, message_id: id, ...(batch ? { batch } : {}) }, null);
     ctx.effects.push({ kind: 'board_message', id: ctx.id });
   },
@@ -1041,13 +1028,19 @@ function settleRelations(db, board, entry, id, effects) {
 }
 
 
-export function projectStatus(db, board, entry, id) {
-  if (!entry.workflow.stored_as?.length) return;
+/** A card's workflow status and the status Hermes's `tasks.status` stores it as, read without writing. */
+export function storedStatus(db, board, entry, id) {
   const task = cardOf(db, id);
   const status = statusOf(db, task);
+  if (!entry.workflow.stored_as?.length) return { status, stored: task.status };
   const scope = scopeOf(db, board, task, { params: entry.params });
   const rule = entry.workflow.stored_as.find((r) => holds(r.guard, scope));
-  const stored = rule?.status ?? storedAs(entry.workflow, status);
+  return { status, stored: rule?.status ?? storedAs(entry.workflow, status) };
+}
+
+export function projectStatus(db, board, entry, id) {
+  if (!entry.workflow.stored_as?.length) return;
+  const { status, stored } = storedStatus(db, board, entry, id);
   run(db, 'UPDATE tasks SET status = ? WHERE id = ?', stored, id);
   run(db, 'INSERT INTO supercode_cards (task_id, stage) VALUES (?, ?) ON CONFLICT(task_id) DO UPDATE SET stage = excluded.stage', id, status);
 }

package/board/workspace.mjs

@@ -1,5 +1,7 @@
 // Filesystem/RPC work happens before a board transaction; the ownership check is pure.
 import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { basename, dirname } from 'node:path';
 import { Workspaces, inspectCheckout, repositoryId, teamsHome } from '@volter/supercode-teams/workspaces';
 import { localMachine, normalMachine, supercodeBin, commandEnv } from './dispatch.mjs';
 export const isWorkspacePath = value => /^(\/|~|[A-Za-z]:[\\/])/.test(value ?? '');
@@ -28,6 +30,17 @@ export function declareWorkspace(kind, value, machine, branch = null) {
   const row = workspaceDoor(machine, 'register', value);
   return { repository: row.repository, branch: branch ?? (kind === 'dir' ? row.branch : null), path: kind === 'dir' ? row.path : null };
 }
+/** The checkouts this machine keeps of any repository on `branch`: where an arc changing several repositories
+ *  keeps its work in each of them (its own worktree aside). Another machine's map is not read from here. */
+export function branchCheckouts(machine, branch) {
+  if (!branch || (machine && normalMachine(machine) !== localMachine())) return [];
+  return new Workspaces(teamsHome()).list().filter((row) => (branch === '*' || row.branch === branch) && existsSync(row.path));
+}
+/** The registered checkout of `repository` on `branch` on `machine`: where a card changing several repositories
+ *  keeps its work in each of them. */
+export function checkoutOf(machine, repository, branch) {
+  return workspaceDoor(machine, 'resolve', repositoryId(repository), { branch });
+}
 export function resolveWorkspace(task, create = false) {
   const declared = task.workspace_anchor ?? task.workspace_path;
   if (isWorkspacePath(declared)) {
@@ -36,6 +49,19 @@ export function resolveWorkspace(task, create = false) {
     if (info.linked) throw new Error('worktree declaration is already a linked worktree; name its repository instead');
     throw new Error('legacy worktree path needs registration and a repository declaration before launch');
   }
+  // A primary checkout can change when another clone is registered. That does
+  // not move an already allocated card worktree. Machine moves and workspace
+  // retargets clear this runtime receipt; never borrow an arbitrary checkout.
+  if (task.workspace_kind === 'worktree' && task.workspace_path &&
+      basename(task.workspace_path) === task.id && basename(dirname(task.workspace_path)) === '.worktrees' &&
+      (!isLocalWorkspace(task) || existsSync(task.workspace_path))) {
+    const cached = workspaceDoor(task.machine, 'inspect', task.workspace_path);
+    if (cached.linked && basename(cached.path) === task.id && basename(dirname(cached.path)) === '.worktrees' &&
+        cached.repository === repositoryId(declared) && cached.branch === (task.branch_name ?? `wt/${task.id}`)) {
+      return { ...cached, root: dirname(dirname(cached.path)) };
+    }
+    throw new Error(`card worktree ${task.workspace_path} does not match ${declared}, branch ${task.branch_name ?? `wt/${task.id}`}; retarget its workspace explicitly`);
+  }
   return workspaceDoor(task.machine, 'resolve', declared, { branch: task.branch_name, solo: task.workspace_kind === 'worktree', card: task.id, create });
 }
 export function checkWorkspace(board, task) {