@volter/supercode-orchestrator 0.5.206 → 0.5.208

package/board/cli.mjs

@@ -10,6 +10,7 @@ import { DatabaseSync } from 'node:sqlite';
 import { homeOf, parse } from './args.mjs';
 import { BOARD_OPERATION_VERBS, boardHome, boardOwnerSocket, CALLER_FACTS } from '@volter/teams/board-owner';
 import { current, isCallersCall, ownCall, within } from './call.mjs';
+import { cardState, holdDescription } from './card-state.mjs';
 import { detachSession } from './custody.mjs';
 import { taskStatusOf } from './published.mjs';
 import { executionOf } from './session-work.mjs';
@@ -24,14 +25,14 @@ import { holdLock } from './lock-holder.mjs';
 import { takeEpoch } from './fence.mjs';
 import { dispatcherNotice, holdOwnerHealth, holdRound, holdSwitch } from './owner-health.mjs';
 import { boardTool } from './tools.mjs';
-import { assertSourceReceipt } from './ci.mjs';
+import { arcSources, assertSourceReceipt } from './ci.mjs';
 import { noteStep, recordSlow, takeSteps } from '@volter/supercode-harness-sdk/slow-log';
 // read by name, so an older harness SDK without them still loads: the owner then keeps no per-verb or loop lines
 import * as slowLog from '@volter/supercode-harness-sdk/slow-log';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir, tmpdir, userInfo } from 'node:os';
-import { actorOf, CALLER_RUN_ADDRESS, CALLER_RUN_AGENT, SESSION_CURRENT_RUNS, SESSION_RUNS, sessionIndexed, heldConfigWatched, heldDocumentsChanged, heldDocumentsWatched, holdBoards, retireHeldBoards, releaseHeldBoards, publishMarked, view, backingPaths, layOut, backingOf, boardExists, boardCopyOf, boardPath, briefPath, DEFAULT_BOARD, event, json, listBoards, logsDir, now, openBoard, setActor, setPrincipal, principalOf, isCaller, tx } from './store.mjs';
+import { boardKey, cardRef, actorOf, CALLER_RUN_ADDRESS, CALLER_RUN_AGENT, SESSION_CURRENT_RUNS, SESSION_RUNS, sessionIndexed, heldConfigWatched, heldDocumentsChanged, heldDocumentsWatched, holdBoards, retireHeldBoards, releaseHeldBoards, publishMarked, view, backingPaths, layOut, backingOf, boardExists, boardCopyOf, boardPath, briefPath, DEFAULT_BOARD, event, json, listBoards, logsDir, now, openBoard, setActor, setPrincipal, principalOf, isCaller, tx } from './store.mjs';
 import { isLocalWorkspace } from './workspace.mjs';
 import { openZtrackBoard } from './ztrack.mjs';
 import * as engine from './engine.mjs';
@@ -93,19 +94,22 @@ const callerPath = (named) => notRuntime(resolve(current().cwd, named));
 const SAFE_SESSION = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/;
 const HELP = `supercode workflow <verb> [--root <home>] [--board <slug>] [--json]
 
+A card is named by its id (t_4406c88a) or by its number, keyed or bare (VO-42, vo-42, #42 or 42): the short number the board
+gave it when it was made, read with the board's key, the first letters of the board's name.
+
 The board's verbs, with their flags:
   init [--backing sqlite|files|ztrack] [--document <arcs.md>] [--commit] [--manager <address>] [--dispatching on|off] [--archive-max-lines N] [--archive-period month]
   migrate --backing ztrack --document <arcs.md> --status-map <json>
   boards list|create|rm|switch|show|rename|set-default-workdir|export|import
-  create <title> [--body | --body-file PATH|-] [--assignee] [--parent]... [--workspace scratch|worktree:<repository>|dir:<repository>] [--branch] [--project]
+  create <title> [--readable-id ID] [--body | --body-file PATH|-] [--assignee] [--parent]... [--workspace scratch|worktree:<repository>|dir:<repository>] [--branch] [--project]
          [--tenant] [--priority] [--triage] [--idempotency-key] [--max-runtime 30m] [--created-by] [--skill]... [--max-retries]
          [--model] [--provider] [--reviewer PROFILE] [--goal|--no-goal] [--goal-max-turns] [--initial-status blocked|running]
   swarm <goal> --worker PROFILE:TITLE[:SKILL,SKILL]... --verifier P --synthesizer P
-  list [--mine] [--assignee] [--status] [--tenant] [--session] [--archived] [--sort]   show <id>   context <id>   brief <id> [--run N]   runs <id>
+  list [--mine] [--assignee] [--status] [--tenant] [--session] [--subtasks] [--archived] [--sort]   show <id>   context <id>   brief <id> [--run N]   runs <id>
   set <id> <assignee|machine|model|every|reviewer> <value|none> [--provider] [--ids ...]   assign <id> <profile|none>   set-model <id> [model] [--provider]   set-goal <id>... [--goal-max-turns N] [--off]
   reassign <id> --agent AGENT [--role implementer]   (moves a card role's assignment to another agent; sessions keep their identity)
   claim <id> [--ttl]   reclaim <id> [--reason]   heartbeat <id> [--note] [--until <time|30m>]   link|unlink <parent> <child>
-  comment <id> (<text> | --file PATH|-) [--author] [--max-len] [(--pr URL --pr-head SHA)...]   attach <id> <path> [--name] [--content-type]   attachments <id>   attach-rm <n>
+  comment <id> (<text> | --file PATH|-) [--author] [--max-len] [(--pr URL --pr-head SHA)...] [--source owner/repo:branch]...   attach <id> <path> [--name] [--content-type]   attachments <id>   attach-rm <n>
   attachment-read <id> <attachment-id> [--offset N --length N --version V]   bounded base64/metadata JSON, including through --at
   complete <id>... [--result] [--summary] [--metadata JSON] [--commit SHA]   edit <id> --result [--summary] [--metadata]
   block <id> [reason] (--on <card> | --waiting-on <message id>) [--ids ...]   schedule <id> [reason] [--ids ...]
@@ -113,7 +117,7 @@ The board's verbs, with their flags:
   request-state <id> --state block|pause|done|cancelled --reason <why> [--on <card>|--waiting-on <message>] [--evidence <pointers>]
   unblock <id>... --on <blocker> --reason <what arrived>   request-review <id> (--pr URL --pr-head SHA)... [--summary] [--reviewer] [--force] [--commit SHA]   request-changes <id> <reason> [--finding <finding>]...   reopen-review <id>...   reopen <id>... [--reason]
   promote <id> [reason] [--ids ...] [--force] [--dry-run]   archive <id>... --reason <why> [--rm <id>...]
-  specify <id> [--title --body | --body-file PATH|-] [--workspace scratch|worktree:<repository>|dir:<repository>] [--branch NAME] [--machine M|none] [--all]
+  specify <id> [--readable-id ID] [--title --body | --body-file PATH|-] [--workspace scratch|worktree:<repository>|dir:<repository>] [--branch NAME] [--machine M|none] [--all]
   decompose <id> [--child "<title>[@<profile>]"]... [--all]
   diagnostics [--task] [--severity]   stats   assignees   log <id> [--tail N]   tail <id>   watch [--assignee] [--kinds]
   github-usage [--since 1h]          local REST attempts by caller/endpoint; no GitHub read
@@ -125,14 +129,14 @@ The board's verbs, with their flags:
 And:
   events [--after <cursor>] [--once] --json
       Native retained card snapshots, then committed changes; a changed source requests resynchronization.
-  usage [--agent AGENT] [--sponsor PERSON] [--json]
-      Tokens each agent's ended card sessions recorded (the harness's own records), per model, summed on its sponsor.
+  usage [--agent AGENT] [--json]
+      Tokens each agent's ended card sessions recorded (the harness's own records), per model.
   init --backing sqlite|files · boards create <slug>
       Where the Org's one task store is kept: sqlite is one database file, kanban.db (the default); files is one JSON file per
       card. A board is a saved view over that store: the cards carrying its slug as a tag (create --tag, tag/untag).
-  create … --tag T… --sponsor PERSON | --requested-by <platform>:<user> [--request <message ref>]
-      Tags are ordered (the first is the tenant). A proven requester sponsors the card with the request as
-      evidence; an unproven one is recorded as requested by (unverified) and the sponsor stays inherited.
+  create … --tag T… --requested-by <platform>:<user> [--request <message ref>]
+      Tags are ordered (the first is the tenant). The requester is recorded with what Teams' identity record says of
+      them (proven or not) and the request.
   tag <id> <tag>…   untag <id> <tag>…
   create … --machine M --subtask-of ARC --notify ADDRESS|--no-notify --no-start
       With a pane lane and room, a card starts at once and answers "started" with its session; else it answers why it
@@ -149,7 +153,8 @@ And:
 
   specify <id> --workspace dir:<repository> --branch NAME: the manager retargets a stopped card without replacing its history.
   specify <id> --workspace … --machine M: declares the workspace on M and moves the card there, never asking the machine it leaves.
-  comment <id> TEXT (--pr URL --pr-head SHA)...: the card's implementer or the manager adds PRs (including merged ones) to the arc's discovered source set, in the card's own repositories, each followed at its current head; the latest declaration replaces the previous one. This records evidence; only the board starts its review.
+  comment <id> TEXT (--pr URL --pr-head SHA)...: the card's implementer or the manager adds PRs (including merged ones) to the arc's discovered source set, in the arc's repositories (its workspace, its declared sources, its tasks'), each followed at its current head; the latest declaration replaces the previous one. This records evidence; only the board starts its review.
+  comment <arc> TEXT --source owner/repo:branch...: the arc's implementer or the manager declares every repository and branch the arc changes, on the arc itself; its review discovers PRs from them and accepts --pr declarations in them, with no task registered there. The latest declaration is the complete set.
   request-review <id> (--pr URL --pr-head SHA)...: hand over every open PR the arc changed, each at its pushed head; one review covers them all.
   request-state <id> --state done (--reviewed-sha SHA)...: record the verdict on every requested PR head.
   request-state <id>... --state STATE --reason REASON: request several decisions in one retained manager mail.
@@ -192,7 +197,8 @@ const isView = (root, slug) => slug !== DEFAULT_BOARD && !boardExists(root, slug
 function boardMeta(root, slug) {
   const meta = { slug, name: slug === DEFAULT_BOARD ? 'Default' : slug, description: '', icon: '', color: '', default_workdir: null, project_id: null, created_at: null, archived: false };
   try { Object.assign(meta, JSON.parse(readFileSync(metaPath(root, slug), 'utf8')), { slug }); } catch { /* no metadata yet */ }
-  return { ...meta, db_path: boardPath(root, slug), backing: backingOf(root, slug) };
+  const store = boardExists(root, slug) ? slug : DEFAULT_BOARD;
+  return { ...meta, key: boardKey(root, store), db_path: boardPath(root, store), backing: backingOf(root, store) };
 }
 
 function writeMeta(root, slug, patch) {
@@ -201,7 +207,7 @@ function writeMeta(root, slug, patch) {
   meta.created_at ??= now();
   mkdirSync(boardDir(root, slug), { recursive: true });
   writeFileSync(metaPath(root, slug), `${JSON.stringify(meta, null, 2)}\n`);
-  return { ...meta, db_path: boardPath(root, slug), backing: backingOf(root, slug) };
+  return boardMeta(root, slug);
 }
 
 /** Hermes's list: the default board and every named one with a database or metadata. */
@@ -226,7 +232,7 @@ function counts(root, slug) {
   if (view && !boardExists(root, DEFAULT_BOARD)) return {};
   const b = openBoard(root, view ? DEFAULT_BOARD : slug);
   try {
-    const rows = b.db.prepare('SELECT t.status, t.tenant, c.tags FROM tasks t LEFT JOIN supercode_cards c ON c.task_id = t.id').all();
+    const rows = engine.listCards(b.db, { ...stateOptions(root), includeSubtasks: false });
     const out = {};
     for (const r of rows) if (!view || tagsOf(r).includes(slug)) out[r.status] = (out[r.status] ?? 0) + 1;
     return out;
@@ -303,17 +309,12 @@ async function callerPrincipal(root, sid, { teams = false, recordedAgent = null
   return !scope.offline && scope.principal ? `person:${scope.principal}` : null;
 }
 
-/** C4: a requester named by an outside id; a proven link makes them the card's sponsor, anything less is recorded unverified. */
-async function requestedSponsor(args) {
-  if (args.sponsor) return { sponsor: args.sponsor, sponsorEvidence: args.request ? { request: args.request, by: principalOf() } : null };
-  if (!args['requested-by']) return {};
+/** C4: a requester named by an outside id, recorded with what Teams' identity record says of them: a record only. */
+async function requester(args) {
   let resolved = null;
-  try { resolved = (await agentDoor('resolveIdentity', [args['requested-by']], { context: current().facts.SUPERCODE_CONTEXT })).data; } catch { /* no Teams: unverified */ }
-  if (resolved?.classification === 'proven' && resolved.principal?.kind === 'user') {
-    const link = resolved.links?.find((l) => l.classification === 'proven');
-    return { sponsor: resolved.principal.id, sponsorEvidence: { observation: args['requested-by'], link: link?.id ?? null, proof: link?.proof?.kind ?? null, request: args.request ?? null, by: principalOf() } };
-  }
-  return { requestedByUnverified: { observation: args['requested-by'], label: resolved?.label ?? 'unresolved', request: args.request ?? null } };
+  try { resolved = (await agentDoor('resolveIdentity', [args['requested-by']], { context: current().facts.SUPERCODE_CONTEXT })).data; } catch { /* no Teams: unresolved */ }
+  const link = resolved?.classification === 'proven' ? resolved.links?.find((l) => l.classification === 'proven') : null;
+  return { requestedByUnverified: { observation: args['requested-by'], label: resolved?.label ?? 'unresolved', ...(link ? { proven: { principal: resolved.principal?.id ?? null, link: link.id, proof: link.proof?.kind ?? null } } : {}), request: args.request ?? null } };
 }
 
 const tagsOf = (card) => { const tags = Array.isArray(card.tags) ? card.tags : json(card.tags, null); return Array.isArray(tags) ? tags : card.tenant ? [card.tenant] : []; };
@@ -321,7 +322,7 @@ const tagsOf = (card) => { const tags = Array.isArray(card.tags) ? card.tags : j
 const say = (args, human, value) => { current().out(args.json ? `${JSON.stringify(value, null, 2)}\n` : `${human}\n`); };
 
 // Hermes's own output lines, so a reader of `hermes kanban list` reads this one
-const ICONS = { todo: '◻', ready: '▶', running: '●', scheduled: '⏱', blocked: '⊘', done: '✓', archived: '—' };
+const ICONS = { todo: '◻', ready: '▶', running: '●', scheduled: '⏱', blocked: '⊘', paused: '⏸', done: '✓', archived: '—' };
 const ts = (t) => {
   if (!t) return '';
   const d = new Date(Number(t) * 1000);
@@ -329,16 +330,19 @@ const ts = (t) => {
   return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
 };
 // a card's status is the workflow's (triaging, reviewing, …); kanban.db stores the Hermes status it maps to
-const line = (t) => `${ICONS[t.status] ?? '?'} ${t.id}  ${(t.stage ?? t.status).padEnd(8)}${t.detached ? ` [session belongs to ${t.detached.person}]` : ['running','review'].includes(t.status) ? ` [session ${t.execution?.state ?? 'unknown'}]` : ''}  ${(t.assignee || '(unassigned)').padEnd(20)}${t.tenant ? ` [${t.tenant}]` : ''}  ${t.title}${t.machine ? `  @${t.machine}` : ''}`;
-const cardDict = (t) => ({
-  id: t.id, title: t.title, body: t.body, assignee: t.assignee, status: t.status, priority: t.priority, tenant: t.tenant,
+const line = (key) => (t) => `${ICONS[t.status] ?? '?'} ${engine.cardLabel(key, t.number, t.id, t.readable_id).padEnd(18)}  ${(['paused','blocked'].includes(t.status) ? t.status : t.stage ?? t.status).padEnd(8)}${holdDescription(t) ? ` [${holdDescription(t)}]` : t.detached ? ` [session belongs to ${t.detached.person}]` : ['running','review'].includes(t.status) ? ` [session ${t.execution?.state ?? 'unknown'}]` : ''}  ${(t.assignee || '(unassigned)').padEnd(20)}${t.tenant ? ` [${t.tenant}]` : ''}  ${t.title}${t.machine ? `  @${t.machine}` : ''}`;
+// `key` is the card's board's (store.mjs boardKey); `ref` the card as a person names it (`VO-856`)
+const stateOptions = root => ({ nativeHolds: Boolean(workflowFor(root).workflow.flags?.paused) });
+const cardDict = (raw, key, options) => { const t = cardState(raw, options); return ({
+  id: t.id, readable_id: t.readable_id ?? null, number: t.number ?? null, key, ref: cardRef(key, t.number) ?? null, title: t.title, body: t.body, assignee: t.assignee, status: t.status, priority: t.priority, tenant: t.tenant,
   workspace_kind: t.workspace_kind, repository: t.workspace_anchor ?? null, workspace_path: t.workspace_path, branch_name: t.branch_name, project_id: t.project_id,
   created_by: t.created_by, created_at: t.created_at, started_at: t.started_at, completed_at: t.completed_at, result: t.result,
   skills: t.skills ?? [], max_retries: t.max_retries, model_override: t.model_override, provider_override: t.provider_override,
   session_id: t.session_id, workflow_template_id: t.workflow_template_id, current_step_key: t.current_step_key,
   machine: t.machine ?? null, subtask_of: t.subtask_of ?? null, execution: t.execution ?? null, detached: t.detached ?? null,
   reviewer: t.reviewer ?? null,
-});
+  paused: t.paused, blocked_by: t.blocked_by,
+}); };
 
 /** Hermes's durations: seconds, or 30s / 5m / 2h / 1d. */
 // a moment the caller names: an ISO time, or a duration from now (30m, 2h); epoch seconds, or null
@@ -366,6 +370,40 @@ const metadataOf = (v) => {
   return got;
 };
 
+// A card is named by its id or by its number, keyed or bare (`VO-42`, `vo-42`, `#42`, `42`: store.mjs boardKey,
+// layOutNumbers) in every place a verb takes a card: its card positionals (none, the first, the first two, or all of
+// them) and its card flags. A number is read as its card's id before anything else reads the verb (its authorization
+// included). A number no card here has, or a key that is not this board's, is refused. A key is two or more letters, so
+// a message id (`m-…`, `a-…`) is never read as one.
+const NO_CARD_WORDS = new Set(['create', 'new', 'swarm', 'list', 'ls', 'migrate', 'init', 'boards', 'usage', 'events', 'listeners', 'dispatch',
+  'capacity', 'deliver', 'daemon', 'serve', 'gc', 'repair', 'dispatching', 'attach-rm', 'run-session', 'stats', 'assignees', 'diagnostics', 'diag',
+  'watch', 'help', 'github-usage']);
+// the verbs that act on every positional as a card (each loops over them all)
+const ALL_CARD_WORDS = new Set(['complete', 'archive', 'request-state', 'request_state', 'set-goal', 'unblock', 'reopen', 'reopen-review']);
+const CARD_FLAGS = ['ids', 'subtask-of', 'parent', 'on', 'for-card', 'task', 'rm'];
+const CARD_NUMBER = /^(?:#|([A-Za-z][A-Za-z0-9]+)-)?([1-9]\d*)$/;
+function resolveCardNumbers(verb, rest, args, withBoard, keyOf) {
+  const words = NO_CARD_WORDS.has(verb) ? 0 : ALL_CARD_WORDS.has(verb) ? rest.length : ['link', 'unlink'].includes(verb) ? 2 : 1;
+  const places = [];
+  for (let i = 0; i < Math.min(words, rest.length); i++) places.push([rest, i]);
+  for (const flag of CARD_FLAGS) {
+    if (Array.isArray(args[flag])) args[flag].forEach((_, i) => places.push([args[flag], i]));
+    else if (typeof args[flag] === 'string') places.push([args, flag]);
+  }
+  const numbered = places.filter(([holder, key]) => CARD_NUMBER.test(String(holder[key])));
+  if (!numbered.length) return;
+  const own = keyOf();
+  withBoard((b) => view(b, (db) => {
+    for (const [holder, at] of numbered) {
+      const [, named, digits] = CARD_NUMBER.exec(String(holder[at]));
+      if (named && named.toUpperCase() !== own) throw new Error(`${holder[at]} names a card of board ${named.toUpperCase()}, not of this board (${own}); nothing was done`);
+      const id = engine.cardByNumber(db, Number(digits));
+      if (!id) throw new Error(`no card ${own}-${digits} on this board`);
+      holder[at] = id;
+    }
+  }));
+}
+
 /** One verb in full, in the call it runs in (call.mjs): a caller's in the owner, or the process's own here. */
 export async function runVerb(argv) {
   const args = parse(argv);
@@ -390,6 +428,9 @@ export async function runVerb(argv) {
   const open = (create = false) => { const b = openBoard(root, slug, { create, document: args.document ?? null, backing: create ? args.backing ?? null : null }); b.label = boardLabel(root, slug); return b; };
   const withBoard = (fn, create = false) => { const b = open(create); try { return fn(b); } finally { b.close(); } };
   const withBoardAsync = async (fn, create = false) => { const b = open(create); try { return await fn(b); } finally { b.close(); } };
+  // the board's key (store.mjs boardKey), read when a card is named or shown by its number
+  const keyOf = () => boardKey(root, slug);
+  resolveCardNumbers(verb, rest, args, withBoard, keyOf);
   const id = rest[0];
   const need = (n, what) => { if (rest.length < n) throw new Error(`${verb} needs ${what}`); };
   const ids = (first = rest) => [...first, ...(args.ids ?? [])];
@@ -516,19 +557,19 @@ export async function runVerb(argv) {
       let workspace = args.workspace;
       if ((workspace === 'dir' || workspace === 'worktree') && meta.default_workdir) workspace = `${workspace}:${meta.default_workdir}`;
       // --goal / --no-goal are the create's words; without either, the workflow's initial decides
-      // a person filing for themselves sponsors it; an agent filing a person's request names them (proven) or records them unverified
-      const sponsorship = args.sponsor || args['requested-by'] ? await requestedSponsor(args) : principalOf()?.startsWith('person:') ? { sponsor: principalOf().slice('person:'.length) } : {};
+      // an agent filing a person's request records who asked
+      const requested = args['requested-by'] ? await requester(args) : {};
       const created = await withBoardAsync(async (b) => engine.createCard(b, await engine.prepareCard(b, {
         title: rest.join(' '), body: textFrom(args['body-file'], args.body), assignee: args.assignee === 'none' ? null : args.assignee, machine: args.machine,
         reviewer: args.reviewer ?? null,
-        workspace, branch: args.branch, parents: args.parent, priority: args.priority, tenant: args.tenant,
+        readableId: args['readable-id'], workspace, branch: args.branch, parents: args.parent, priority: args.priority, tenant: args.tenant,
         triage: args.triage, idempotencyKey: args['idempotency-key'], maxRuntime: duration(args['max-runtime']),
         maxRetries, skills: args.skill, model: args.model, provider: args.provider, createdBy: args['created-by'] ?? null,
         noStart: Boolean(args['no-start']), adopt: args.adopt ?? null,
         every: args.every ?? null, sessionId: callerSession(), subtaskOf: args['subtask-of'] ?? null, initialStatus: args['initial-status'] ?? null,
         project: args.project ?? meta.project_id ?? null, goal: args.goal ? { maxTurns: args['goal-max-turns'] ? Number(args['goal-max-turns']) : null } : args['no-goal'] ? false : null,
         tags: [...(viewTag ? [viewTag] : []), ...(args.tag ?? [])],
-        ...sponsorship,
+        ...requested,
       })), true);
       await withBoardAsync(b=>engine.runEffects(b,created.effects??[]));
       let answer = { id: created.id, existing: created.existing };
@@ -544,9 +585,9 @@ export async function runVerb(argv) {
       if (address) withBoard((b) => engine.subscribe(b, created.id, address, 'creator'));
       const task = withBoard((b) => view(b, (db) => engine.getTask(db, created.id)));
       const recipients = withBoard(b => engine.subscriptions(b.db, created.id)).filter(s => s.platform === 'supercode').map(s => s.chat_id);
-      if (args.json) { say(args, '', { ...cardDict(task), ...answer, notify: address ?? null, recipients }); return answer.failed ? 1 : 0; }
+      if (args.json) { say(args, '', { ...cardDict(task, keyOf(), stateOptions(root)), ...answer, notify: address ?? null, recipients }); return answer.failed ? 1 : 0; }
       const said = answer.adoption_requested ? `; held for ${answer.adoption_requested}, which the dispatcher binds on its next tick` : answer.started ? `; started session ${answer.session} (${answer.mode})` : answer.failed ? `; did not start: ${answer.failed}` : answer.waits ? `; waits: ${answer.waits}` : '';
-      say(args, `${created.existing ? 'Existing' : 'Created'} ${created.id}  (${task.status}, assignee=${task.assignee || '-'})${said}${recipients.length ? `; notices go to ${recipients.join(', ')}` : ''}`, null);
+      say(args, `${created.existing ? 'Existing' : 'Created'} ${engine.cardLabel(keyOf(), task.number, created.id, task.readable_id)}  (${task.status}, assignee=${task.assignee || '-'})${said}${recipients.length ? `; notices go to ${recipients.join(', ')}` : ''}`, null);
       return answer.failed ? 1 : 0;
     }
 
@@ -565,7 +606,7 @@ export async function runVerb(argv) {
 
     case 'list': case 'ls': {
       const assignee = args.assignee ?? (args.mine ? callerName() : null);
-      const cards = await withBoardAsync(b => listCardsInTurns(b.db, { detailed: Boolean(args.json), status: args.status, assignee, machine: args.machine, includeArchived: args.archived || args.all,
+      const cards = await withBoardAsync(b => listCardsInTurns(b.db, { ...stateOptions(root), detailed: Boolean(args.json), status: args.status, assignee, machine: args.machine, includeArchived: args.archived || args.all, includeSubtasks: args.subtasks || args.all,
         tenant: args.tenant, session: args.session, workflowTemplateId: args['workflow-template-id'], stepKey: args['step-key'], tags: [...(viewTag ? [viewTag] : []), ...(args.tag ?? [])] }));
       const sorters = {
         assignee: (a, b) => String(a.assignee ?? '').localeCompare(String(b.assignee ?? '')), created: (a, b) => a.created_at - b.created_at,
@@ -575,14 +616,15 @@ export async function runVerb(argv) {
       };
       if (args.sort) { if (!sorters[args.sort]) throw new Error(`--sort is one of ${Object.keys(sorters).join(', ')}`); cards.sort(sorters[args.sort]); }
       if (args.json) {
-        await writeCardList(cards, t => ({ ...cardDict(t), workflow_status: t.workflow_status, parents: t.parents, run: t.run, waiting_on: t.waiting_on }), current().out);
+        const own = keyOf();
+        await writeCardList(cards, t => ({ ...cardDict(t, own, stateOptions(root)), workflow_status: t.workflow_status, parents: t.parents, run: t.run, waiting_on: t.waiting_on }), current().out);
         return 0;
       }
       const others = boardsOf(root, { includeArchived: false }).length - 1;
       if (others > 0) current().out(`Board: ${slug} (${others} other board${others === 1 ? '' : 's'} — \`supercode workflow boards list\`)\n\n`);
       if (!cards.length) current().out('(no matching tasks)\n');
       for (let offset = 0; offset < cards.length; offset += 64) {
-        current().out(`${cards.slice(offset, offset + 64).map(line).join('\n')}\n`);
+        current().out(`${cards.slice(offset, offset + 64).map(line(keyOf())).join('\n')}\n`);
         await new Promise(resolve => setImmediate(resolve));
       }
       return 0;
@@ -592,11 +634,11 @@ export async function runVerb(argv) {
       need(1, 'a card id');
       const { settings } = await laneState(root).catch(() => ({ settings: boardSettings({}) }));
       const card = withBoard((b) => {
-        const got = engine.showCard(b.db, id);
+        const got = engine.showCard(b.db, id, stateOptions(root));
         got.runs = engine.runs(b.db, id, { stateType: args['state-type'] ?? null, stateName: args['state-name'] ?? null });
         got.task.execution = executionOf(engine.currentRun(b.db, id));
         got.runs = got.runs.map(run => ({ ...run, execution: executionOf(run) }));
-        got.diagnostics = engine.diagnose(b.db, got.task, { failureLimit: settings.failureLimit, launchWindowSeconds: settings.launchWindow });
+        got.diagnostics = engine.diagnose(b.db, got.task, { ...stateOptions(root), failureLimit: settings.failureLimit, launchWindowSeconds: settings.launchWindow });
         got.stage = statusOf(b.db, got.task);
         const entry = workflowFor(root);
         // A workflow may explicitly replace the built-in time field. Keep its
@@ -606,20 +648,24 @@ export async function runVerb(argv) {
           : timeOf(b.db, got.task);
         return got;
       });
-      const t = card.task;
+      const t = cardState({ ...card.task, stage: card.stage }, stateOptions(root));
       const latest = [...card.runs].reverse().find((r) => r.summary)?.summary ?? null;
       if (args.json) {
-        say(args, '', { task: cardDict(t), side_sessions: withBoard((b) => sideSessions(b.db, t.id)), latest_summary: latest, parents: card.parents.map((p) => p.id), children: card.children, subtasks: card.subtasks, comments: card.comments, events: card.events, runs: card.runs, time: card.time, subscriptions: card.subscriptions, diagnostics: card.diagnostics });
+        say(args, '', { task: cardDict(t, keyOf(), stateOptions(root)), sources: withBoard((b) => arcSources(b.db, t.id)), side_sessions: withBoard((b) => sideSessions(b.db, t.id)), latest_summary: latest, parents: card.parents.map((p) => p.id), children: card.children, subtasks: card.subtasks, comments: card.comments, events: card.events, runs: card.runs, time: card.time, subscriptions: card.subscriptions, diagnostics: card.diagnostics });
         return 0;
       }
-      const out = [`Task ${t.id}: ${t.title}`, `  status:    ${taskStatusOf(card.stage, t.completed_at)} (lane ${card.stage}${card.stage !== t.status ? `, ${t.status} in kanban.db` : ''})`, `  assignee:  ${t.assignee || '-'}`];
+      const labels = withBoard((b) => view(b, (db) => engine.numbersOf(db, [t.subtask_of, ...card.parents.map((p) => p.id), ...card.children].filter(Boolean))));
+      const boardKeyNow = keyOf();
+      const label = (cardId) => engine.cardLabel(boardKeyNow, labels.get(cardId), cardId);
+      const out = [`Task ${engine.cardLabel(boardKeyNow, t.number, t.id, t.readable_id)}: ${t.title}`, `  status:    ${['paused','blocked'].includes(t.status) ? t.status : taskStatusOf(card.stage, t.completed_at)} (lane ${card.stage})`, `  assignee:  ${t.assignee || '-'}`];
+      if (holdDescription(t)) out.push(`  hold:      ${holdDescription(t)}`);
       if (t.machine) out.push(`  machine:   ${t.machine}`);
       if (t.reviewer) out.push(`  reviewer:  ${t.reviewer} (card override)`);
       if (t.detached) out.push(`  session:   ${t.detached.session.address} belongs to ${t.detached.person} (detached ${ts(t.detached.at)}; dispatcher does not own it)`);
       // where the card's time went: each role's runs, and the rest waiting
       const mins = (sec) => `${Math.round(sec / 60)}m`;
       out.push(`  time:      ${Object.entries(card.time).filter(([, v]) => v > 0).map(([k, v]) => `${k} ${mins(v)}`).join(', ') || '-'}`);
-      if (t.subtask_of) out.push(`  subtask of: ${t.subtask_of}`);
+      if (t.subtask_of) out.push(`  subtask of: ${label(t.subtask_of)}`);
       if (t.tenant) out.push(`  tenant:    ${t.tenant}`);
       out.push(`  workspace: ${t.workspace_kind}${t.workspace_anchor ? `:${t.workspace_anchor}` : ''}`);
       if (t.workspace_path) out.push(`  resolved:  ${t.workspace_path}`);
@@ -630,27 +676,28 @@ export async function runVerb(argv) {
       out.push(`  created:   ${ts(t.created_at)} by ${t.created_by || '-'}`);
       const own = withBoard((b) => engine.getTask(b.db, t.id));
       if (own?.tags?.length) out.push(`  tags:      ${own.tags.join(', ')}`);
-      if (own?.sponsor) out.push(`  sponsor:   ${own.sponsor}${own.sponsor_evidence?.observation ? ` (requested by ${own.sponsor_evidence.observation}, proven)` : ''}`);
-      if (own?.requested_by_unverified) out.push(`  requested by (unverified): ${own.requested_by_unverified.label ?? own.requested_by_unverified.observation}`);
+      if (own?.requested_by_unverified) out.push(`  requested by: ${own.requested_by_unverified.label ?? own.requested_by_unverified.observation}${own.requested_by_unverified.proven ? ' (proven)' : ' (unverified)'}`);
       if (card.diagnostics.length) {
         out.push('', `  Diagnostics (${card.diagnostics.length}):`);
-        for (const d of card.diagnostics) { out.push(`    ${{ warning: '⚠', error: '!!', critical: '!!!' }[d.severity]} [${d.severity}] ${d.title}`); for (const a of d.actions.slice(0, 1)) out.push(`       → ${a}`); }
+        for (const d of card.diagnostics) { out.push(`    ${{ info: 'ℹ', warning: '⚠', error: '!!', critical: '!!!' }[d.severity]} [${d.severity}] ${d.title}`); for (const a of d.actions.slice(0, 1)) out.push(`       → ${a}`); }
       }
       if (t.started_at) out.push(`  started:   ${ts(t.started_at)}`);
       if (t.completed_at) out.push(`  completed: ${ts(t.completed_at)}`);
-      if (card.parents.length) out.push(`  parents:   ${card.parents.map((p) => p.id).join(', ')}`);
-      if (card.children.length) out.push(`  children:  ${card.children.join(', ')}`);
-      if (card.subtasks.length) out.push(`  subtasks:  ${card.subtasks.map((s) => `${s.id} (${s.status})`).join(', ')}`);
+      if (card.parents.length) out.push(`  parents:   ${card.parents.map((p) => label(p.id)).join(', ')}`);
+      if (card.children.length) out.push(`  children:  ${card.children.map(label).join(', ')}`);
+      if (card.subtasks.length) out.push(`  subtasks:  ${card.subtasks.map((s) => `${engine.cardLabel(boardKeyNow, s.number, s.id)} (${s.status})`).join(', ')}`);
       const side = withBoard((b) => sideSessions(b.db, t.id));
       if (side.length) out.push(`  side sessions: ${side.map((s) => s.address).join(', ')}`);
       if (t.body) out.push('', 'Body:', t.body);
+      // the repositories and branches the arc declares it changes (comment --source)
+      { const sources = withBoard((b) => arcSources(b.db, t.id)); if (sources.length) out.push('', `Sources: ${sources.map((x) => `${x.repository}:${x.branch}`).join(', ')}`); }
       if (t.result) out.push('', 'Result:', t.result);
       else if (latest) out.push('', 'Latest summary:', latest);
       if (card.comments.length) { out.push('', `Comments (${card.comments.length}):`); for (const c of card.comments) out.push(`  [${ts(c.created_at)}] ${c.author}: ${c.body}`); }
       // the card's history, without the board's own bookkeeping (a claim, a session kept or started, a goal ask, a
       // message queued); `--all` shows every event, `--json` always does
       const PLUMBING = new Set(['claimed', 'session_started', 'session_resumed', 'session_adopted', 'agent_session_queued', 'session_replaced', 'session_closed',
-        'goal_set', 'goal_continued', 'decision_asked', 'board_message', 'board_message_sent', 'heartbeat', 'promoted', 'respawn_guarded',
+        'goal_set', 'goal_continued', 'decision_asked', 'board_message', 'board_message_sent', 'review_wait_cleared', 'heartbeat', 'promoted', 'respawn_guarded',
         'claim_extended', 'reclaimed', 'reconciled', 'status']);
       const history = args.all ? card.events : card.events.filter((e) => !PLUMBING.has(e.kind));
       if (history.length) {
@@ -672,20 +719,16 @@ export async function runVerb(argv) {
       return 0;
     }
 
-    // G3: usage from each run's own harness records, summed on agents and on their sponsors
+    // G3: usage from each run's own harness records, summed on agents
     case 'usage': {
       const byAgent = agentUsage(root), context = current().facts.SUPERCODE_CONTEXT;
-      const sponsorOf = async (agent) => { try { return (await agentDoor('get', [agent], { context })).data.sponsor ?? null; } catch { for (const row of activeAgentAssignments(root).filter((a) => a.agent_id === agent)) { const local = localAgentRecord(root, row.org, agent); if (local) return local.identity.sponsor ?? null; } return null; } };
       const sum = (records) => { const out = {}; for (const u of records) { const m = out[u.model] ??= { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0, cost: 0 }; m.input_tokens += u.input_tokens ?? 0; m.output_tokens += u.output_tokens ?? 0; m.cache_read_tokens += u.cache_read_tokens ?? 0; m.cache_write_tokens += u.cache_write_tokens ?? 0; m.cost += u.cost?.amount ?? 0; if (u.cost?.amount != null) { m.cost_recorded = true; m.currency = u.cost.currency ?? m.currency ?? null; } else m.cost_unrecorded = true; } return out; };
       // a harness that keeps no price records tokens only: its cost reads as unrecorded, never as zero
       const line = (byModel) => Object.entries(byModel).map(([m, t]) => `${m} in ${t.input_tokens} out ${t.output_tokens} cache read ${t.cache_read_tokens} write ${t.cache_write_tokens} cost ${t.cost_recorded ? `${t.cost.toFixed(4)} ${t.currency ?? ''}${t.cost_unrecorded ? ' (some sessions unrecorded)' : ''}`.trim() : 'unrecorded'}`).join('; ');
       const agents = [...byAgent.keys()].filter((a) => !args.agent || a === args.agent);
-      const rows = (await Promise.all(agents.map(async (agent) => ({ agent, sponsor: args.sponsor || !args.agent ? await sponsorOf(agent) : undefined, sessions: new Set(byAgent.get(agent).map((u) => u.session)).size, by_model: sum(byAgent.get(agent)) }))))
-        .filter((row) => !args.sponsor || row.sponsor === args.sponsor);
+      const rows = agents.map((agent) => ({ agent, sessions: new Set(byAgent.get(agent).map((u) => u.session)).size, by_model: sum(byAgent.get(agent)) }));
       const total = sum(rows.flatMap((row) => byAgent.get(row.agent)));
-      const sponsors = [...new Set(rows.map((row) => row.sponsor).filter(Boolean))].map((sponsor) => ({ sponsor, agents: rows.filter((row) => row.sponsor === sponsor).length, by_model: sum(rows.filter((row) => row.sponsor === sponsor).flatMap((row) => byAgent.get(row.agent))) }));
-      say(args, rows.length ? [...rows.map((r) => `${r.agent}${r.sponsor ? ` (sponsor ${r.sponsor})` : ''}: ${r.sessions} session(s) ${line(r.by_model)}`),
-        ...sponsors.map((s) => `sponsor ${s.sponsor}: ${s.agents} agent(s) ${line(s.by_model)}`), `total: ${line(total)}`].join('\n') : '(no recorded usage)', { agents: rows, sponsors, total, ...(args.sponsor ? { sponsor: args.sponsor } : {}) });
+      say(args, rows.length ? [...rows.map((r) => `${r.agent}: ${r.sessions} session(s) ${line(r.by_model)}`), `total: ${line(total)}`].join('\n') : '(no recorded usage)', { agents: rows, total });
       return 0;
     }
 
@@ -785,7 +828,7 @@ export async function runVerb(argv) {
       need(args.file !== undefined ? 1 : 2, 'a card id and the text (or --file PATH, - for stdin)');
       let text = textFrom(args.file, rest.slice(1).join(' '));
       if (args['max-len']) text = text.slice(0, Number(args['max-len']));
-      const n = await withBoardAsync((b) => engine.comment(b, id, isLatestReviewer(b.db, id, actorOf()) ? actorOf() : args.author ?? callerAddress() ?? callerName(), text, { pr: args.pr ?? null, pr_head: args['pr-head'] ?? null }));
+      const n = await withBoardAsync((b) => engine.comment(b, id, isLatestReviewer(b.db, id, actorOf()) ? actorOf() : args.author ?? callerAddress() ?? callerName(), text, { pr: args.pr ?? null, pr_head: args['pr-head'] ?? null, source: args.source ?? null }));
       say(args, `Comment added to ${id}`, { ok: true, comment: n }); return 0;
     }
     case 'attach': {
@@ -839,7 +882,7 @@ export async function runVerb(argv) {
       need(1, 'a card id');
       const reason = rest.slice(1).join(' ') || null;
       const results = [];
-      for (const t of [id, ...(args.ids ?? [])]) results.push([t, (await withBoardAsync((b) => engine.block(b, t, { reason, on: args.on ?? null, waitingOn: args['waiting-on'] ?? null }))).to]);
+      for (const t of [id, ...(args.ids ?? [])]) results.push([t, (await withBoardAsync((b) => engine.block(b, t, { reason, kind: args.kind ?? 'needs_input', on: args.on ?? null, waitingOn: args['waiting-on'] ?? null }))).to]);
       say(args, results.map(([t, s]) => `${s === 'todo' ? 'Waiting on dependencies' : s === 'triage' ? 'Routed to triage' : 'Blocked'} ${t}`).join('\n'), { ok: true, results }); return 0;
     }
     case 'schedule': {
@@ -859,7 +902,7 @@ export async function runVerb(argv) {
     case 'request-review': need(1, 'a card id'); await withBoardAsync((b) => engine.requestReview(b, id, { summary: args.summary ?? null, reviewer: args.reviewer ?? null, metadata: metadataOf(args.metadata) ?? null, commit: args.commit ?? null, branch: args.branch ?? null, pr: args.pr ?? null, pr_head: args['pr-head'] ?? args.head ?? args.commit ?? null, force: Boolean(args.force), expectedRunId: workerRun(b.db, id, sid) })); say(args, `${id} → review`, { ok: true }); return 0;
     case 'request-changes': {
       need(2, 'a card id and the reason');
-      // 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.finding ?? []).map((f) => String(f).trim()).filter(Boolean);
       const filed = [];
       for (const finding of findings) filed.push((await withBoardAsync((b) => engine.createCard(b, { title: finding, subtaskOf: id }))).id);
@@ -885,7 +928,7 @@ export async function runVerb(argv) {
       const targets = [id, ...(args.ids ?? [])];
       if (args['dry-run']) {
         const verdicts = withBoard((b) => targets.map((t) => {
-          const card = engine.showCard(b.db, t);
+          const card = engine.showCard(b.db, t, stateOptions(root));
           const open = card.parents.filter((p) => !['done', 'archived'].includes(p.status)).map((p) => p.id);
           const ok = ['todo', 'blocked'].includes(card.task.status) && (!open.length || args.force);
           return { id: t, ok, reason: ok ? null : !['todo', 'blocked'].includes(card.task.status) ? `${t} is ${card.task.status}` : `parents not done: ${open.join(', ')}` };
@@ -915,12 +958,12 @@ export async function runVerb(argv) {
 
     case 'specify': case 'decompose': {
       const { lanes, settings } = await laneState(root);
-      const targets = args.all ? withBoard((b) => engine.listCards(b.db, { status: 'triage' }).filter((t) => !args.tenant || t.tenant === args.tenant).map((t) => t.id)) : [id];
+      const targets = args.all ? withBoard((b) => engine.listCards(b.db, { ...stateOptions(root), status: 'triage' }).filter((t) => !args.tenant || t.tenant === args.tenant).map((t) => t.id)) : [id];
       if (!targets[0]) throw new Error(`${verb} needs a card id, or --all`);
       const results = [];
       for (const t of targets) {
-        if (verb === 'specify' && (args.title !== undefined || args.body !== undefined || args['body-file'] !== undefined || args.workspace !== undefined || args.branch !== undefined || args.machine !== undefined)) {
-          const moved = await withBoardAsync((b) => engine.specify(b, t, { title: args.title ?? null, body: textFrom(args['body-file'], args.body) ?? null, workspace: args.workspace ?? null, branch: args.branch ?? null, machine: args.machine ?? null, author: args.author ?? callerAddress() ?? callerName() }));
+        if (verb === 'specify' && (args['readable-id'] !== undefined || args.title !== undefined || args.body !== undefined || args['body-file'] !== undefined || args.workspace !== undefined || args.branch !== undefined || args.machine !== undefined)) {
+          const moved = await withBoardAsync((b) => engine.specify(b, t, { readableId: args['readable-id'] ?? null, title: args.title ?? null, body: textFrom(args['body-file'], args.body) ?? null, workspace: args.workspace ?? null, branch: args.branch ?? null, machine: args.machine ?? null, author: args.author ?? callerAddress() ?? callerName() }));
           results.push({ id: t, specified: true, status: moved.to });
         } else if (verb === 'decompose' && args.child?.length) {
           const children = args.child.map((c) => { const [title, assignee] = c.split(/@(?=[^@]*$)/); return { title: title.trim(), assignee: assignee?.trim() || undefined }; });
@@ -939,11 +982,11 @@ export async function runVerb(argv) {
       const fleet = await observeFleet(root);
       const publishing = await boardPublishing(root);
       const [expiredMail, waitingMail] = await Promise.all([await mailExpiries(), await mailWaiting()]);
-      const order = ['warning', 'error', 'critical'];
+      const order = ['info', 'warning', 'error', 'critical'];
       const found = withBoard((b) => {
-        const cards = args.task ? [engine.getTask(b.db, args.task)].filter(Boolean) : engine.listCards(b.db, {});
+        const cards = args.task ? [engine.getTask(b.db, args.task)].filter(Boolean) : engine.listCards(b.db, stateOptions(root));
         return [...(args.task ? [] : engine.diagnosePublishing(publishing).map((d) => ({ task: '(board)', title_of_task: null, ...d }))),
-          ...cards.flatMap((t) => engine.diagnose(b.db, t, { failureLimit: settings.failureLimit, fleet, launchWindowSeconds: settings.launchWindow, publishing, expiredMail, waitingMail }).map((d) => ({ task: t.id, title_of_task: t.title, ...d })))]
+          ...cards.flatMap((t) => engine.diagnose(b.db, t, { ...stateOptions(root), failureLimit: settings.failureLimit, fleet, launchWindowSeconds: settings.launchWindow, publishing, expiredMail, waitingMail }).map((d) => ({ task: t.id, title_of_task: t.title, ...d })))]
           .filter((d) => !args.severity || order.indexOf(d.severity) >= order.indexOf(args.severity));
       });
       if (args.json) { say(args, '', found); return 0; }
@@ -951,7 +994,7 @@ export async function runVerb(argv) {
       return 0;
     }
     case 'stats': {
-      const s = withBoard((b) => engine.stats(b.db));
+      const s = withBoard((b) => engine.stats(b.db, stateOptions(root)));
       if (args.json) { say(args, '', s); return 0; }
       const fmt = (o) => Object.entries(o).sort().map(([k, v]) => `${k}=${v}`).join(', ') || '(none)';
       current().out(`By status:   ${fmt(s.by_status)}\nBy assignee:\n${Object.entries(s.by_assignee).map(([a, c]) => `  ${a.padEnd(20)} ${fmt(c)}`).join('\n') || '  (none)'}\nBy machine:\n${Object.entries(s.by_machine).map(([m, c]) => `  ${m.padEnd(20)} ${fmt(c)}`).join('\n') || '  (none)'}\nOldest ready: ${s.oldest_ready_age_seconds === null ? '-' : `${Math.floor(s.oldest_ready_age_seconds / 60)}m`}\n`);
@@ -959,7 +1002,7 @@ export async function runVerb(argv) {
     }
     case 'assignees': {
       const { profiles, lanes } = await laneState(root);
-      const c = withBoard((b) => engine.stats(b.db).by_assignee);
+      const c = withBoard((b) => engine.stats(b.db, stateOptions(root)).by_assignee);
       const data = [...new Set([...profiles, ...Object.keys(c)])].sort().map((name) => ({ name, on_disk: profiles.includes(name), surface: lanes[name]?.surface ?? null, counts: c[name] ?? {} }));
       if (args.json) { say(args, '', data); return 0; }
       current().out(`${'NAME'.padEnd(20)}  ${'ON DISK'.padEnd(8)}  ${'LANE'.padEnd(9)} COUNTS\n${data.map((e) => `${e.name.padEnd(20)}  ${(e.on_disk ? 'yes' : 'no').padEnd(8)}  ${(e.surface ?? '-').padEnd(9)} ${Object.entries(e.counts).sort().map(([k, v]) => `${k}=${v}`).join(', ') || '(idle)'}`).join('\n')}\n`);
@@ -1063,16 +1106,24 @@ export async function runVerb(argv) {
       const reports = await plan({ root, lanes, settings });
       const out = { capacity: reports.capacity, would: reports.flatMap((r) => r.would.map((w) => w.id)), waiting: reports.flatMap((r) => r.queued.map(([id, why]) => ({ id, why }))) };
       if (args.json) { say(args, '', out); return 0; }
+      // each card as a person reads it, by the number its own board gave it
+      const shown = [...out.would, ...out.waiting.map((w) => w.id), ...out.capacity.flatMap((cap) => cap.groups.flatMap((g) => g.cards))];
+      const labels = new Map();
+      for (const board of listBoards(root)) {
+        const b = openBoard(root, board);
+        try { const own = boardKey(root, board); for (const [cardId, n] of view(b, (db) => engine.numbersOf(db, shown))) labels.set(cardId, engine.cardLabel(own, n, cardId)); } finally { b.close(); }
+      }
+      const label = (cardId) => labels.get(cardId) ?? cardId;
       const lines = [];
       for (const cap of out.capacity) {
         const filter = Object.entries(cap.where ?? {}).map(([k, v]) => `${k} ${[].concat(v).join('|')}`).join(', ');
         const except = Object.entries(cap.unless ?? {}).map(([k, v]) => `${k} ${[].concat(v).join('|')}`).join(', ');
         lines.push(`cap "${cap.name}": ${cap.counts} per ${cap.scope}${filter ? `, where ${filter}` : ''}${except ? `, unless ${except}` : ''}, max ${cap.max}`);
         if (!cap.groups.length) lines.push('    (nothing counted)');
-        for (const g of cap.groups) lines.push(`    ${cap.scope === 'global' ? 'home' : g.group ?? '(none)'}: ${g.count} of ${g.max ?? 'no max'}  ${[...new Set(g.cards)].join(' ')}`);
+        for (const g of cap.groups) lines.push(`    ${cap.scope === 'global' ? 'home' : g.group ?? '(none)'}: ${g.count} of ${g.max ?? 'no max'}  ${[...new Set(g.cards)].map(label).join(', ')}`);
       }
-      lines.push(out.would.length ? `would start: ${out.would.join(' ')}` : 'would start: nothing');
-      for (const w of out.waiting) lines.push(`${w.id}  ${w.why}`);
+      lines.push(out.would.length ? `would start: ${out.would.map(label).join(', ')}` : 'would start: nothing');
+      for (const w of out.waiting) lines.push(`${label(w.id)}  ${w.why}`);
       current().out(`${lines.join('\n')}\n`);
       return 0;
     }
@@ -1356,6 +1407,19 @@ function scrub(db) {
   }
 }
 
+// Only the transfer copy is lowered. Keep supercode_cards.paused (actor/reason)
+// and add Hermes's ordinary blocked event so its own tools can explain/unblock it.
+function lowerHermesHolds(db) {
+  const rows = db.prepare(`SELECT t.id,c.paused FROM tasks t LEFT JOIN supercode_cards c ON c.task_id=t.id
+    WHERE t.status = 'paused' OR (t.status NOT IN ('done','archived','cancelled') AND c.paused IS NOT NULL AND c.paused != 'null')`).all();
+  for (const row of rows) {
+    const pause = json(row.paused, {}) ?? {};
+    db.prepare("UPDATE tasks SET status='blocked',block_kind='needs_input' WHERE id=?").run(row.id);
+    db.prepare('INSERT INTO task_events(task_id,kind,payload,created_at) VALUES (?,?,?,?)').run(row.id, 'blocked',
+      JSON.stringify({ kind: 'needs_input', reason: pause.reason ?? 'Paused on the native board', by: pause.by ?? null, source: 'native_pause_export' }), now());
+  }
+}
+
 const rowCounts = (db) => Object.fromEntries(TABLES.map((t) => [t, Number(db.prepare(`SELECT COUNT(*) AS n FROM ${t}`).get().n)]));
 
 function copyTree(from, to) {
@@ -1375,12 +1439,15 @@ function exportBoard(root, slug, out, { attachments, logs }) {
   mkdirSync(base, { recursive: true });
   try {
     const b = openBoard(root, slug);
-    try { b.db.prepare('VACUUM INTO ?').run(join(base, 'kanban.db')); } finally { b.close(); }
+    try {
+      const path = join(base, 'kanban.db');
+      if (b.snapshot) b.snapshot(path); else b.db.prepare('VACUUM INTO ?').run(path);
+    } finally { b.close(); }
     const snap = openBoard(base, DEFAULT_BOARD);
     let counts;
-    try { tx(snap, (db) => scrub(db)); counts = rowCounts(snap.db); } finally { snap.close(); }
+    try { tx(snap, (db) => { scrub(db); lowerHermesHolds(db); }); counts = rowCounts(snap.db); } finally { snap.close(); }
     const { db_path: _, backing: ____, default_workdir: __, project_id: ___, ...meta } = boardMeta(root, slug);
-    writeFileSync(join(base, 'board.json'), `${JSON.stringify(meta, null, 2)}\n`);
+    writeFileSync(join(base, 'board.json'), `${JSON.stringify({ ...meta, key: boardKey(root, slug) }, null, 2)}\n`);
     const attachmentsDir = slug === DEFAULT_BOARD ? join(root, 'kanban', 'attachments') : join(boardDir(root, slug), 'attachments');
     const logsFrom = logsDir(root, slug);
     const files = attachments ? copyTree(attachmentsDir, join(base, 'attachments')) : 0;
@@ -1412,11 +1479,12 @@ function importBoard(root, archive, as) {
     const requested = normalSlug(as ?? manifest.board ?? tops[0]);
     let slug = requested === DEFAULT_BOARD ? `${requested}-imported` : requested;
     for (let n = 2; existsSync(boardDir(root, slug)); n += 1) slug = `${requested}-${n}`;
+    const staged = json(existsSync(join(extracted, 'board.json')) ? readFileSync(join(extracted, 'board.json'), 'utf8') : null, {}) ?? {};
+    boardKey(root, slug, { creating: true, key: staged.key ?? null });
     const dest = boardDir(root, slug);
     mkdirSync(dest, { recursive: true });
     renameSync(join(extracted, 'kanban.db'), join(dest, 'kanban.db'));
     for (const tree of ['attachments', 'logs']) if (existsSync(join(extracted, tree))) renameSync(join(extracted, tree), join(dest, tree));
-    const staged = json(existsSync(join(extracted, 'board.json')) ? readFileSync(join(extracted, 'board.json'), 'utf8') : null, {}) ?? {};
     const name = staged.name || manifest.board_name || slug;
     writeMeta(root, slug, { name, description: staged.description ?? '', icon: staged.icon ?? '', color: staged.color ?? '', archived: false });
     const warnings = [];
@@ -1511,7 +1579,8 @@ const READS = new Set(['list', 'ls', 'show', 'context', 'brief', 'runs', 'log',
 
 /** The main session of each agent the workflow names a manager (`sc:<machine>:agent:<name>`), asked of this machine's
  *  daemon, which keeps agents' records (mail step 1c), once per call before its verb runs: a manager named by its agent
- *  address is that agent's main session on the board. None for an agent the daemon does not know, or when it is down. */
+ *  address is that agent's main session on the board. Only a positive not-declared answer means no main; an unread
+ *  identity stops the call before authorization, rather than denying a role it could not establish. */
 async function readAgentMains(root) {
   // A lookup belongs to this call, including a refusal. A startup miss must not become the resident owner's
   // permanent answer, and a replacement main must revoke the old main's manager role on the next call.
@@ -1520,10 +1589,18 @@ async function readAgentMains(root) {
   for (const address of managers) {
     const name = /^sc:[^:\s]+:agent:([^:\s]+)$/.exec(address)?.[1];
     if (!name || agentMains.has(address)) continue;
-    let main = null;
-    try { main = (await machineCall(null, 'harness.v1.agent.show', { name, claim: { pid: process.pid, ppid: process.ppid, session: null, named: null, owner: null } }, { timeoutMs: 5_000 }))?.agents?.[0]?.main_session ?? null; }
-    catch { /* not known: the agent is no manager's session in this call */ }
-    agentMains.set(address, typeof main === 'string' && main ? main : null);
+    try {
+      const answer = await machineCall(null, 'harness.v1.agent.show', { name, records_only: true, claim: { pid: process.pid, ppid: process.ppid, session: null, named: null, owner: null } }, { timeoutMs: 5_000 });
+      // EXIT_UNKNOWN is the daemon's explicit answer that this named agent is not declared.
+      if (answer?.code === 3) { agentMains.set(address, null); continue; }
+      const agent = answer?.agents?.[0];
+      if (answer?.code !== 0 || answer.agents?.length !== 1 || agent?.name !== name ||
+          typeof agent.main_session !== 'string' || !/^sc:[^:\s]+:[^:\s]+:[^:\s]+$/.test(agent.main_session))
+        throw new Error(answer?.text ?? 'the daemon returned no valid named agent and main session');
+      agentMains.set(address, agent.main_session);
+    } catch (cause) {
+      throw Object.assign(new Error(`Could not read who the caller is: manager ${address} could not be looked up (${cause.message ?? cause}). No role decision was made.`, { cause }), { code: 'manager_identity_unavailable' });
+    }
   }
 }
 function agentMain(address) { return current().agentMains.get(address) ?? null; }