@volter/supercode-orchestrator 0.5.207 → 0.5.209

package/board/tools.mjs

@@ -43,7 +43,9 @@ export async function boardTool(root, name, args = {}, env = {}) {
   const slug = args.board || env.HERMES_KANBAN_BOARD || DEFAULT_BOARD;
   // the board's workflow decides what each tool's event does; the worker is its run's role on its own task, and
   // nobody on another (Hermes's worker scoping)
-  try { await loadWorkflow(root); } catch (e) { return error(e.message); }
+  let entry;
+  try { entry = await loadWorkflow(root); } catch (e) { return error(e.message); }
+  const stateOptions = { nativeHolds: Boolean(entry.workflow.flags?.paused) };
   engine.setCaller((db, cardId) => {
     if (!own || !runId) return own ? [] : ['manager'];
     const meta = json(db.prepare('SELECT metadata FROM task_runs WHERE id = ?').get(runId)?.metadata, {})?.supercode ?? {};
@@ -78,13 +80,13 @@ export async function boardTool(root, name, args = {}, env = {}) {
     if (name !== 'kanban_show' && name !== 'kanban_list' && !(name === 'kanban_comment' && isLatestReviewer(board.db, tid, actorOf()))) { const stale = ownRun(); if (stale) return error(stale); }
     switch (name) {
       case 'kanban_show': {
-        const card = tx(board, (db) => { const c = engine.showCard(db, tid); c.context = engine.cardContext(db, tid); return c; });
+        const card = tx(board, (db) => { const c = engine.showCard(db, tid, stateOptions); c.context = engine.cardContext(db, tid, stateOptions); return c; });
         const t = card.task;
         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,
+          task: { id: t.id, readable_id: t.readable_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 },
-          parents: card.parents.map((p) => p.id), children: card.children,
+          parents: card.parents.map((p) => p.id), children: card.children, subtasks: card.subtasks,
           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,
         });
@@ -92,7 +94,7 @@ export async function boardTool(root, name, args = {}, env = {}) {
       case 'kanban_list': {
         const limit = args.limit === undefined ? 100 : Number(args.limit);
         if (!Number.isInteger(limit) || limit < 1) return error('limit must be an integer >= 1');
-        const cards = tx(board, (db) => engine.listCards(db, { status: args.status ?? null, assignee: args.assignee ?? null, includeArchived: Boolean(args.include_archived) }))
+        const cards = tx(board, (db) => engine.listCards(db, { ...stateOptions, status: args.status ?? null, assignee: args.assignee ?? null, includeArchived: Boolean(args.include_archived), includeSubtasks: Boolean(args.include_subtasks) }))
           .filter((t) => !args.tenant || t.tenant === args.tenant).slice(0, limit);
         return ok({ tasks: cards.map((t) => ({ id: t.id, title: t.title, assignee: t.assignee, status: t.status, priority: t.priority, tenant: t.tenant, machine: t.machine })), count: cards.length });
       }
@@ -120,7 +122,7 @@ export async function boardTool(root, name, args = {}, env = {}) {
       }
       case 'kanban_block': {
         const stale = ownRun(); if (stale) return error(stale);
-        const { to: status } = await engine.block(board, tid, { reason: args.reason ? redact(String(args.reason)) : null, on: args.on ?? null, waitingOn: args.waiting_on ?? null });
+        const { to: status } = await engine.block(board, tid, { kind: args.kind ?? 'needs_input', reason: args.reason ? redact(String(args.reason)) : null, on: args.on ?? null, waitingOn: args.waiting_on ?? null });
         return ok({ task_id: tid, status });
       }
       case 'kanban_request_state': {
@@ -135,7 +137,7 @@ export async function boardTool(root, name, args = {}, env = {}) {
       }
       case 'kanban_request_changes': {
         const stale = ownRun(); if (stale) return error(stale);
-        // each finding is filed as a task on the arc first, so the arc stays open until a pushed head fixes it
+        // each finding is filed as a task on the arc first: the arc's review is due again once every one is closed (ci.mjs answeredChanges)
         const findings = [].concat(args.findings ?? []).map((f) => redact(String(f)).trim()).filter(Boolean);
         const filed = findings.map((finding) => engine.createCard(board, { title: finding, subtaskOf: tid }).id);
         await engine.requestChanges(board, tid, { reason: args.reason ? redact(String(args.reason)) : null, reviewer: author });
@@ -183,7 +185,7 @@ export async function boardTool(root, name, args = {}, env = {}) {
       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, reviewer: args.reviewer ?? null, parents: [args.parents ?? []].flat(), tenant: args.tenant ?? null,
+          title: args.title, readableId: args.readable_id, 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/visibility.mjs

@@ -0,0 +1,11 @@
+// Shared by the bounded CLI reader and the engine's record listing. t and c are
+// the task and its supercode state; the two parameters opt into subtasks/history.
+export const CARD_VISIBILITY_SQL = `(? OR c.subtask_of IS NULL) AND (? OR (
+  t.status NOT IN ('cancelled', 'archived') AND COALESCE(c.stage, '') NOT IN ('cancelled', 'archived')
+  AND COALESCE(c.archived, 0) = 0
+  AND NOT EXISTS (
+    SELECT 1 FROM tasks arc LEFT JOIN supercode_cards state ON state.task_id = arc.id
+    WHERE arc.id = c.subtask_of AND (arc.status IN ('cancelled', 'archived')
+      OR state.stage IN ('cancelled', 'archived') OR state.archived = 1)
+  )
+))`;

package/board/workflow.mjs

@@ -1,3 +1,4 @@
+import { allocateReadableId } from './readable-id.mjs';
 // The board's workflow, interpreted (docs/architecture/orchestrator.md §2.9). The IR's `Orchestration.workflow`
 // (crates/interchange/src/orchestration/workflow.rs; Hermes's dispatcher, hermes.workflow.yaml, when a home declares
 // none) says every status a card can be in, what runs there, which events move a card and who may send them, what
@@ -13,7 +14,7 @@ import { promisify } from 'node:util';
 import { existsSync, readdirSync, realpathSync, watch, readFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { randomBytes } from 'node:crypto';
-import { actorOf, appendRunObservation, event as record, json, now } from './store.mjs';
+import { actorOf, appendRunObservation, boardKey, cardHandleOf, event as record, json, now } from './store.mjs';
 import { releaseAllSideSessions } from './side-sessions.mjs';
 import { evaluate, holds, render, needsSources } from './expr.mjs';
 import { completionEvidence, declaredWorkBranches, namedWorkBranch, reviewCandidate } from './ci.mjs';
@@ -150,9 +151,9 @@ export function workflowEntry(orchestration) {
 }
 
 /** The workflow loaded for `root` (loadWorkflow first): the running call's basis, else the latest read. */
-export function workflowFor(root) {
+export function workflowFor(root, { optional = false } = {}) {
   const entry = current().workflows.get(root) ?? loaded.get(root);
-  if (!entry) throw new Error(`the board workflow of ${root} is not loaded`);
+  if (!entry && !optional) throw new Error(`the board workflow of ${root} is not loaded`);
   return entry;
 }
 
@@ -235,7 +236,8 @@ function pattern(p) {
 // ran: volter-org t_9a9c2a9c). A folder that is not there, a git that did not answer, a machine that could not be asked:
 // unknown, with why, and never "no commits".
 const commitTimes = new Map(); // `${path}:${id}` → { at, known, value, error }
-async function readCardCommit(path, id, branches) {
+// A commit names the card by its id or by its keyed number (`VO-856`); a branch is the card's by its handle too.
+async function readCardCommit(path, id, branches, handle = null) {
   if (!existsSync(path)) return { known: false, value: null, error: `no folder ${path} on this machine` };
   // awaited, never a wait that holds the event loop: `status` 0 or the exit code, as a synchronous run answered
   const git = (repo, args) => execFileAsync('git', ['-C', repo, ...args], { encoding: 'utf8', timeout: 10_000 }).then(({ stdout }) => ({ status: 0, stdout }), (error) => ({ status: error.code ?? 1, stdout: error.stdout ?? '', timedOut: Boolean(error.killed) }));
@@ -251,7 +253,13 @@ async function readCardCommit(path, id, branches) {
     if (!refs.length) return { repo: true, known: true, value: null };
     const r = await git(repo, ['log', ...refs, '--no-merges', '-1', '--format=%ct', '--fixed-strings', `--grep=${id}`, '--']);
     if (r.status !== 0) return { repo: true, known: false, value: null, error: `git log ${r.timedOut ? 'did not answer within 10s' : 'failed'} in ${repo}` };
-    const value = Number(r.stdout?.trim());
+    let value = Number(r.stdout?.trim());
+    const recorded = refs.filter(ref => branches.includes(short(ref)) && !['main', 'master', fallback].includes(short(ref)));
+    if (handle && recorded.length) {
+      const keyed = await git(repo, ['log', ...recorded, '--no-merges', '-1', '--format=%ct', '--fixed-strings', `--grep=${handle.toUpperCase()}`, '--']);
+      if (keyed.status !== 0) return { repo: true, known: false, value: null, error: `git log failed in ${repo}` };
+      value = Math.max(value || 0, Number(keyed.stdout?.trim()) || 0);
+    }
     return { repo: true, known: true, value: Number.isFinite(value) && value > 0 ? value : null };
   };
   const own = await readCommit(path);
@@ -271,15 +279,15 @@ async function readCardCommit(path, id, branches) {
   // a commit that was read stands; with none read, a child that could not be read leaves the whole reading unknown
   return value == null && unread ? { known: false, value: null, error: unread } : { known: true, value };
 }
-async function observeLastCommit(path, id, branches = [], machine = null) {
+async function observeLastCommit(path, id, branches = [], machine = null, handle = null) {
   if (!path) return null;
   const key = `${path}:${id}`;
   const cached = commitTimes.get(key);
   if (cached && now() - cached.at < 15) return cached.value;
   let reading;
   try {
-    if (isLocalWorkspace({ machine })) reading = await readCardCommit(path, id, branches);
-    else reading = { known: true, value: (await cardCommitsOn(machine, path, id, branches)).at };
+    if (isLocalWorkspace({ machine })) reading = await readCardCommit(path, id, branches, handle);
+    else reading = { known: true, value: (await cardCommitsOn(machine, path, id, branches, handle?.toUpperCase() ?? null)).at };
   } catch (error) { reading = { known: false, value: null, error: String(error?.message ?? error).slice(0, 300) }; }
   commitTimes.set(key, { at: now(), ...reading });
   return reading.value;
@@ -313,7 +321,7 @@ export async function refreshCardInputs(board, id, { commits = false } = {}) {
   if (commits && !task.subtask_of) {
     const { path, machine } = commitSource(board.db, task);
     if(path)commitTimes.delete(`${path}:${id}`);
-    await observeLastCommit(path,id,declaredWorkBranches(board.db,id),machine);
+    await observeLastCommit(path,id,declaredWorkBranches(board.db,id),machine,cardHandleOf(board,id));
   }
 }
 
@@ -333,6 +341,12 @@ export async function refreshRelationAnswers(board) {
   for (const row of board.db.prepare("SELECT e.payload FROM task_events e JOIN (SELECT task_id, MAX(id) id FROM task_events WHERE kind IN ('blocked','unblocked') GROUP BY task_id) last ON e.id=last.id JOIN tasks t ON t.id=e.task_id WHERE e.kind='blocked' AND t.status='blocked'").all()) {
     const id = json(row.payload, {})?.waiting_on; if (id) ids.add(id);
   }
+  // State requests stay live while the card runs, independently of a blocker.
+  // Read their exact question ids through the same mailbox receipt door.
+  for (const row of board.db.prepare("SELECT id FROM tasks WHERE current_run_id IS NOT NULL AND status NOT IN ('done','cancelled','archived')").all()) {
+    const request = stateRequestOf(board.db, row.id);
+    if (request?.message_id) ids.add(request.message_id);
+  }
   const list = [...ids];
   if (!list.length) return;
   // one read of this machine's daemon for every id (its header index answers, no process per message)
@@ -341,7 +355,9 @@ export async function refreshRelationAnswers(board) {
     if (!Array.isArray(rows)) throw new Error('the mail door returned no message list');
     for (const id of list) {
       const row = rows.find((item) => item?.id === id);
-      mailboxAnswers.set(id, { answer: row?.replies?.[0]?.id ?? null, askedOf: row?.session ?? null });
+      mailboxAnswers.set(id, row?.found === true
+        ? { answer: row.replies?.[0]?.id ?? null, askedOf: row.session ?? null }
+        : { error: `the mailbox did not find question ${id}; its answer is unknown` });
     }
   } catch (error) { for (const id of list) mailboxAnswers.set(id, { error: `the answer to ${id} could not be read: ${String(error.message).slice(0, 200)}` }); }
 }
@@ -351,6 +367,18 @@ function answerTo(id) {
   return observed?.answer ?? null;
 }
 
+// A manager's state act settles the request; a mailbox reply answers it without
+// changing the card. Unknown mailbox reads never assert an unanswered question.
+function stateRequestOf(db, id) {
+  const row = one(db, "SELECT id,payload,created_at FROM task_events WHERE task_id=? AND kind='state_requested' ORDER BY id DESC LIMIT 1", id);
+  if (!row || one(db, "SELECT 1 FROM task_events WHERE task_id=? AND id>? AND kind IN ('paused','resumed','blocked','unblocked','completed','cancelled','review_pass','reopened') LIMIT 1", id, row.id)) return null;
+  const payload = json(row.payload, {}) ?? {};
+  const question = payload.message_id ?? json(one(db, "SELECT payload FROM task_events WHERE task_id=? AND id<? AND kind='board_message' AND json_extract(payload,'$.batch') IS NOT NULL ORDER BY id DESC LIMIT 1", id, row.id)?.payload, {})?.message_id;
+  const receipt = question ? mailboxAnswers.get(question) : null;
+  return { id: row.id, created_at: row.created_at, state: payload.state, reason: payload.reason, message_id: question ?? null,
+    answer_known: Boolean(receipt && !receipt.error), answer: receipt?.answer ?? null, error: receipt?.error ?? null };
+}
+
 const OPEN_OUTCOME = /^(\s*[-*] )\[ \] (.+)$/;
 const TICKED_OUTCOME = /^\s*[-*] \[[xX]\] .+$/;
 /** Whether `body` is `was` with only outcomes ticked: each changed line is under the Acceptance heading, was `- [ ] X`
@@ -484,6 +512,7 @@ export function scopeOf(db, board, task, { params, event = {}, extra = {}, lazy
       task.id, Number(one(db, 'SELECT since FROM supercode_cards WHERE task_id = ?', task.id)?.since ?? 0))?.payload, {})?.reason ?? null; },
     // the message whose answer the standing block waits for (`block --waiting-on`), and that answer's id once it has landed
     get waiting_on() { return waitingOn(); },
+    get state_request() { return stateRequestOf(db, task.id); },
     answer: () => answerTo(waitingOn()),
     // the seconds its runs spent, by the role each run was for (implementer: coding, reviewer: reviewing, …), an open
     // run counted to now; `waiting` is the rest of its life since it was filed
@@ -593,7 +622,7 @@ function queueTransitionNotice(db, board, entry, task, from, name, payload, befo
   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 = numbered(cardNumber(db, task.id), render(entry.workflow.notify?.worker?.run_changed ?? defaultNotice, scope));
+  const body = numbered(boardKey(board.root, board.slug), cardNumber(db, task.id), 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: 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')}` };
@@ -889,7 +918,7 @@ const FORMAT = {
   model_override_set: ({ e }) => ({ model: (e.field === 'model' ? e.value : e.model) || null, provider: e.provider || null }),
   goal_set: ({ after }) => ({ goal_mode: Boolean(after.goal_mode), goal_max_turns: after.goal_mode ? after.goal_max_turns ?? null : null }),
   heartbeat: ({ e }) => (e.note || e.until ? { ...(e.note ? { note: e.note } : {}), ...(e.until ? { until: Number(e.until) } : {}) } : null),
-  commented: ({ e }) => ({ author: String(e.author ?? 'user').trim(), len: String(e.body ?? '').length, ...(e.sources ? { sources: e.sources } : {}) }),
+  commented: ({ e }) => ({ author: String(e.author ?? 'user').trim(), len: String(e.body ?? '').length, ...(e.sources ? { sources: e.sources } : {}), ...(e.branches ? { branches: e.branches } : {}) }),
   archived: () => null,
   status: ({ e, before, to }) => ({ status: to, reason: e.reason ?? 'reopened', previous_status: before.stored_as }),
   machine_set: ({ e, before }) => ({ machine: e.field === 'machine' ? e.value ?? null : e.machine ?? null, was: before.machine }),
@@ -1107,6 +1136,11 @@ const ACTIONS = {
       cardField(ctx, 'workspace_root', null);
       if (moves) cardField(ctx, 'machine', ws.machine ?? null);
     }
+    if (said?.readable_id != null) {
+      const task = cardOf(ctx.db, ctx.id);
+      const readable = allocateReadableId(ctx.db, task.title, said.readable_id, ctx.id);
+      run(ctx.db, 'UPDATE tasks SET readable_id=? WHERE id=?', readable, ctx.id);
+    }
     if (said?.title && String(said.title).trim()) run(ctx.db, 'UPDATE tasks SET title = ? WHERE id = ?', String(said.title).trim(), ctx.id);
     if (said?.body !== undefined && said?.body !== null) run(ctx.db, 'UPDATE tasks SET body = ? WHERE id = ?', said.body, ctx.id);
   },
@@ -1188,7 +1222,7 @@ const ACTIONS = {
   send_to_actor(ctx, text) {
     const effect = { kind: 'send_to_actor', id: ctx.id, runId: ctx.runId, text, messageKey: `board-actor-${randomBytes(16).toString('hex')}` };
     const inserted = run(ctx.db, 'INSERT INTO supercode_effects (effect) VALUES (?)', JSON.stringify(effect));
-    effect.text = identifyNotice({ id: `notice-${inserted.lastInsertRowid}`, kind: 'actor_notice', run_id: ctx.runId, created_at: now() }, numbered(cardNumber(ctx.db, ctx.id), text));
+    effect.text = identifyNotice({ id: `notice-${inserted.lastInsertRowid}`, kind: 'actor_notice', run_id: ctx.runId, created_at: now() }, numbered(boardKey(ctx.board.root, ctx.board.slug), cardNumber(ctx.db, ctx.id), text));
     run(ctx.db, 'UPDATE supercode_effects SET effect=? WHERE id=?', JSON.stringify(effect), Number(inserted.lastInsertRowid));
     ctx.effects.push({ ...effect, durableId: Number(inserted.lastInsertRowid) });
   },
@@ -1371,14 +1405,22 @@ function settleRelations(db, board, entry, id, effects) {
 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 };
+  // Native holds are stored honestly. Hermes lowering is an export concern;
+  // older homes may still declare a lossy paused -> blocked storage rule.
+  const nativeHolds = Boolean(entry.workflow.flags?.paused);
+  if (nativeHolds && !task.archived) {
+    if (task.paused) return { status, stored: 'paused' };
+    if (task.blocked_by.length) return { status, stored: 'blocked' };
+  }
+  if (!entry.workflow.stored_as?.length) return { status, stored: nativeHolds ? storedAs(entry.workflow, status) : task.status };
   const scope = scopeOf(db, board, task, { params: entry.params, lazy: true });
   const rule = entry.workflow.stored_as.find((r) => holds(r.guard, scope));
-  return { status, stored: rule?.status ?? storedAs(entry.workflow, status) };
+  const stored = rule?.status ?? storedAs(entry.workflow, status);
+  return { status, stored: nativeHolds && ['blocked', 'paused'].includes(stored) ? storedAs(entry.workflow, status) : stored };
 }
 
 export function projectStatus(db, board, entry, id) {
-  if (!entry.workflow.stored_as?.length) return;
+  if (!entry.workflow.stored_as?.length && !entry.workflow.flags?.paused) return;
   const { status, stored } = storedStatus(db, board, entry, id);
   // Only a change is written: an unchanged write still commits, and a commit wakes the dispatcher that called this.
   run(db, 'UPDATE tasks SET status = ? WHERE id = ? AND status IS NOT ?', stored, id, stored);

package/board/workspace.mjs

@@ -4,6 +4,7 @@ import { basename, dirname } from 'node:path';
 import { runtimeDoor } from './runtime-door.mjs';
 import { inspectCheckout } from '@volter/teams/checkout';
 import { localMachine, normalMachine, commandEnv } from './dispatch.mjs';
+import { cardHandleOf } from './store.mjs';
 
 // Repository identities are portable input values; the daemon owns their checkout resolution.
 function repositoryId(value) {
@@ -19,7 +20,7 @@ export const isWorkspacePath = value => /^(\/|~|[A-Za-z]:[\\/])/.test(value ?? '
 let presence = null;
 export const notePresence = (reading) => { presence = reading; };
 async function workspaceDoor(machine, verb, value, options = {}) {
-  if (machine && presence?.known === true && normalMachine(machine) !== localMachine() && !presence.online.has(normalMachine(machine))) {
+  if (machine && presence?.known === true && normalMachine(machine) !== localMachine() && presence.offline?.has(normalMachine(machine))) {
     throw new Error(`workspace on ${machine}: machine ${normalMachine(machine)} is offline`);
   }
   const local = !machine || normalMachine(machine) === localMachine();
@@ -42,12 +43,12 @@ const commitDoorHeld = new Map(); // machine → { until (ms), why }
  * seconds here): `{ at }`, seconds or null for none. Throws when it could not be read (the machine offline or silent,
  * its daemon without the door, no such folder there): an unread checkout is unknown, never a card with no commits.
  */
-export async function cardCommitsOn(machine, path, card, branches = []) {
+export async function cardCommitsOn(machine, path, card, branches = [], ref = null) {
   const name = normalMachine(machine);
-  if (presence?.known === true && !presence.online.has(name)) throw new Error(`machine ${name} is offline`);
+  if (presence?.known === true && presence.offline?.has(name)) throw new Error(`machine ${name} is offline`);
   const held = commitDoorHeld.get(name);
   if (held && Date.now() < held.until) throw new Error(held.why);
-  const r = await runtimeDoor(machine, 'harness.v1.workspaces.commits', { path, card, branches }, { timeout: 10_000 });
+  const r = await runtimeDoor(machine, 'harness.v1.workspaces.commits', { path, card, branches, ...(ref ? { ref } : {}) }, { timeout: 10_000 });
   if (r.code !== 0) {
     let refusal = null; try { refusal = JSON.parse(String(r.stderr).trim().split('\n').pop()); } catch { /* said in its own words */ }
     const missing = refusal?.code === -32601 || /unknown method/.test(refusal?.message ?? '');
@@ -92,6 +93,15 @@ export async function branchCheckouts(machine, branch) {
 export async function checkoutOf(machine, repository, branch) {
   return workspaceDoor(machine, 'resolve', repositoryId(repository), { branch });
 }
+// A card's solo worktree folder under the repository's `.worktrees`: the one it was made in, while its path is recorded
+// (a card running keeps its folder), else its handle (`vo-856`, store.mjs cardHandle; `task.handle`), as the board names
+// a card's worktree, else its id. Its branch is its own, else `wt/<id>`, as the folder named for its id had.
+const worktreeFolder = (task) => {
+  if (task.workspace_path && basename(dirname(task.workspace_path)) === '.worktrees') return basename(task.workspace_path);
+  const branch = task.branch_name?.split('/').at(-1);
+  return task.handle && (branch === task.handle || branch?.startsWith(`${task.handle}-`)) ? task.handle : task.id;
+};
+const worktreeBranch = (task) => task.branch_name ?? `wt/${task.id}`;
 export async function resolveWorkspace(task, create = false) {
   const declared = task.workspace_anchor ?? task.workspace_path;
   if (isWorkspacePath(declared)) {
@@ -104,19 +114,21 @@ export async function resolveWorkspace(task, create = false) {
   // 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' &&
+      basename(dirname(task.workspace_path)) === '.worktrees' &&
       (!isLocalWorkspace(task) || existsSync(task.workspace_path))) {
     const cached = await 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}`)) {
+    if (cached.linked && basename(cached.path) === worktreeFolder(task) && basename(dirname(cached.path)) === '.worktrees' &&
+        cached.repository === repositoryId(declared) && cached.branch === worktreeBranch(task)) {
       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`);
+    throw new Error(`card worktree ${task.workspace_path} does not match ${declared}, branch ${worktreeBranch(task)}; retarget its workspace explicitly`);
   }
-  return workspaceDoor(task.machine, 'resolve', declared, { branch: task.branch_name, solo: task.workspace_kind === 'worktree', card: task.id, create });
+  const solo = task.workspace_kind === 'worktree';
+  return workspaceDoor(task.machine, 'resolve', declared, { branch: solo ? worktreeBranch(task) : task.branch_name, solo, card: solo ? worktreeFolder(task) : task.id, create });
 }
 export async function checkWorkspace(board, task) {
   if (task.workspace_kind === 'scratch') return null;
+  task = { ...task, handle: task.handle ?? cardHandleOf(board, task.id) };
   const facts = await resolveWorkspace(task), peers = [];
   if (task.workspace_kind === 'dir' && !facts.linked) {
     for (const row of board.db.prepare(`SELECT t.id,t.workspace_path,t.branch_name,c.workspace_anchor,c.machine FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id WHERE t.current_run_id IS NOT NULL AND t.workspace_kind='dir'`).all()) {