@volter/supercode-orchestrator 0.5.207 → 0.5.208

package/board/engine.mjs

@@ -1,3 +1,4 @@
+import { allocateReadableId } from './readable-id.mjs';
 // The board's transitions (docs/architecture/orchestrator.md §2.9): what a card may do, written for supercode and
 // kept to Hermes Kanban's lifecycle so the two read each other's boards. Statuses: triage · todo · scheduled ·
 // ready · running · blocked · review · done · archived. A card with a parent that is not done waits in `todo`
@@ -10,18 +11,20 @@
 import { current } from './call.mjs';
 import { detachedCard, detachedSession, personCustody, sessionAddress, sessionOperation } from './custody.mjs';
 import { executionOf } from './session-work.mjs';
+import { cardState, cardStateSql, holdDescription } from './card-state.mjs';
 import { spawn, execFile } from 'node:child_process';
 import { existsSync, rmSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { checkWorkspace, assertWorkspaceOwner, declareWorkspace, isLocalWorkspace, plainWorkspace } from './workspace.mjs';
 import { DatabaseSync } from 'node:sqlite';
-import { view, actorOf, principalOf, CARD_NUMBERS, claimer, contention, event, json, newTaskId, now, retryContention, tx } from './store.mjs';
+import { CARD_VISIBILITY_SQL } from './visibility.mjs';
+import { view, actorOf, principalOf, boardKey, cardBranch, cardHandle, CARD_NUMBERS, claimer, contention, event, json, newTaskId, now, retryContention, tx } from './store.mjs';
 import { assertSourceReceipt, completionPhase, inspectCompletionEvidence, observeCompletionEvidence, withCompletionEvidence } from './ci.mjs';
 import { addDependency, retireSupersededRuns, refreshCardInputs, requestSessionClose, reviewerOf, eventTo, fire, validateEvent, loadWorkflow, setStatus, settle, startNew, statusOf, runEvent, workflowFor } from './workflow.mjs';
 import { refuseCredentialDump, withheldIfDump } from './credential-guard.mjs';
 import { AGENT_KIND_LIST, compactCardAgentEvents } from './published.mjs';
 
-export const STATUSES = ['triage', 'todo', 'scheduled', 'ready', 'running', 'blocked', 'review', 'done', 'archived'];
+export const STATUSES = ['triage', 'todo', 'scheduled', 'ready', 'running', 'blocked', 'paused', 'review', 'done', 'archived'];
 export const WORKSPACE_KINDS = ['scratch', 'dir', 'worktree'];
 /** A card blocked this many times in a row for the same kind goes to triage for a person (Hermes's limit). */
 export const BLOCK_RECURRENCE_LIMIT = 2;
@@ -38,23 +41,24 @@ const one = (db, sql, ...args) => db.prepare(sql).get(...args);
 const all = (db, sql, ...args) => db.prepare(sql).all(...args);
 const run = (db, sql, ...args) => db.prepare(sql).run(...args);
 
-// A card's number (#42): what the store gave it when it was made (store.mjs layOutNumbers). A person names a card by
-// it wherever its id is taken (`42` or `#42`), and every view of a card shows it first, before the id.
+// A card's number: what the store gave it when it was made (store.mjs layOutNumbers), read with its board's key
+// (`VO-42`, store.mjs boardKey). A person names a card by it wherever its id is taken (`VO-42`, `vo-42`, `#42`, `42`),
+// and every view of a card shows it first, before the id.
 /** Card `n`'s id on this board, or null when no card here has that number. */
 export const cardByNumber = (db, n) => one(db, `SELECT t.id FROM ${CARD_NUMBERS} n JOIN tasks t ON t.id = n.task_id WHERE n.number = ?`, Number(n))?.id ?? null;
 /** The number of card `id`, or null. */
 export const numberOf = (db, id) => one(db, `SELECT number FROM ${CARD_NUMBERS} WHERE task_id = ?`, id)?.number ?? null;
 /** The numbers of cards `ids`: id → number. */
 export const numbersOf = (db, ids) => new Map(ids.length ? all(db, `SELECT task_id, number FROM ${CARD_NUMBERS} WHERE task_id IN (SELECT value FROM json_each(?))`, JSON.stringify([...new Set(ids)])).map((r) => [r.task_id, r.number]) : []);
-/** A card as a person reads it: its number first, then its id (`#42 t_4406c88a`). */
-export const cardLabel = (number, id) => (number ? `#${number} ${id}` : String(id));
+/** A card as a person reads it: its keyed number first (store.mjs boardKey), then its id (`VO-42 t_4406c88a`). */
+export const cardLabel = (key, number, id, readableId = null) => `${number ? `${key}-${number} ${id}` : String(id)}${readableId ? ` (${readableId})` : ''}`;
 
 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, number: numberOf(db, id), workspace_anchor: ours?.workspace_anchor ?? null, blocked_by: json(ours?.blocked_by, []) ?? [], paused: json(ours?.paused, null), detached: json(ours?.detached, null), archived: Boolean(ours?.archived), every: ours?.every ?? null, skills: json(row.skills, []) ?? [], machine: ours?.machine ?? null, subtask_of: ours?.subtask_of ?? null,
-    tags: json(ours?.tags, null) ?? (row.tenant ? [row.tenant] : []), sponsor: ours?.sponsor ?? null, sponsor_evidence: json(ours?.sponsor_evidence, null), requested_by_unverified: json(ours?.requested_by_unverified, null) };
+  return { ...row, number: numberOf(db, id), stage: ours?.stage ?? row.status, workspace_anchor: ours?.workspace_anchor ?? null, blocked_by: json(ours?.blocked_by, []) ?? [], paused: json(ours?.paused, null), detached: json(ours?.detached, null), archived: Boolean(ours?.archived), every: ours?.every ?? null, skills: json(row.skills, []) ?? [], machine: ours?.machine ?? null, subtask_of: ours?.subtask_of ?? null,
+    tags: json(ours?.tags, null) ?? (row.tenant ? [row.tenant] : []), requested_by_unverified: json(ours?.requested_by_unverified, null) };
 }
 
 function must(db, id) {
@@ -243,8 +247,6 @@ export function createCard(board, spec) {
   if (spec.provider && !spec.model) throw new Error('a provider needs a model');
   // Several ordered tags (C4); Hermes's single `tenant` is the first of them, as its export lowers them.
   const tags = [...new Set([spec.tenant, ...(spec.tags ?? [])].filter((tag) => typeof tag === 'string' && tag.trim()).map((tag) => tag.trim()))];
-  // A sponsor is a person, never an agent or an automation (Teams refuses any principal that is not a person).
-  if (spec.sponsor && /^(agent_|svc_|service_)/.test(spec.sponsor)) throw new Error('a sponsor is a person; an agent or an automation cannot sponsor a card');
   return tx(board, (db) => {
     if (spec.idempotencyKey) {
       const got = one(db, "SELECT id FROM tasks WHERE idempotency_key = ? AND status != 'archived' ORDER BY created_at DESC LIMIT 1", spec.idempotencyKey);
@@ -272,14 +274,10 @@ export function createCard(board, spec) {
     }
     assertWorkspaceOwner(db, workspaceTask, checked);
     // The repository declaration stays separate from the resolved worktree path.
-    if (project) {
-      if (ws.kind === 'scratch') ws.kind = 'worktree';
-      if (ws.kind === 'worktree' && !spec.branch) {
-        const t = title.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/, '');
-        spec = { ...spec, branch: `${project.slug}/${id}${t ? `-${t}` : ''}` };
-      }
-    }
-    spec = { ...spec, project: project?.id ?? null, branch: spec.branch ?? (ws.kind === 'worktree' ? `wt/${id}` : null) };
+    if (project && ws.kind === 'scratch') ws.kind = 'worktree';
+    // A worktree card's branch is named for it once the store has numbered it (below), unless its creator named one.
+    const namedBranch = ws.kind === 'worktree' && !spec.branch ? (handle) => `${project ? `${project.slug}/` : ''}${cardBranch(handle, readableId)}` : null;
+    spec = { ...spec, project: project?.id ?? null };
     const t = now();
     run(db, `INSERT INTO tasks (id, title, body, assignee, status, priority, created_by, created_at, workspace_kind, workspace_path, branch_name,
                tenant, idempotency_key, max_runtime_seconds, skills, max_retries, model_override, provider_override, reasoning_effort, session_id,
@@ -289,16 +287,20 @@ export function createCard(board, spec) {
       spec.branch ?? null, tags[0] ?? null, spec.idempotencyKey ?? null, spec.maxRuntime ?? null,
       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 readableId = allocateReadableId(db, title, spec.readableId ?? null, id);
+    run(db, 'UPDATE tasks SET readable_id=? WHERE id=?', readableId, id);
+    const handle = cardHandle(boardKey(board.root, board.slug), numberOf(db, id));
+    if (namedBranch) run(db, 'UPDATE tasks SET branch_name = ? WHERE id = ?', handle ? namedBranch(handle) : `wt/${id}`, id);
     const machine = spec.machine ?? arc?.machine ?? null;
-    run(db, 'INSERT OR REPLACE INTO supercode_cards (task_id,machine,subtask_of,workspace_anchor,workspace_root,tags,sponsor,sponsor_evidence,requested_by_unverified) VALUES (?,?,?,?,?,?,?,?,?)', id, machine, arc?.id ?? null, declared.repository, checked?.mainRoot ?? null,
-      tags.length ? JSON.stringify(tags) : null, spec.sponsor ?? null, spec.sponsorEvidence ? JSON.stringify(spec.sponsorEvidence) : null, spec.requestedByUnverified ? JSON.stringify(spec.requestedByUnverified) : null);
+    run(db, 'INSERT OR REPLACE INTO supercode_cards (task_id,machine,subtask_of,workspace_anchor,workspace_root,tags,requested_by_unverified) VALUES (?,?,?,?,?,?,?)', id, machine, arc?.id ?? null, declared.repository, checked?.mainRoot ?? null,
+      tags.length ? JSON.stringify(tags) : null, spec.requestedByUnverified ? JSON.stringify(spec.requestedByUnverified) : 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,
       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(), created_by: one(db, 'SELECT created_by FROM tasks WHERE id=?', id)?.created_by ?? null, assignee: spec.assignee || null,
-      ...(spec.reviewer != null ? { reviewer: spec.reviewer } : {}), status, parents, tags, ...(spec.sponsor ? { sponsor: spec.sponsor } : {}), ...(spec.requestedByUnverified ? { requested_by_unverified: spec.requestedByUnverified } : {}), ...(machine ? { machine } : {}), ...(arc ? { subtask_of: arc.id } : {}) });
+      ...(spec.reviewer != null ? { reviewer: spec.reviewer } : {}), status, parents, tags, ...(spec.requestedByUnverified ? { requested_by_unverified: spec.requestedByUnverified } : {}), ...(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) {
@@ -693,8 +695,8 @@ export const complete = async (board, id, options = {}) => {
   return await act(board, id, 'complete', { roles, payload: { result, summary, metadata, run_id: runId, commit, branch, pr, pr_head, reviewed_sha } });
 };
 // a block names the one thing that ends it: a card it waits on (`on`), or the message whose answer it waits for (`waiting_on`)
-export const block = async (board, id, { reason = null, on = null, waitingOn = null, roles, runId = null } = {}) =>
-  await act(board, id, 'block', { roles, payload: { reason, on, waiting_on: waitingOn, run_id: runId } });
+export const block = async (board, id, { reason = null, on = null, waitingOn = null, kind = 'needs_input', roles, runId = null } = {}) =>
+  await act(board, id, 'block', { roles, payload: { reason, on, kind, waiting_on: waitingOn, run_id: runId } });
 export const unblock = (board, id, { reason = null, on = null, roles } = {}) => act(board, id, 'unblock', { roles, payload: { reason, on } });
 export const requestReview = async (board, id, options = {}) => {
   assertSourceReceipt(options);
@@ -708,7 +710,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, reason } = {}) => act(board, id, 'archive', { roles, payload: { reason } });
-export async function specify(board, id, { title = null, body = null, workspace = null, branch = null, machine = null, author = 'user', roles } = {}) {
+export async function specify(board, id, { title = null, body = null, readableId = null, workspace = null, branch = null, machine = null, author = 'user', roles } = {}) {
   refuseCredentialDump(`${id}'s specification`, { title, body });
   let declaration = null;
   if (workspace != null || branch != null || machine != null) {
@@ -722,12 +724,13 @@ export async function specify(board, id, { title = null, body = null, workspace
     if (branch != null && ws.kind === 'scratch') throw new Error('a scratch workspace has no repository branch');
     declaration = { kind: ws.kind, ...(await declareWorkspace(ws.kind, ws.path, target, branch)), ...(machine != null && target !== task.machine ? { machine: target } : {}) };
     if (declaration.repository === task.workspace_anchor) declaration.branch ??= task.branch_name;
-    if (declaration.kind === 'worktree') declaration.branch ??= `wt/${id}`;
+    const handle = cardHandle(boardKey(board.root, board.slug), task.number);
+    if (declaration.kind === 'worktree') declaration.branch ??= handle ? cardBranch(handle, task.readable_id) : `wt/${id}`;
     if (declaration.kind === 'dir') declaration.path = (await checkWorkspace(board, { ...task, machine: target, workspace_kind: declaration.kind, workspace_anchor: declaration.repository, workspace_path: declaration.path, branch_name: declaration.branch })).path;
   }
   // 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 } : {}) } });
+  const done = await act(board, id, 'specify', { roles, payload: { title, body: steps.body, readable_id: readableId, author, ...(declaration ? { workspace: declaration } : {}) } });
   for (const step of steps.tasks) createCard(board, { ...step, subtaskOf: id, assignee: getTask(board.db, id)?.assignee || null });
   return done;
 }
@@ -767,10 +770,26 @@ export async function unlink(board, parent, child, { roles } = {}) {
 }
 
 /** A comment on the card's thread; answers its id. */
-export async function comment(board, id, author, body, { roles, pr = null, pr_head = null } = {}) {
+export async function comment(board, id, author, body, { roles, pr = null, pr_head = null, source = null } = {}) {
   if (!String(body ?? '').trim()) throw new Error('a comment has a body');
   if (!String(author ?? '').trim()) throw new Error('a comment has an author');
-  let sources;
+  let sources, branches;
+  // The repositories and branches an arc changes are the arc's own: declared on it (`--source owner/repo:branch`, each
+  // repository the arc changes), never registered as a subtask's workspace to be reviewed (VO-2858 had to register
+  // volter-org and runhuman-2 on its tasks, VO-2860). The latest declaration is the arc's complete set.
+  if (source != null) {
+    const named = [].concat(source).map((item) => String(item).trim());
+    branches = named.map((item) => {
+      const found = /^(?:https:\/\/github\.com\/|github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?:([^\s:]+)$/.exec(item);
+      if (!found) throw new Error(`Declare each source as owner/repository:branch, not ${JSON.stringify(item)}.`);
+      return { repository: found[1], branch: found[2] };
+    });
+    if (!branches.length) throw new Error('Declare at least one source as owner/repository:branch.');
+    if (new Set(branches.map((b) => `${b.repository.toLowerCase()}:${b.branch}`)).size !== branches.length) throw new Error('Declare each source once.');
+    const arc = one(board.db, 'SELECT subtask_of FROM supercode_cards WHERE task_id = ?', id)?.subtask_of;
+    if (arc) throw new Error(`${id} is a task of ${arc}: an arc's sources are declared on the arc (comment ${arc} … --source owner/repository:branch).`);
+    if (!(roles ?? callerRoles(board.db, id)).some((role) => role === 'implementer' || role === 'manager')) throw new Error(`Only ${id}'s implementer or the manager declares its sources.`);
+  }
   if (pr != null || pr_head != null) {
     const urls = [].concat(pr ?? []), heads = [].concat(pr_head ?? []);
     if (!urls.length || urls.length !== heads.length) throw new Error('Record every PR with --pr URL --pr-head SHA, one full head per URL.');
@@ -782,7 +801,7 @@ export async function comment(board, id, author, body, { roles, pr = null, pr_he
     // Only the card's own implementer or the board's manager declares its sources; the author text is not identity.
     if (!(roles ?? callerRoles(board.db, id)).some((role) => role === 'implementer' || role === 'manager')) throw new Error(`Only ${id}'s implementer or the manager records its PR sources.`);
   }
-  const result = await act(board, id, 'comment', { roles, payload: { author: author.trim(), body, ...(sources ? { sources } : {}) } });
+  const result = await act(board, id, 'comment', { roles, payload: { author: author.trim(), body, ...(sources ? { sources } : {}), ...(branches ? { branches } : {}) } });
   return result.commentId;
 }
 
@@ -866,7 +885,7 @@ export function reconcileDependencySubscriptions(db) {
     const where = "WHERE task_id=? AND platform='supercode' AND chat_id=? AND thread_id=?";
     const identity = [row.task_id, row.chat_id, row.thread_id];
     if (!owner || owner.detached || owner.archived || ['done', 'cancelled', 'archived'].includes(owner.status)) run(db, `DELETE FROM kanban_notify_subs ${where}`, ...identity);
-    else if (address && (address !== row.chat_id || metadata.waiting_recipient)) run(db, `UPDATE kanban_notify_subs SET chat_id=?,delivery_metadata=? ${where}`, address, JSON.stringify({ ...metadata, waiting_recipient: false, failures: 0 }), ...identity);
+    else if (address && (address !== row.chat_id || metadata.waiting_recipient)) run(db, `UPDATE kanban_notify_subs SET chat_id=?,delivery_metadata=? ${where}`, address, JSON.stringify({ ...metadata, notice_wait: undefined, waiting_recipient: false, failures: 0 }), ...identity);
     else if (!address && !metadata.waiting_recipient) run(db, `UPDATE kanban_notify_subs SET delivery_metadata=? ${where}`, JSON.stringify({ ...metadata, waiting_recipient: true }), ...identity);
   }
 }
@@ -876,11 +895,13 @@ function inheritSubscriptions(db, child, parents, { workers = false } = {}) {
   const cursor = one(db, 'SELECT COALESCE(MAX(id), 0) AS c FROM task_events WHERE task_id = ?', child).c;
   for (const p of parents) {
     for (const s of all(db, 'SELECT * FROM kanban_notify_subs WHERE task_id = ?', p)) {
-      const role = json(s.delivery_metadata, {})?.role;
+      const metadata = json(s.delivery_metadata, {}) ?? {}, role = metadata.role;
       if ((role === 'worker' && !workers) || role === 'dependency') continue; // a parent's session does not work the child
+      // A child's subscription is a new wait, not the parent's retained delivery state.
+      delete metadata.notice_wait;
       run(db, `INSERT OR IGNORE INTO kanban_notify_subs (task_id, platform, chat_id, thread_id, user_id, user_id_alt, chat_type, notifier_profile, delivery_mode, delivery_metadata, created_at, last_event_id)
                VALUES (?, ?, ?, ?, ?, ?, COALESCE(?, 'dm'), ?, COALESCE(?, 'notify'), ?, ?, ?)`,
-        child, s.platform, s.chat_id, s.thread_id, s.user_id, s.user_id_alt, s.chat_type, s.notifier_profile, s.delivery_mode, s.delivery_metadata, now(), cursor);
+        child, s.platform, s.chat_id, s.thread_id, s.user_id, s.user_id_alt, s.chat_type, s.notifier_profile, s.delivery_mode, JSON.stringify(metadata), now(), cursor);
     }
   }
 }
@@ -890,20 +911,21 @@ export const subscriptions = (db, id = null) => (id ? all(db, 'SELECT * FROM kan
 
 // ------------------------------------------------------------------ reading
 
-export function listCards(db, { status = null, assignee = null, machine = null, includeArchived = false } = {}) {
-  const rows = all(db, `SELECT t.*, n.number, c.machine, c.subtask_of, c.stage, c.tags, c.sponsor FROM tasks t LEFT JOIN supercode_cards c ON c.task_id = t.id LEFT JOIN ${CARD_NUMBERS} n ON n.task_id = t.id
-    WHERE (? IS NULL OR t.status = ? OR c.stage = ?) AND (? IS NULL OR t.assignee = ?) AND (? IS NULL OR c.machine = ?) AND (? OR t.status != 'archived')
-    ORDER BY t.priority DESC, t.created_at ASC`, status, status, status, assignee, assignee, machine, machine, includeArchived ? 1 : 0);
-  return rows.map((r) => ({ ...r, skills: json(r.skills, []) ?? [], execution: executionOf(r.current_run_id ? one(db, 'SELECT metadata,ended_at FROM task_runs WHERE id=?', r.current_run_id) : null) }));
+export function listCards(db, { status = null, assignee = null, machine = null, includeArchived = false, includeSubtasks = true, nativeHolds = false } = {}) {
+  const stateSql = cardStateSql({ nativeHolds });
+  const rows = all(db, `SELECT t.*, n.number, c.machine, c.subtask_of, c.stage, c.tags, c.paused, c.blocked_by FROM tasks t LEFT JOIN supercode_cards c ON c.task_id = t.id LEFT JOIN ${CARD_NUMBERS} n ON n.task_id = t.id
+    WHERE (? IS NULL OR ${stateSql} = ? OR (? NOT IN ('paused','blocked') AND c.stage = ?)) AND (? IS NULL OR t.assignee = ?) AND (? IS NULL OR c.machine = ?) AND ${CARD_VISIBILITY_SQL}
+    ORDER BY t.priority DESC, t.created_at ASC`, status, status, status, status, assignee, assignee, machine, machine, includeSubtasks ? 1 : 0, includeArchived ? 1 : 0);
+  return rows.map((r) => cardState({ ...r, skills: json(r.skills, []) ?? [], execution: executionOf(r.current_run_id ? one(db, 'SELECT metadata,ended_at FROM task_runs WHERE id=?', r.current_run_id) : null) }, { nativeHolds }));
 }
 
-export function showCard(db, id) {
-  const task = { ...must(db, id), reviewer: reviewerOf(db, id) };
+export function showCard(db, id, options = {}) {
+  const task = cardState({ ...must(db, id), reviewer: reviewerOf(db, id) }, options);
   return {
     task,
     parents: parentsOf(db, id),
     children: childrenOf(db, id),
-    subtasks: all(db, `SELECT t.id, n.number, t.status, t.title FROM tasks t JOIN supercode_cards c ON c.task_id = t.id LEFT JOIN ${CARD_NUMBERS} n ON n.task_id = t.id WHERE c.subtask_of = ? ORDER BY t.created_at`, id),
+    subtasks: all(db, `SELECT t.id, n.number, t.status, t.title, c.stage, c.paused, c.blocked_by FROM tasks t JOIN supercode_cards c ON c.task_id = t.id LEFT JOIN ${CARD_NUMBERS} n ON n.task_id = t.id WHERE c.subtask_of = ? ORDER BY t.created_at`, id).map(row => cardState(row, options)),
     comments: all(db, 'SELECT author, body, created_at FROM task_comments WHERE task_id = ? ORDER BY id', id),
     runs: all(db, 'SELECT * FROM task_runs WHERE task_id = ? ORDER BY id', id).map((r) => ({ ...r, metadata: json(r.metadata, null) })),
     events: all(db, 'SELECT id, kind, payload, created_at, run_id FROM task_events WHERE task_id = ? ORDER BY id', id).map((e) => ({ ...e, payload: json(e.payload, null) })),
@@ -916,9 +938,10 @@ export function showCard(db, id) {
 const cap = (text, n) => { text = text ? withheldIfDump(text) : text; return text && text.length > n ? `${text.slice(0, n)}… (${text.length - n} more characters)` : text; };
 
 /** What a session starting on a card reads first: the card, its parents' results, earlier attempts and the thread. */
-export function cardContext(db, id) {
-  const task = must(db, id);
+export function cardContext(db, id, options = {}) {
+  const task = cardState(must(db, id), options);
   const out = [`# Card ${task.id}: ${task.title}`, ''];
+  out.push(`Readable id: ${task.readable_id}.`);
   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.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);
@@ -998,14 +1021,16 @@ export function removeAttachment(board, attachmentId) {
 }
 
 /** Per status, per assignee, and the oldest ready card's age (Hermes's `stats`). */
-export function stats(db) {
+export function stats(db, options = {}) {
+  const stateSql = cardStateSql(options);
+  const rows = `FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id`;
   const byStatus = {};
-  for (const r of all(db, "SELECT status, COUNT(*) AS n FROM tasks WHERE status != 'archived' GROUP BY status")) byStatus[r.status] = Number(r.n);
+  for (const r of all(db, `SELECT ${stateSql} AS board_status, COUNT(*) AS n ${rows} WHERE t.status != 'archived' GROUP BY board_status`)) byStatus[r.board_status] = Number(r.n);
   const byAssignee = {};
-  for (const r of all(db, "SELECT assignee, status, COUNT(*) AS n FROM tasks WHERE status != 'archived' AND assignee IS NOT NULL GROUP BY assignee, status")) (byAssignee[r.assignee] ??= {})[r.status] = Number(r.n);
+  for (const r of all(db, `SELECT t.assignee, ${stateSql} AS board_status, COUNT(*) AS n ${rows} WHERE t.status != 'archived' AND t.assignee IS NOT NULL GROUP BY t.assignee, board_status`)) (byAssignee[r.assignee] ??= {})[r.board_status] = Number(r.n);
   const byMachine = {};
-  for (const r of all(db, "SELECT c.machine, t.status, COUNT(*) AS n FROM tasks t JOIN supercode_cards c ON c.task_id = t.id WHERE t.status != 'archived' AND c.machine IS NOT NULL GROUP BY c.machine, t.status")) (byMachine[r.machine] ??= {})[r.status] = Number(r.n);
-  const oldest = one(db, "SELECT MIN(created_at) AS ts FROM tasks WHERE status = 'ready'")?.ts;
+  for (const r of all(db, `SELECT c.machine, ${stateSql} AS board_status, COUNT(*) AS n ${rows} WHERE t.status != 'archived' AND c.machine IS NOT NULL GROUP BY c.machine, board_status`)) (byMachine[r.machine] ??= {})[r.board_status] = Number(r.n);
+  const oldest = one(db, `SELECT MIN(t.created_at) AS ts ${rows} WHERE ${stateSql} = 'ready'`)?.ts;
   const t = now();
   return { by_status: byStatus, by_assignee: byAssignee, by_machine: byMachine, oldest_ready_age_seconds: oldest ? t - Number(oldest) : null, now: t };
 }
@@ -1043,7 +1068,8 @@ export function diagnosePublishing(publishing) {
  * same thing can go wrong, and supercode's own where only its sessions can): each `{ kind, severity, title, data,
  * actions }`, worst first.
  */
-export function diagnose(db, task, { failureLimit = DEFAULT_FAILURE_LIMIT, strandedSeconds = 30 * 60, blockedHours = 24, fleet = null, launchWindowSeconds = 300, publishing = null, expiredMail = null, waitingMail = null } = {}) {
+export function diagnose(db, task, { failureLimit = DEFAULT_FAILURE_LIMIT, strandedSeconds = 30 * 60, blockedHours = 24, fleet = null, launchWindowSeconds = 300, publishing = null, expiredMail = null, waitingMail = null, nativeHolds = false } = {}) {
+  task = cardState(task, { nativeHolds });
   const out = [];
   const t = now();
   const events = all(db, 'SELECT kind, payload, created_at FROM task_events WHERE task_id = ? ORDER BY id', task.id);
@@ -1070,9 +1096,10 @@ export function diagnose(db, task, { failureLimit = DEFAULT_FAILURE_LIMIT, stran
   if (lost >= 2) out.push({ kind: 'repeated_session_loss', severity: 'warning', title: `its session was lost ${lost}x in 24h`, data: { lost }, actions: [`supercode workflow set ${task.id} machine <machine>`] });
   const crashes = events.filter((e) => e.kind === 'crashed' && t - e.created_at < 24 * 3600).length;
   if (crashes >= 2) out.push({ kind: 'repeated_crashes', severity: 'error', title: `its worker crashed ${crashes}x in 24h`, data: { crashes }, actions: [`supercode workflow log ${task.id}`] });
-  if (task.status === 'blocked') {
+  if (task.status === 'paused') out.push({ kind: 'paused', severity: 'info', title: holdDescription(task), data: { paused: task.paused }, actions: [`supercode workflow resume ${task.id}`] });
+  if (task.status === 'blocked' && (!nativeHolds || task.blocked_by.length)) {
     const since = [...events].reverse().find((e) => e.kind === 'blocked' || e.kind === 'gave_up')?.created_at ?? task.created_at;
-    if (hours(t - since) >= blockedHours) out.push({ kind: 'stuck_in_blocked', severity: 'warning', title: `blocked for ${Math.floor(hours(t - since))}h`, data: { hours: Math.floor(hours(t - since)) }, actions: [`supercode workflow unblock ${task.id}`] });
+    if (hours(t - since) >= blockedHours) out.push({ kind: 'stuck_in_blocked', severity: 'warning', title: `blocked for ${Math.floor(hours(t - since))}h${holdDescription(task) ? `; ${holdDescription(task)}` : ''}`, data: { hours: Math.floor(hours(t - since)), blocked_by: task.blocked_by }, actions: [`supercode workflow unblock ${task.id}`] });
     const cycles = events.filter((e) => e.kind === 'unblocked' && t - e.created_at < 24 * 3600).length;
     if (cycles >= 3) out.push({ kind: 'block_unblock_cycling', severity: 'warning', title: `block→unblock cycled ${cycles}x in 24h`, data: { cycles }, actions: [] });
   }

package/board/event-stream.mjs

@@ -92,7 +92,12 @@ export async function* followBoardPublications({root,after,signal}) {
             // A pruned floor above the cursor means changes it never read are gone; a new log id means a new store.
             if(!position||position.log!==boundary.log||!Number.isSafeInteger(position.sequence)||position.sequence<boundary.floor||position.sequence>boundary.high)throw resync(`Workflow publication log changed: ${slug}`);
             for(;;){
-              const rows=board.db.prepare('SELECT * FROM supercode_publications WHERE sequence>? ORDER BY sequence LIMIT 32').all(positions[slug].sequence);if(!rows.length)break;
+              const rows=board.tx(db=>{
+                const current=db.prepare('SELECT id,pruned_through FROM supercode_publication_log').get();
+                if(!current||current.id!==position.log||positions[slug].sequence<Number(current.pruned_through))throw resync(`Workflow publication log changed: ${slug}`);
+                return db.prepare('SELECT * FROM supercode_publications WHERE sequence>? AND sequence<=? ORDER BY sequence LIMIT 32').all(positions[slug].sequence,boundary.high);
+              });
+              if(!rows.length)break;
               for(const row of rows){positions[slug].sequence=row.sequence;yield {type:'event',id:row.id,kind:row.kind,sequence:row.sequence,cursor:cursorOf(home,positions),data:{board:slug,card:JSON.parse(row.snapshot)}};}
             }
           }

package/board/files.mjs

@@ -1,3 +1,4 @@
+import { fillReadableIds } from './readable-id.mjs';
 // The `files` backing of a board (docs/architecture/orchestrator.md §2.9, "Backings"): the same tables as a
 // Hermes `kanban.db`, kept as a directory of JSON files instead of one SQLite file. `<id>.json` holds everything of
 // one card (its `tasks` row, its `supercode_cards` row, the links to its parents, its comments, events, runs,
@@ -45,7 +46,7 @@ export function openFilesBoard(dir, { create = false, init, held = false }) {
   // events, and on every read while it keeps no watch on them; a write still compares the files it read (persist)
   board.held = held;
   if (!isFilesBoard(dir)) board.tx(() => {}, { force: true });
-  return { db: board.db, tx: (fn) => board.tx(fn), close: () => board.close(),
+  return { db: board.db, snapshot: (path) => board.read(() => board.mem.prepare('VACUUM INTO ?').run(path)), tx: (fn) => board.tx(fn), close: () => board.close(),
     documentsChanged: () => { board.changed = true; }, documentsUnwatched: (unwatched) => { board.unwatched = unwatched; } };
 }
 
@@ -147,6 +148,7 @@ class FilesBoard {
     if (mem.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'supercode_publication_heads'").get()) markRemovedHeads(mem);
     this.mem = mem;
     this.watch();
+    fillReadableIds(mem);
     this.stamp = stamp;
   }
 

package/board/listing.mjs

@@ -3,6 +3,8 @@
 import { setImmediate as nextTurn } from 'node:timers/promises';
 import { noteStep } from '@volter/supercode-harness-sdk/slow-log';
 import { executionOf } from './session-work.mjs';
+import { CARD_VISIBILITY_SQL } from './visibility.mjs';
+import { cardState, cardStateSql } from './card-state.mjs';
 
 export const LIST_BATCH = 64;
 // A listing on the owner's read door (owner-door.mjs) that can read no committed state without waiting on a writer (a
@@ -45,9 +47,9 @@ const sameRevision = (a, b) => Object.keys(a).every(key => a[key] === b[key]);
 
 // Only the fields cardDict, human lines, filters and sorters use. A human listing never reads
 // body/result/skills or run history. A JSON listing retains its existing full-text contract.
-const HUMAN_FIELDS = 'id,title,assignee,status,priority,tenant,created_at,started_at,completed_at';
+const HUMAN_FIELDS = 'id,readable_id,title,assignee,status,priority,tenant,created_at,started_at,completed_at';
 const JSON_FIELDS = `${HUMAN_FIELDS},body,result,workspace_kind,workspace_path,branch_name,project_id,created_by,skills,max_retries,model_override,provider_override,session_id,workflow_template_id,current_step_key`;
-export const TASK_SUMMARY_INDEX = 'idx_tasks_list_summary';
+export const TASK_SUMMARY_INDEX = 'idx_tasks_list_summary_readable';
 export const TASK_SUMMARY_INDEX_SQL = `CREATE INDEX IF NOT EXISTS ${TASK_SUMMARY_INDEX} ON tasks(${HUMAN_FIELDS},current_run_id,session_id,workflow_template_id,current_step_key)`;
 const RUN_METADATA = `CASE WHEN json_valid(r.metadata) THEN json_object('supercode', json_object(
   'address',json_extract(r.metadata,'$.supercode.address'),'session_id',json_extract(r.metadata,'$.supercode.session_id'),
@@ -66,16 +68,16 @@ export const LAST_BLOCK_SQL = `SELECT CASE WHEN kind = 'blocked' THEN payload EN
     UNION ALL SELECT (SELECT id FROM task_events WHERE task_id = t.id AND kind = 'dependency_wait' ORDER BY id DESC LIMIT 1)
   ))`;
 
-export function listPageSql(detailed, tagCount = 0) {
+export function listPageSql(detailed, tagCount = 0, options = {}) {
   return `SELECT t.rowid AS list_order,${(detailed ? JSON_FIELDS : HUMAN_FIELDS).split(',').map(name => `t.${name}`).join(',')},
-    n.number,c.machine,c.stage${detailed ? ',c.subtask_of' : ''},
+    n.number,c.machine,c.stage,c.paused,c.blocked_by,c.detached${detailed ? ',c.subtask_of' : ''},
     r.id AS run_id,r.status AS run_status,r.started_at AS run_started_at,r.ended_at AS run_ended_at,${RUN_METADATA} AS run_metadata
     ${detailed ? `,(SELECT json_group_array(parent_id) FROM (SELECT parent_id FROM task_links WHERE child_id = t.id ORDER BY parent_id)) AS parents_json,
       (${LAST_BLOCK_SQL}) AS block_payload` : ''}
     FROM tasks t ${detailed ? '' : `INDEXED BY ${TASK_SUMMARY_INDEX}`} LEFT JOIN supercode_cards c ON c.task_id = t.id LEFT JOIN supercode_card_numbers n ON n.task_id = t.id
     LEFT JOIN task_runs r ON r.id = t.current_run_id
-    WHERE t.id IN (SELECT value FROM json_each(?)) AND (? IS NULL OR t.status = ? OR c.stage = ?)
-      AND (? IS NULL OR t.assignee = ?) AND (? IS NULL OR c.machine = ?) AND (? OR t.status != 'archived')
+    WHERE t.id IN (SELECT value FROM json_each(?)) AND (? IS NULL OR ${cardStateSql(options)} = ? OR (? NOT IN ('paused','blocked') AND c.stage = ?))
+      AND (? IS NULL OR t.assignee = ?) AND (? IS NULL OR c.machine = ?) AND ${CARD_VISIBILITY_SQL}
       AND (? IS NULL OR t.tenant = ?) AND (? IS NULL OR t.session_id = ?)
       AND (? IS NULL OR t.workflow_template_id = ?) AND (? IS NULL OR t.current_step_key = ?)
       ${Array.from({ length: tagCount }, () => `AND CASE WHEN json_valid(c.tags) THEN
@@ -92,10 +94,10 @@ export async function listCardsInTurns(db, options = {}) {
   throw Object.assign(new Error('board changed during both listing reads; run list again'), { code: 'board_listing_changed' });
 }
 
-async function readCardsInTurns(db, { detailed = false, status = null, assignee = null, machine = null, includeArchived = false,
-  tenant = null, session = null, workflowTemplateId = null, stepKey = null, tags = [] }, revision) {
+async function readCardsInTurns(db, { detailed = false, status = null, assignee = null, machine = null, includeArchived = false, includeSubtasks = false,
+  tenant = null, session = null, workflowTemplateId = null, stepKey = null, tags = [], nativeHolds = false }, revision) {
   const out = [];
-  const page = prepared(db, listPageSql(detailed, tags.length)), candidates = prepared(db, LIST_CANDIDATES_SQL);
+  const page = prepared(db, listPageSql(detailed, tags.length, { nativeHolds })), candidates = prepared(db, LIST_CANDIDATES_SQL);
   const ceiling = measured('last candidate', () => prepared(db, "SELECT COALESCE(MAX(id), '') AS cursor FROM tasks").get().cursor);
   let cursor = '';
   while (cursor < ceiling) {
@@ -103,7 +105,7 @@ async function readCardsInTurns(db, { detailed = false, status = null, assignee
     const range = measured('candidate range', () => candidates.get(cursor, ceiling));
     if (range.last == null) break;
     const rows = measured(detailed ? 'JSON task rows and latest blocks' : 'human task rows', () => page.all(range.ids,
-      status, status, status, assignee, assignee, machine, machine, includeArchived ? 1 : 0,
+      status, status, status, status, assignee, assignee, machine, machine, includeSubtasks ? 1 : 0, includeArchived ? 1 : 0,
       tenant, tenant, session, session, workflowTemplateId, workflowTemplateId, stepKey, stepKey, ...tags.flatMap(tag => [tag, tag, tag])));
     measured('row projection', () => {
       for (const { run_id, run_status, run_started_at, run_ended_at, run_metadata, parents_json, block_payload, ...task } of rows) {
@@ -117,7 +119,7 @@ async function readCardsInTurns(db, { detailed = false, status = null, assignee
           task.waiting_on = parse(block_payload, {})?.waiting_on ?? null;
           task.run = run ? { id: run.id, status: run.status, started_at: run.started_at, session: metadata.supercode?.address ?? metadata.supercode?.session_id ?? null, execution: task.execution } : null;
         }
-        out.push(task);
+        out.push(cardState(task, { nativeHolds }));
       }
     });
     cursor = range.last;

package/board/machine-fleet.mjs

@@ -82,12 +82,14 @@ export async function readMachineFleet(machines, local) {
   noteStep(`fleet reading (${names.length} machine${names.length === 1 ? '' : 's'}, held records)`, performance.now() - started);
   // `panes`: each answering machine's live pane ids, whether or not a session was read in them
   // `ended`: the panes each machine saw end (its tmux's exit log, or a pane its host keeps dead), with how each ended
-  const online = new Set(), unknown = new Set(), alive = new Set(), native = new Map(), sessions = [], capabilities = new Map(), panes = new Map(), ended = new Map();
+  const online = new Set(), offline = new Set(), unknown = new Set(), errors = new Map(), alive = new Set(), native = new Map(), sessions = [], capabilities = new Map(), panes = new Map(), ended = new Map();
   let localError = null;
   for (const row of rows) {
     if (row.error) {
+      errors.set(row.machine, row.error);
       if (row.machine === local) localError = row.error;
-      else if (row.code !== 'machine_offline') unknown.add(row.machine);
+      else if (row.code === 'machine_offline') offline.add(row.machine);
+      else unknown.add(row.machine);
       continue;
     }
     online.add(row.machine);
@@ -98,13 +100,13 @@ export async function readMachineFleet(machines, local) {
       ...(row.ended ?? []).filter((exit) => exit?.pane && !panes.get(row.machine).has(exit.pane)).map((exit) => [exit.pane, { failed: exit.failed ?? null, how: exit.how ?? null }]),
       ...(row.panes ?? []).filter((pane) => pane.dead).map((pane) => [pane.pane, { failed: null, how: 'its program ended (the pane is kept for its last screen)' }]),
     ]));
-    for (const { pid, activity } of row.activities ?? []) {
+    for (const { pid, activity, locator } of row.activities ?? []) {
       const pane = live.find((item) => item.pid === pid);
       if (!pane || !activity?.session_id || !activity.harness) continue;
       const address = `sc:${row.machine}:${activity.harness}:${activity.session_id}`, running = activity.presence === 'running';
       native.set(address, { alive: running ? true : null, states: [running ? true : null] });
       if (running) alive.add(address);
-      sessions.push({ address, machine: row.machine, harness: activity.harness, session_id: activity.session_id, pane: pane.pane, name: pane.title ?? pane.label ?? null,
+      sessions.push({ address, machine: row.machine, harness: activity.harness, session_id: activity.session_id, locator: locator ?? null, pane: pane.pane, name: pane.title ?? pane.label ?? null,
         starter_session: pane.starter_session ?? null,
         state: running ? 'running' : 'unknown', turn: activity.turn ?? null, native_state: activity.evidence?.native_state ?? null,
         // what a session that needs input says it waits for, what started its open turn (Codex: `goal` for a thread
@@ -114,5 +116,5 @@ export async function readMachineFleet(machines, local) {
     }
   }
   const ok = online.has(local);
-  return { ok, presenceKnown: ok, online, unknown, alive, native, sessions, capabilities, panes, ended, error: ok ? null : `machine ${local}'s door did not answer: ${localError ?? 'no row'}` };
+  return { ok, presenceKnown: ok, online, offline, unknown, errors, alive, native, sessions, capabilities, panes, ended, error: ok ? null : `machine ${local}'s door did not answer: ${localError ?? 'no row'}` };
 }

package/board/notices.mjs

@@ -1,5 +1,5 @@
-/** A notice's text or a mail's subject about a card, with the card's number first (`#42 …`; store.mjs layOutNumbers). */
-export const numbered = (number, text) => (number ? `#${number} ${text}` : text);
+/** A notice's text or a mail's subject about a card, with the card's keyed number first (`VO-42 …`; store.mjs boardKey). */
+export const numbered = (key, number, text) => (number ? `${key}-${number} ${text}` : text);
 /** The number of card `id` in the board's store, or null. */
 export const cardNumber = (db, id) => db.prepare('SELECT number FROM supercode_card_numbers WHERE task_id = ?').get(id)?.number ?? null;