@volter/supercode-orchestrator 0.5.206 → 0.5.207

package/board/cli.mjs

@@ -93,6 +93,8 @@ 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 (42 or #42): the short number the board gave it when it was made.
+
 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>
@@ -329,9 +331,9 @@ 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 line = (t) => `${ICONS[t.status] ?? '?'} ${engine.cardLabel(t.number, t.id).padEnd(16)}  ${(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,
+  id: t.id, number: 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,
@@ -366,6 +368,36 @@ const metadataOf = (v) => {
   return got;
 };
 
+// A card is named by its id or by its number (`42`, `#42`, store.mjs 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 is refused.
+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 = /^#?([1-9]\d*)$/;
+function resolveCardNumbers(verb, rest, args, withBoard) {
+  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;
+  withBoard((b) => view(b, (db) => {
+    for (const [holder, key] of numbered) {
+      const n = Number(CARD_NUMBER.exec(String(holder[key]))[1]);
+      const id = engine.cardByNumber(db, n);
+      if (!id) throw new Error(`no card #${n} on this board`);
+      holder[key] = 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 +422,7 @@ 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(); } };
+  resolveCardNumbers(verb, rest, args, withBoard);
   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 ?? [])];
@@ -546,7 +579,7 @@ export async function runVerb(argv) {
       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; }
       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(task.number, created.id)}  (${task.status}, assignee=${task.assignee || '-'})${said}${recipients.length ? `; notices go to ${recipients.join(', ')}` : ''}`, null);
       return answer.failed ? 1 : 0;
     }
 
@@ -612,14 +645,16 @@ export async function runVerb(argv) {
         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 });
         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 label = (cardId) => engine.cardLabel(labels.get(cardId), cardId);
+      const out = [`Task ${engine.cardLabel(t.number, 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 || '-'}`];
       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}`);
@@ -638,9 +673,9 @@ export async function runVerb(argv) {
       }
       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(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);
@@ -1063,16 +1098,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 { for (const [cardId, n] of view(b, (db) => engine.numbersOf(db, shown))) labels.set(cardId, engine.cardLabel(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;
     }

package/board/dispatch.mjs

@@ -51,7 +51,7 @@ import { doors, fire, loadWorkflow, resumeOf, runSpec, runWorkingSeconds, reques
 import { checkWorkspace, assertWorkspaceOwner, notePresence, resolveWorkspace } from './workspace.mjs';
 import { capacity, dispatched, executionHost, harnessDefaults, holdings } from './capacity.mjs';
 import { evaluate, holds, render } from './expr.mjs';
-import { identifyNotice } from './notices.mjs';
+import { identifyNotice, numbered } from './notices.mjs';
 import { noticeReceiptsInTurns, noticeKey, requireNoticeBasis, noticeWriterBasis } from './notice-receipts.mjs';
 import { pendingRequestMail } from './request-mail.mjs';
 import {
@@ -1800,7 +1800,9 @@ export async function sessionNotice(board, e) {
   }
   const address = e.address ?? addressOf(prior);
   if (!address) throw new Error('lifecycle notice awaits the owned launch session identity');
-  const filed = await fileMail(board, address, e.text, effectMessageKey(e));
+  const card = view(board, (db) => getTask(db, e.id));
+  const subject = numbered(card?.number, `${String(e.verb ?? 'run_changed').replaceAll('_', ' ')} · run ${e.runId} · event ${e.sourceEvent ?? 'none'} · ${card?.title || e.id}`);
+  const filed = await fileMail(board, address, e.text, effectMessageKey(e), { subject });
   tx(board, (db) => {
     const session = json(db.prepare('SELECT metadata FROM task_runs WHERE id = ?').get(e.runId)?.metadata, {})?.supercode;
     if (session?.lifecycle_notice_pending === e.durableId) setRunSession(db, e.runId, { lifecycle_notice_pending: null });
@@ -1819,7 +1821,8 @@ export async function sessionEffect(board, e) {
     const address = addressOf(session);
     if (!address) throw new Error('actor session identity unavailable');
     // filed in the actor's mailbox, which delivers it
-    const filed = await fileMail(board, address, e.text, effectMessageKey(e));
+    const card = view(board, (db) => getTask(db, e.id));
+    const filed = await fileMail(board, address, e.text, effectMessageKey(e), { subject: numbered(card?.number, `actor notice · run ${e.runId ?? 'none'} · ${card?.title || e.id}`) });
     if (filed.new) tx(board, db => event(db, e.id, 'actor_notice_filed', { notice: e.durableId, address, message_id: filed.message_id }, e.runId));
     return true;
   }
@@ -2862,7 +2865,7 @@ export async function fileBoardMail(board, report, taskId = null) {
     const first = mail.members[0];
     try {
       const task = view(board, db => getTask(db, first.task_id));
-      const subject = mail.requester ? `State requests · ${mail.members.length} request(s) · ${task?.title || first.task_id}` : `${task?.title || first.task_id} · ${mail.message_id ? 'Question' : 'Update'}`;
+      const subject = numbered(task?.number, mail.requester ? `State requests · ${mail.members.length} request(s) · ${task?.title || first.task_id}` : `${task?.title || first.task_id} · ${mail.message_id ? 'Question' : 'Update'}`);
       const filed = await fileMail(board, mail.to, mail.text, mail.message_id ?? `board-message-${first.id}`, { ask: Boolean(mail.message_id), subject });
       tx(board, db => {
         if (filed.detached) {
@@ -2893,7 +2896,7 @@ export function noticeOf(entry, audience, kind, task, payload, comment = null) {
   if (template === undefined || template === null) return null;
   const cut = (text, n) => String(text ?? '').slice(0, Number(n));
   const text = render(template, { card: task, event: payload ?? {}, comment, params: entry.params, cut });
-  return text.trim() ? text : null;
+  return text.trim() ? numbered(task?.number, text) : null;
 }
 
 /**
@@ -3067,7 +3070,7 @@ async function notify(board, fleet, report, entry) {
           if (Number(currentSub.last_event_id) >= ev.id) { cursor = Math.max(cursor, Number(currentSub.last_event_id)); continue; }
           const body = ['worker', 'dependency'].includes(role) ? identifyNotice(ev, text) : text;
           // filed under its fixed key: a second pass filing the same notice files nothing new
-          const filed = await fileMail(board, sub.chat_id, body, `board-${sub.task_id}-${ev.id}-${sub.chat_id.slice(-12)}`, { wake, subject: `${ev.kind.replaceAll('_', ' ')} · run ${ev.run_id ?? 'none'} · event ${ev.id} · ${task?.title || sub.task_id}`,
+          const filed = await fileMail(board, sub.chat_id, body, `board-${sub.task_id}-${ev.id}-${sub.chat_id.slice(-12)}`, { wake, subject: numbered(task?.number, `${ev.kind.replaceAll('_', ' ')} · run ${ev.run_id ?? 'none'} · event ${ev.id} · ${task?.title || sub.task_id}`),
             eligible: () => view(board, db => {
               const currentSub = db.prepare(`SELECT last_event_id FROM kanban_notify_subs ${where}`).get(...identity);
               return Boolean(currentSub) && Number(currentSub.last_event_id) < ev.id;

package/board/engine.mjs

@@ -15,7 +15,7 @@ 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, claimer, contention, event, json, newTaskId, now, retryContention, tx } from './store.mjs';
+import { view, actorOf, principalOf, 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';
@@ -38,11 +38,22 @@ 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.
+/** 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));
+
 export function getTask(db, id) {
   const row = one(db, 'SELECT * FROM tasks WHERE id = ?', id);
   if (!row) return null;
   const ours = one(db, 'SELECT * FROM supercode_cards WHERE task_id = ?', id);
-  return { ...row, workspace_anchor: ours?.workspace_anchor ?? null, 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,
+  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) };
 }
 
@@ -880,7 +891,7 @@ 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.*, 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
+  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) }));
@@ -892,7 +903,7 @@ export function showCard(db, id) {
     task,
     parents: parentsOf(db, id),
     children: childrenOf(db, id),
-    subtasks: all(db, 'SELECT t.id, t.status, t.title FROM tasks t JOIN supercode_cards c ON c.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 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),
     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) })),

package/board/files.mjs

@@ -11,6 +11,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { fenced } from './fence.mjs';
 import { markRemovedHeads } from './published.mjs';
+import { CARD_NUMBERS } from './store.mjs';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
@@ -98,6 +99,9 @@ class FilesBoard {
     const state = this.stateText === null ? null : JSON.parse(this.stateText);
     for (const sql of state?.schema ?? []) mem.exec(sql);
     this.init(mem, { fresh: !state?.schema?.length });
+    // the schema as the directory keeps it: a layout this load added (a table, a column, the card numbers) is written to
+    // every card's file by the next write (persist)
+    this.keptSchema = state?.schema ?? [];
     const columns = (table) => new Set(mem.prepare(`PRAGMA table_info(${quote(table)})`).all().map((c) => c.name));
     const insert = (table, rows) => {
       const have = columns(table);
@@ -108,17 +112,26 @@ class FilesBoard {
     };
     const previous = this.texts;
     this.texts = new Map();
+    const cards = [];
     for (const name of readdirSync(this.dir)) {
       if (!name.endsWith('.json') || name.startsWith('_')) continue;
       const text = readFileSync(join(this.dir, name), 'utf8');
       const card = JSON.parse(text);
       this.texts.set(card.id, text);
-      for (const [table, rows] of Object.entries(card.tables ?? {})) insert(table, rows);
+      cards.push(card);
     }
-    for (const [table, rows] of Object.entries(state?.tables ?? {})) insert(table, rows);
+    // The id counters first: a number handed out before stays handed out.
     for (const { name, seq } of state?.sequence ?? []) {
       if (mem.prepare('UPDATE sqlite_sequence SET seq = MAX(seq, ?) WHERE name = ?').run(seq, name).changes === 0) mem.prepare('INSERT INTO sqlite_sequence (name, seq) VALUES (?, ?)').run(name, seq);
     }
+    // Inserting a card's row numbers it when it has no number yet (store.mjs layOutNumbers): every number a card file
+    // holds loads first, so each card keeps its own and a new one is past them all, and then the cards load in the
+    // order they were made.
+    for (const card of cards) if (card.tables?.[CARD_NUMBERS]) insert(CARD_NUMBERS, card.tables[CARD_NUMBERS]);
+    const madeAt = (card) => Number(card.tables?.tasks?.[0]?.created_at ?? 0);
+    cards.sort((a, b) => madeAt(a) - madeAt(b) || (String(a.id) < String(b.id) ? -1 : String(a.id) > String(b.id) ? 1 : 0));
+    for (const card of cards) for (const [table, rows] of Object.entries(card.tables ?? {})) if (table !== CARD_NUMBERS) insert(table, rows);
+    for (const [table, rows] of Object.entries(state?.tables ?? {})) insert(table, rows);
     // Loading inserts every card, which marks every card changed (published.mjs). The first load of this projection keeps
     // those marks: its next write compares each card with its published head once (a named limit: each projection opened
     // compares every card once, as each load already reads every card's file). A reload keeps the marks not yet
@@ -172,7 +185,8 @@ class FilesBoard {
   /** Write the files of the cards the transaction touched, then `_board.json`; writes compare the content hash. */
   persist(schemaBefore) {
     const schema = this.schema();
-    const reshaped = schema.join('\n') !== schemaBefore.join('\n');
+    // reshaped by this transaction, or by the load it runs on (a layout the directory does not keep yet)
+    const reshaped = schema.join('\n') !== schemaBefore.join('\n') || schema.join('\n') !== (this.keptSchema ?? []).join('\n');
     const touched = new Set(this.mem.prepare('SELECT DISTINCT id FROM _touched').all().map((r) => r.id).filter((id) => id !== null));
     if (reshaped) this.watch(); // a table made in the transaction gets its triggers; every card is written again
     const keys = this.keys;

package/board/listing.mjs

@@ -68,11 +68,12 @@ export const LAST_BLOCK_SQL = `SELECT CASE WHEN kind = 'blocked' THEN payload EN
 
 export function listPageSql(detailed, tagCount = 0) {
   return `SELECT t.rowid AS list_order,${(detailed ? JSON_FIELDS : HUMAN_FIELDS).split(',').map(name => `t.${name}`).join(',')},
-    c.machine,c.stage${detailed ? ',c.subtask_of' : ''},
+    n.number,c.machine,c.stage${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 task_runs r ON r.id = t.current_run_id
+    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')
       AND (? IS NULL OR t.tenant = ?) AND (? IS NULL OR t.session_id = ?)

package/board/notices.mjs

@@ -1,3 +1,8 @@
+/** 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);
+/** 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;
+
 export function identifyNotice(event, text) {
   const time = new Date(Number(event.created_at) * 1000).toISOString();
   const kind = String(event.kind).replaceAll('_', ' ');

package/board/store.mjs

@@ -276,6 +276,34 @@ function layOutHistoryIndexes(db) {
   }
 }
 
+// A card's number (#42): short and sequential, given once when the card is made, never changed and never given to
+// another card, as an issue tracker numbers its issues. The store gives it, whoever makes the card (a verb, a document
+// import, Hermes's own writer): a trigger on `tasks` numbers each new card id. AUTOINCREMENT never hands a number out
+// twice, and a number stays with its card id while the card's row is replaced or removed. The trigger inserts only
+// where the id has no number yet, so no conflict arises in it (a writing statement's own conflict clause would govern
+// the trigger's insert: published.mjs). Its first installation numbers the cards already there, in the order they were
+// made (created_at, then id), in the same savepoint.
+export const CARD_NUMBERS = 'supercode_card_numbers';
+function layOutNumbers(db) {
+  if (db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'trigger' AND name = 'supercode_number_cards'").get()) return;
+  db.exec('SAVEPOINT supercode_card_numbering');
+  try {
+    db.exec(`CREATE TABLE IF NOT EXISTS ${CARD_NUMBERS} (number INTEGER PRIMARY KEY AUTOINCREMENT, task_id TEXT NOT NULL UNIQUE);
+      INSERT INTO ${CARD_NUMBERS} (task_id) SELECT id FROM tasks WHERE id NOT IN (SELECT task_id FROM ${CARD_NUMBERS}) ORDER BY created_at, id;
+      CREATE TRIGGER IF NOT EXISTS supercode_number_cards AFTER INSERT ON tasks BEGIN
+        INSERT INTO ${CARD_NUMBERS} (task_id) SELECT NEW.id WHERE NOT EXISTS (SELECT 1 FROM ${CARD_NUMBERS} WHERE task_id = NEW.id);
+      END;`);
+    db.exec('RELEASE supercode_card_numbering');
+  } catch (error) { db.exec('ROLLBACK TO supercode_card_numbering; RELEASE supercode_card_numbering'); throw error; }
+}
+
+/** Raise the numbers' high-water mark to the highest number held, and to `floor`: AUTOINCREMENT hands out only numbers
+ *  above it. For a store whose numbers were given or copied explicitly. */
+export function raiseCardNumbers(db, floor = 0) {
+  db.prepare(`INSERT INTO sqlite_sequence (name, seq) SELECT ?, 0 WHERE NOT EXISTS (SELECT 1 FROM sqlite_sequence WHERE name = ?)`).run(CARD_NUMBERS, CARD_NUMBERS);
+  db.prepare(`UPDATE sqlite_sequence SET seq = MAX(seq, ?, (SELECT COALESCE(MAX(number), 0) FROM ${CARD_NUMBERS})) WHERE name = ?`).run(Number(floor) || 0, CARD_NUMBERS);
+}
+
 /** Hermes's tables on a fresh board, supercode's own table and columns on every one. */
 export function layOut(db, { fresh }) {
   if (fresh) db.exec(SCHEMA);
@@ -287,6 +315,7 @@ export function layOut(db, { fresh }) {
   // each read walked every card's row. Laid out here, after the column it names exists on a store of any age and before
   // any statement is prepared; no statement names it, so a store without it is only slower.
   db.exec('CREATE INDEX IF NOT EXISTS idx_supercode_cards_subtask_of ON supercode_cards(subtask_of)');
+  layOutNumbers(db);
   layOutEventIndex(db);
   layOutHistoryIndexes(db);
   // A covering summary index keeps human listings out of task records' body overflow pages.

package/board/workflow.mjs

@@ -18,7 +18,7 @@ import { releaseAllSideSessions } from './side-sessions.mjs';
 import { evaluate, holds, render, needsSources } from './expr.mjs';
 import { completionEvidence, declaredWorkBranches, namedWorkBranch, reviewCandidate } from './ci.mjs';
 import { cardCommitsOn, isLocalWorkspace, isWorkspacePath } from './workspace.mjs';
-import { identifyNotice } from './notices.mjs';
+import { cardNumber, identifyNotice, numbered } from './notices.mjs';
 
 const loaded = new Map();
 // the owner's read door holds the workflow the owner reads (owner-door.mjs), told when it is read again
@@ -593,7 +593,7 @@ function queueTransitionNotice(db, board, entry, task, from, name, payload, befo
   const defaultNotice = noticeSession
     ? '{{card.id}}: verified adoption started run {{run.id}} ({{event.from}} → {{event.to}}). Follow the board’s current state before continuing.'
     : '{{card.id}}: {{event.verb}} changed run {{run.id}} ({{event.from}} → {{event.to}}). Stop work under the previous run; follow the board’s current state. {{event.reason ?? ""}}';
-  const body = render(entry.workflow.notify?.worker?.run_changed ?? defaultNotice, scope);
+  const body = numbered(cardNumber(db, task.id), render(entry.workflow.notify?.worker?.run_changed ?? defaultNotice, scope));
   const source = one(db, 'SELECT MAX(id) AS id FROM task_events WHERE task_id = ?', task.id)?.id;
   const text = identifyNotice({ id: source, kind: name, run_id: targetRun.id, created_at: now() }, body);
   const effect = { kind: 'session_notice', id: task.id, runId: targetRun.id, address, text, sourceEvent: source, verb: name, messageKey: `board-run-notice-${randomBytes(16).toString('hex')}` };
@@ -825,12 +825,14 @@ function dueAfter(db, workflow, task, status, scope) {
 
 /**
  * Where a new card starts: the first `initial` transition that holds (`event` is the create's own words), its status
- * set and its actions run (a goal card by the workflow's default, for one). Answers the status.
+ * set and its actions run (a goal card by the workflow's default, for one). Answers the status. A validator that fails
+ * refuses the create, as it refuses any other event (a home that keeps its root unassigned says so here).
  */
 export function startNew(db, board, entry, task, event) {
   const scope = scopeOf(db, board, task, { params: entry.params, event, extra: { lanes: lanesIn(entry) } });
   const t = entry.workflow.initial.find((x) => holds(x.guard ?? null, scope));
   if (!t?.target) throw new Error('the workflow says nowhere for a new card to start');
+  for (const v of t.validate ?? []) if (!holds(v.expr, scope)) throw new Error(render(v.message, scope));
   const status = String(templateValue(t.target, scope));
   if (!entry.workflow.statuses[status]) throw new Error(`the workflow starts a new card in ${status}, which it does not declare`);
   setStatus(db, entry.workflow, task.id, status);
@@ -1186,7 +1188,7 @@ const ACTIONS = {
   send_to_actor(ctx, text) {
     const effect = { kind: 'send_to_actor', id: ctx.id, runId: ctx.runId, text, messageKey: `board-actor-${randomBytes(16).toString('hex')}` };
     const inserted = run(ctx.db, 'INSERT INTO supercode_effects (effect) VALUES (?)', JSON.stringify(effect));
-    effect.text = identifyNotice({ id: `notice-${inserted.lastInsertRowid}`, kind: 'actor_notice', run_id: ctx.runId, created_at: now() }, text);
+    effect.text = identifyNotice({ id: `notice-${inserted.lastInsertRowid}`, kind: 'actor_notice', run_id: ctx.runId, created_at: now() }, numbered(cardNumber(ctx.db, ctx.id), text));
     run(ctx.db, 'UPDATE supercode_effects SET effect=? WHERE id=?', JSON.stringify(effect), Number(inserted.lastInsertRowid));
     ctx.effects.push({ ...effect, durableId: Number(inserted.lastInsertRowid) });
   },

package/board/ztrack.mjs

@@ -15,10 +15,10 @@ import { current } from './call.mjs';
 import { fenced } from './fence.mjs';
 import { createRequire } from 'node:module';
 import { createHash, randomBytes } from 'node:crypto';
-import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
-import { actorOf, contention, event, json, now, principalOf, storageFault, STORAGE_TRIES, unreadable } from './store.mjs';
+import { actorOf, CARD_NUMBERS, contention, raiseCardNumbers, event, json, now, principalOf, storageFault, STORAGE_TRIES, unreadable } from './store.mjs';
 import { GitDocument } from './git-document.mjs';
 import { unimported } from './legacy-store.mjs';
 import { noteStep, recordSlow } from '@volter/supercode-harness-sdk/slow-log';
@@ -104,6 +104,9 @@ const ARCHIVE_LINES = 2000;
 // document changed while it was read (readSnapshot).
 const SNAPSHOT_TRIES = 8;
 const isArchive = (role) => role === 'archived' || String(role ?? '').startsWith('archived:');
+// The open document's record of the numbers the board has given (numberMark), and a task line's number (`- [ ] #2836 c3`).
+const NUMBER_MARK = /^The board has given card numbers up to #(\d+)\.[ \t]*$/m;
+const TASK_NUMBER = /^\s*[-*] \[[ xX]\]\s+#(\d+)\s+[a-z]+\d+\s/gm;
 
 const BOARD_TABLES = `
 CREATE TABLE IF NOT EXISTS board_state (key TEXT PRIMARY KEY, value TEXT NOT NULL);
@@ -440,6 +443,13 @@ class ZtrackBoard {
       put(`chunks:${role}`, entries);
     }
     put('published', published);
+    // The earlier store held no numbers: its cards take the numbers their documents' headings give them, and the rest
+    // are numbered in the order they were made, after every number the documents name (documentNumbers).
+    db.exec(`DELETE FROM ${CARD_NUMBERS}; DELETE FROM sqlite_sequence WHERE name = '${CARD_NUMBERS}'`);
+    const named = this.documentNumbers();
+    this.numberFromHeadings([...named.headings].filter(([id]) => db.prepare('SELECT 1 FROM tasks WHERE id = ?').get(id)), db);
+    raiseCardNumbers(db, named.highest);
+    db.exec(`INSERT INTO ${CARD_NUMBERS} (task_id) SELECT id FROM tasks WHERE id NOT IN (SELECT task_id FROM ${CARD_NUMBERS}) ORDER BY created_at, id`);
     db.exec('COMMIT');
   }
 
@@ -556,6 +566,13 @@ class ZtrackBoard {
         timedStep('board tx snapshot', () => this.snapshotHeld());
         const result = timedStep('board tx body', () => fn(this.db));
         if (this.contended) throw RETRY;
+        // The first write made with a codec that renders numbers (numbersRendered) after the store numbered its cards
+        // (store.mjs layOutNumbers) writes every card of the open document again, with its number in its heading and each
+        // open subtask's on its task line; a card made since is written with its number when it is made.
+        if (this.numbersRendered && !this.stateText('numbers_written')) {
+          this.statement('INSERT INTO temp.board_touched SELECT value FROM json_each(?)').run(JSON.stringify(this.entries('open').filter((e) => e.id).map((e) => nativeId(e.id))));
+          this.put('numbers_written', true);
+        }
         const files = timedStep('board tx render', () => this.render());
         const intent = files.length ? randomBytes(16).toString('hex') : null;
         if (intent) {
@@ -658,7 +675,7 @@ class ZtrackBoard {
   // connection-local copies by a read. Only the spans the edit touched are parsed.
   // `held` names cards read again from their indexed span with no edit (see render).
   observe(stale, held = []) {
-    const plan = { layout: new Map(), dropped: [], published: {}, cards: new Map(), rows: new Map(), subtasks: new Map(), tasks: new Map(), remove: new Set(), errors: new Map(), checked: new Set(), before: new Map() };
+    const plan = { layout: new Map(), dropped: [], published: {}, cards: new Map(), numbers: new Map(), rows: new Map(), subtasks: new Map(), tasks: new Map(), remove: new Set(), errors: new Map(), checked: new Set(), before: new Map() };
     const changed = new Set();
     for (const doc of this.docs) {
       const entries = this.entries(doc.role);
@@ -699,11 +716,13 @@ class ZtrackBoard {
       catch (error) { plan.errors.set(id, error.message); continue; }
       entry.rec = hash(JSON.stringify(records[0]));
       plan.cards.set(id, card);
+      if (records[0].number) plan.numbers.set(id, records[0].number);
     }
     for (const [id, card] of plan.cards) {
       plan.rows.set(id, this.cardRows(id, card, null));
       const subtasks = [];
-      for (const [tid, taskCard, key, sources] of this.taskCards(id, card)) {
+      for (const [tid, taskCard, key, sources, number] of this.taskCards(id, card)) {
+        if (number) plan.numbers.set(tid, number);
         plan.rows.set(tid, this.cardRows(tid, taskCard, id));
         plan.tasks.set(tid, { key, sources });
         subtasks.push(tid);
@@ -852,6 +871,13 @@ class ZtrackBoard {
       this.statement(`DELETE FROM ${schema}.task_links WHERE child_id = ?`).run(id);
       if (!overlay) { this.statement('DELETE FROM main.board_tasks WHERE id = ?').run(id); if (!initial) events.push({ id, kind: 'removed', payload: { by, source: 'document' } }); }
     }
+    // A store made again from its documents (an empty one reading them whole) gives each card and subtask the number its
+    // heading or task line says, and hands out none at or below any number the documents name. Any other import keeps
+    // the store's numbers: a number typed into a heading or pasted with a section changes nothing.
+    if (initial) {
+      this.numberFromHeadings([...plan.numbers].filter(([id]) => plan.rows.has(id)));
+      raiseCardNumbers(this.conn, this.documentNumbers().highest);
+    }
     for (const [id, rows] of plan.rows) {
       const before = fingerprintOf(id);
       const oldTask = this.one(`SELECT * FROM ${schema}.tasks WHERE id = ?`, id) ?? {};
@@ -927,7 +953,7 @@ class ZtrackBoard {
     return { task, state };
   }
 
-  // A card's Tasks as subtask cards: [id, card, key, sources].
+  // A card's Tasks as subtask cards: [id, card, key, sources, the number its line gives].
   taskCards(id, card) {
     return card.acceptanceCriteria.map((task) => {
       const key = `${id}:${task.id}`;
@@ -945,7 +971,7 @@ class ZtrackBoard {
         machine: task.metadata?.machine ?? storedState?.machine ?? card.machine, acceptanceCriteria: [], acceptance: task.lines ?? [],
         relations: (task.blockedBy ?? []).map((b) => ({ type: 'blocked-by', issueId: b.ac && /^(?:[ma]-[0-9a-f]{6,}|t_[0-9a-f]+)$/.test(b.ac) ? b.ac : b.ac ? `${nativeId(b.issue)}:${b.ac}` : nativeId(b.issue) })) };
       if (task.waitingOn) taskCard.relations.push({ type: 'blocked-by', issueId: task.waitingOn });
-      return [tid, taskCard, key, task.sources];
+      return [tid, taskCard, key, task.sources, task.number];
     });
   }
 
@@ -965,7 +991,8 @@ class ZtrackBoard {
       return parents;
     };
     let parents = cardsTouched();
-    if (!parents.size) return [];
+    const mark = this.numbersRendered ? this.numberMark() : null;
+    if (!parents.size && !mark) return [];
     const heldBy = (id) => this.errors.has(id) || this.one('SELECT 1 FROM main.supercode_cards WHERE subtask_of = ? AND task_id IN (SELECT id FROM main.board_errors)', id);
     // A card held by a recorded refusal is not rendered, so the store's verbs move its tasks past its lines. When
     // the store moves it, its span is read again: what the store moved past is stale and takes the store's value
@@ -978,6 +1005,7 @@ class ZtrackBoard {
     const where = new Map();
     for (const role of roles) layout[role].forEach((entry, index) => { if (entry.id) where.set(nativeId(entry.id), { role, index, entry }); });
     const edits = Object.fromEntries(roles.map((role) => [role, []]));
+    if (mark) edits.open.push(mark);
     for (const id of parents) {
       if (heldBy(id)) continue;
       const task = this.one('SELECT * FROM main.tasks WHERE id = ?', id);
@@ -1041,7 +1069,8 @@ class ZtrackBoard {
         dropped.push(old.cid);
         if (edit.remove) entries.splice(edit.index, 1); else entries[edit.index] = edit.entry;
       }
-      for (const edit of edits[role].filter((e) => e.index === undefined)) {
+      for (const edit of edits[role].filter((e) => e.prepend)) { text = edit.entry.text + text; entries.unshift(edit.entry); }
+      for (const edit of edits[role].filter((e) => e.index === undefined && !e.prepend)) {
         if (text && !text.endsWith('\n\n')) {
           // the blank line before a new section belongs to the span above it
           const last = entries.at(-1), separator = text.endsWith('\n') ? '\n' : '\n\n';
@@ -1129,7 +1158,7 @@ class ZtrackBoard {
       const messages = blocks.filter((block) => block.kind === 'message');
       // A subtask is its line and its brief (its body, as Markdown under it); its id, status words, assignee and run
       // output stay in the store (company RFC 0025 decision 4).
-      card.acceptanceCriteria.push({ sources: json(stored?.sources, undefined) ?? undefined, id: key, status: ENDED.has(status) ? 'passed' : 'pending', evidence: [], text: match?.[2] ?? r.title,
+      card.acceptanceCriteria.push({ sources: json(stored?.sources, undefined) ?? undefined, id: key, ...this.numberOf(r.id), status: ENDED.has(status) ? 'passed' : 'pending', evidence: [], text: match?.[2] ?? r.title,
         ...(task.body ? { brief: task.body } : {}), lines: task.acceptance,
         waitingOn: messages[0]?.id,
         blockedBy: blocks.filter((block) => block !== messages[0]).map((block) => {
@@ -1140,7 +1169,82 @@ class ZtrackBoard {
         }) });
     }
     const serialized = this.preset.serializeKanbanCard(card);
-    return { id: card.id, title: card.title, status: card.status, ...(card.assignee ? { assignee: card.assignee } : {}), body: serialized.body };
+    return { id: card.id, ...this.numberOf(id), title: card.title, status: card.status, ...(card.assignee ? { assignee: card.assignee } : {}), body: serialized.body };
+  }
+
+  // A card's number, shown first in its heading (`## #42 t_… — …`): the store's (store.mjs layOutNumbers). An edit to a
+  // heading's number changes nothing; a store made again from its documents takes it back (numberFromHeadings). A card's
+  // record keeps the key where the document codec reads it, after the id.
+  numberOf(id) {
+    if (!this.numbersRendered) return {};
+    const number = this.one(`SELECT number FROM main.${CARD_NUMBERS} WHERE task_id = ?`, id)?.number;
+    return number ? { number } : {};
+  }
+
+  // Whether the document codec (@volter/ztrack) writes a card's number in its heading and a subtask's on its task
+  // line. One that does not renders, reads and indexes cards as it always did; the open document is written with the
+  // numbers by the first write made with one that does (tx), whichever was installed first.
+  get numbersRendered() {
+    if (this._numbersRendered === undefined) {
+      try {
+        const task = this.preset.serializeKanbanCard({ id: 't-00000000', title: 'number', summary: '', status: 'todo', body: '', acceptanceCriteria: [{ id: 'c1', number: 2, status: 'pending', evidence: [], text: 'number' }] }).body;
+        this._numbersRendered = this.codec.renderBoardCard({ id: 't_00000000', number: 1, title: 'number', status: 'todo', body: '' }, 2).startsWith('## #1 t_00000000 ') && task.includes('- [ ] #2 c1 number');
+      } catch { this._numbersRendered = false; }
+    }
+    return this._numbersRendered;
+  }
+
+  // Give each card the number its document gives it (its heading, or its task line), where no other card holds that
+  // number and the card has none yet; the numbers' high-water mark rises with them, so none is handed out again. Only
+  // for a store made again from its documents (applyPlan, importRuntime).
+  numberFromHeadings(numbers, db = this.conn) {
+    if (!numbers.length) return;
+    const give = db.prepare(`INSERT INTO ${CARD_NUMBERS} (number, task_id) SELECT ?, ? WHERE NOT EXISTS (SELECT 1 FROM ${CARD_NUMBERS} WHERE task_id = ? OR number = ?)`);
+    for (const [id, number] of numbers) give.run(number, id, id, number);
+    raiseCardNumbers(db);
+  }
+
+  // What the board's documents (the open one, the current archive and each rotated one beside it) say of numbers:
+  // `headings`, card id → the number its heading gives, and `highest`, the highest number any of them names (a
+  // heading, a task line, or the open document's record of the numbers given, numberMark).
+  documentNumbers() {
+    const headings = new Map();
+    let highest = 0;
+    const dir = dirname(this.path), named = basename(this.path);
+    let rotated = [];
+    try { rotated = readdirSync(dir).filter((name) => name.startsWith(`${named}.archive-`) && name.endsWith('.md')).map((name) => join(dir, name)); } catch { /* none */ }
+    for (const path of [this.path, this.archive, ...rotated]) {
+      const text = lf(read(path));
+      for (const line of text.matchAll(TASK_NUMBER)) highest = Math.max(highest, Number(line[1]));
+      if (path === this.path) highest = Math.max(highest, Number(NUMBER_MARK.exec(text)?.[1] ?? 0));
+      let records = [];
+      try { ({ records } = this.codec.inspectBoardDocument(text, path)); } catch { continue; }
+      for (const record of records) {
+        if (!record.number) continue;
+        highest = Math.max(highest, record.number);
+        if (!headings.has(nativeId(record.id))) headings.set(nativeId(record.id), record.number);
+      }
+    }
+    return { headings, highest };
+  }
+
+  // The open document records the highest number the store has given (a line of its preamble, NUMBER_MARK), so a store
+  // made again from the documents hands out none at or below it, whatever card held it: a subtask filed and gone, or
+  // a card the documents no longer show. The edit that brings the line up to the store's count, or null.
+  numberMark() {
+    const given = Number(this.one('SELECT seq FROM main.sqlite_sequence WHERE name = ?', CARD_NUMBERS)?.seq ?? 0);
+    if (!given) return null;
+    const line = `The board has given card numbers up to #${given}.`;
+    const first = this.entries('open')[0];
+    if (first && first.id === null) {
+      const text = this.texts([first])[0].text;
+      const said = NUMBER_MARK.exec(text);
+      if (said && Number(said[1]) >= given) return null;
+      const next = said ? text.replace(NUMBER_MARK, line) : `${text.replace(/\n*$/, '')}\n\n${line}\n\n`;
+      return { index: 0, entry: { cid: null, id: null, level: 0, len: next.length, rec: null, text: next } };
+    }
+    const text = `${line}\n\n`;
+    return { prepend: true, entry: { cid: null, id: null, level: 0, len: text.length, rec: null, text } };
   }
 
   // An ended subtask's own record in the archive document: its title and brief, and the card it belongs to.
@@ -1150,7 +1254,7 @@ class ZtrackBoard {
     const metadata = { subtask_of: fileId(parentId), ...Object.fromEntries(Object.entries(task).filter(([k, v]) => declared(k, v))) };
     const card = { ...parsed, metadata, machine: state.machine || undefined, relations: [] };
     const serialized = this.preset.serializeKanbanCard(card);
-    return { id: card.id, title: card.title, status: card.status, ...(card.assignee ? { assignee: card.assignee } : {}), body: serialized.body };
+    return { id: card.id, ...this.numberOf(id), title: card.title, status: card.status, ...(card.assignee ? { assignee: card.assignee } : {}), body: serialized.body };
   }
 
   // ------------------------------------------------------------------ migration from a SQLite board
@@ -1176,10 +1280,15 @@ class ZtrackBoard {
       if (keys.length) this.statement(`INSERT OR REPLACE INTO main.${quote(table)} (${keys.map(quote).join(',')}) VALUES (${keys.map(() => '?').join(',')})`).run(...keys.map((k) => row[k] ?? null));
     };
     for (const table of this.conn.prepare("SELECT name FROM main.sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE 'board_%'").all()) this.conn.exec(`DELETE FROM main.${quote(table.name)}`);
-    for (const table of source.db.prepare("SELECT name, sql FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all()) {
+    // a card's number is copied before its row, which keeps it; the numbers' high-water mark comes with them, so no
+    // number the old board handed out is handed out again
+    const sourceTables = source.db.prepare("SELECT name, sql FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all()
+      .sort((a, b) => Number(b.name === CARD_NUMBERS) - Number(a.name === CARD_NUMBERS));
+    for (const table of sourceTables) {
       if (!this.tables.has(table.name)) continue;
       for (const row of source.db.prepare(`SELECT * FROM ${quote(table.name)}`).all()) insert(table.name, row);
     }
+    raiseCardNumbers(this.conn, Number(source.db.prepare('SELECT seq FROM sqlite_sequence WHERE name = ?').get(CARD_NUMBERS)?.seq ?? 0));
     for (const task of this.conn.prepare('SELECT * FROM main.tasks').all()) {
       const old = this.one('SELECT * FROM main.supercode_cards WHERE task_id = ?', task.id) ?? {};
       if (old.subtask_of) { const key = /^([a-z]+\d+)\s/.exec(task.title)?.[1]; if (key) this.statement('INSERT OR REPLACE INTO main.board_tasks (id, key) VALUES (?, ?)').run(task.id, `${old.subtask_of}:${key}`); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.206",
+  "version": "0.5.207",
   "type": "module",
   "description": "The orchestrator runtime over the Volter Harness ontology: one typed operational model whose folder is its serialization, read and written through the harness orchestration doors (docs/ORCHESTRATOR-IR.md)",
   "exports": {
@@ -32,10 +32,10 @@
     "check-types": "node scripts/generate-types.mjs --check"
   },
   "dependencies": {
-    "@volter/supercode-teams": "^0.3.343",
-    "@volter/supercode-terminal": "^0.3.9",
-    "@volter/supercode-harness-sdk": "^0.3.103",
-    "@volter/teams": "0.2.95",
+    "@volter/supercode-teams": "^0.3.344",
+    "@volter/supercode-terminal": "^0.3.10",
+    "@volter/supercode-harness-sdk": "^0.3.104",
+    "@volter/teams": "0.2.96",
     "@volter/ztrack": "^2.4.23",
     "yaml": "^2.9.0"
   },