@volter/supercode-orchestrator 0.5.206 → 0.5.208

package/board/ztrack.mjs

@@ -1,3 +1,4 @@
+import { fillReadableIds, validateReadableId } from './readable-id.mjs';
 // The document is card state. One SQLite file beside it keeps the runtime tables the engine speaks
 // and an index of the document's card spans. ADR 0001 and 0003.
 // All markdown interpretation belongs to ztrack's public codec and kanban preset.
@@ -15,10 +16,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, boardKey, 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 +105,10 @@ 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: its key, its number), and a task line's
+// number (`- [ ] VO-2836 c3`); either written keyed, or with `#` as before a board read its numbers with a key.
+const NUMBER_MARK = /^The board has given card numbers up to (?:#|([A-Z][A-Z0-9]+)-)(\d+)\.[ \t]*$/m;
+const TASK_NUMBER = /^\s*[-*] \[[ xX]\]\s+(?:#|[A-Z][A-Z0-9]+-)(\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);
@@ -133,7 +138,7 @@ export function openZtrackBoard(marker, { create = false, document = null, decla
   }
   const config = JSON.parse(read(marker));
   const backing = new ZtrackBoard({ ...config, seed, marker, init, root, slug, held, readOnly });
-  return { db: backing.db, tx: (fn) => backing.tx(fn), publishPending: () => backing.git?.publishPending(), unimported: () => backing.unimported(), close: () => backing.close(), document: backing.path,
+  return { db: backing.db, snapshot: (path) => backing.snapshot(path), tx: (fn) => backing.tx(fn), publishPending: () => backing.git?.publishPending(), unimported: () => backing.unimported(), close: () => backing.close(), document: backing.path,
     documentsChanged: () => backing.documentsChanged(), documentsUnwatched: (unwatched) => { backing.unwatched = unwatched; }, saidOnOpen: () => backing.sayLate() };
 }
 
@@ -210,7 +215,7 @@ class ZtrackBoard {
     }
     // A board's first open in this process recovers what its store accepted and derives what git owes for it (tx), so
     // a board that is only read, or whose owner runs no round, still finishes an earlier process's commit.
-    if (seed || this.git?.underived) this.tx(() => {});
+    if (seed || this.git?.underived || this.get('rebuild_from_documents') || !this.get('task_identities_written') || !this.get('readable_ids_written')) this.tx(() => {});
   }
 
   // A listing's view, taken once at its open and kept until its close: the store's rows as of one read transaction, and
@@ -264,7 +269,7 @@ class ZtrackBoard {
   // state, so a rotation committed but not yet written is still a document of the board).
   get docs() {
     let rotated = [];
-    try { rotated = this.conn ? this.get('archives', []) : []; } catch { rotated = []; }
+    try { rotated = this.conn ? this.get('archives', []) : this.rebuildArchives ?? []; } catch { rotated = []; }
     // recorded by file name, beside the document, so a board moved with its documents still finds them
     return [...this.baseDocs, ...rotated.map(({ role, name }) => ({ role, path: resolve(dirname(this.path), name) }))];
   }
@@ -273,6 +278,14 @@ class ZtrackBoard {
   board() { return { root: this.root, slug: this.slug, label: this.slug, db: this.db }; }
   close() { this.closed = true; this.git?.release(); this.dropOverlay(); this.conn.close(); }
 
+  // Import pending document edits through the backing, then copy the committed
+  // projection outside its write wrapper: SQLite forbids VACUUM inside a tx.
+  snapshot(path) {
+    if (this.active || this.readOnly) throw new Error('board export needs a writable backing outside a transaction');
+    this.tx(() => {});
+    this.conn.prepare('VACUUM INTO ?').run(path);
+  }
+
   statement(sql) {
     let statement = this.statements.get(sql);
     if (!statement) {
@@ -348,6 +361,8 @@ class ZtrackBoard {
 
   // A board created from the previous runtime store imports its rows once; the old file stays as it was.
   create(legacy) {
+    const named = `${basename(this.path)}.archive-`;
+    this.rebuildArchives = existsSync(dirname(this.path)) ? readdirSync(dirname(this.path)).filter(name => name.startsWith(named) && name.endsWith('.md')).sort().map(name => ({ role: `archived:${name.slice(named.length, -3)}`, name })) : [];
     const tmp = `${this.file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
     const db = new DatabaseSync(tmp);
     try {
@@ -359,6 +374,13 @@ class ZtrackBoard {
         this.init(db, { fresh: true });
         db.exec(BOARD_TABLES);
         if (has('runtime_rows')) this.importRuntime(db, old, legacy);
+        // Runtime history is retained, but an old cache is never the current document state. Persist the recovery
+        // marker before installing the store so a crash/reopen also finishes this first full reconciliation.
+        db.prepare('INSERT OR REPLACE INTO board_state VALUES (?, ?)').run('archives', JSON.stringify(this.rebuildArchives));
+        if (!this.seed) {
+          db.prepare('INSERT OR REPLACE INTO board_state VALUES (?, ?)').run('rebuild_from_documents', 'true');
+          db.prepare('INSERT OR REPLACE INTO board_state VALUES (?, ?)').run('published', '{}');
+        }
       } finally { old?.close(); }
       db.close();
     } catch (error) {
@@ -440,6 +462,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');
   }
 
@@ -554,8 +583,26 @@ class ZtrackBoard {
         }
         if (this.seed) this.seedRows();
         timedStep('board tx snapshot', () => this.snapshotHeld());
+        fillReadableIds(this.db);
         const result = timedStep('board tx body', () => fn(this.db));
+        fillReadableIds(this.db);
         if (this.contended) throw RETRY;
+        // The first write made with a codec that renders keyed numbers (numbersRendered) once the store numbered its
+        // cards (store.mjs layOutNumbers) writes every card of the open document again, with its keyed number in its
+        // heading and each open subtask's on its task line, and again whenever the board's key changes (a renamed home);
+        // a card made since is written with its number when it is made. `numbers_written` is the key last written.
+        if (this.numbersRendered && (this.numberForm === 'keyed' ? this.get('numbers_written') !== this.cardKey : !this.get('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', this.numberForm === 'keyed' ? this.cardKey : true);
+        }
+        if (!this.get('readable_ids_written')) {
+          this.conn.exec('INSERT INTO temp.board_touched SELECT id FROM main.tasks');
+          this.put('readable_ids_written', true);
+        }
+        if (!this.get('task_identities_written')) {
+          this.conn.exec('INSERT INTO temp.board_touched SELECT DISTINCT subtask_of FROM main.supercode_cards WHERE subtask_of IS NOT NULL');
+          this.put('task_identities_written', true);
+        }
         const files = timedStep('board tx render', () => this.render());
         const intent = files.length ? randomBytes(16).toString('hex') : null;
         if (intent) {
@@ -658,7 +705,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 +746,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);
@@ -778,7 +827,7 @@ class ZtrackBoard {
   // while its card was not rendered, as under a recorded refusal): it takes the store's value, and the card's
   // render writes that back into its lines (t_f3f102db).
   checkControls(plan, resolveRef) {
-    if (!this.one('SELECT 1 FROM main.tasks LIMIT 1')) return;
+    if (this.get('rebuild_from_documents') || !this.one('SELECT 1 FROM main.tasks LIMIT 1')) return;
     let fields = [];
     try { fields = workflowFor(this.root).params.document_control_fields ?? []; } catch { /* no home policy */ }
     if (!fields.length) return;
@@ -837,9 +886,17 @@ class ZtrackBoard {
       this.dropOverlay();
       this.conn.exec('CREATE TEMP TABLE tasks AS SELECT * FROM main.tasks; CREATE TEMP TABLE supercode_cards AS SELECT * FROM main.supercode_cards; CREATE TEMP TABLE task_links AS SELECT * FROM main.task_links');
       this.conn.exec(TASK_SUMMARY_INDEX_SQL.replace(TASK_SUMMARY_INDEX, `temp.${TASK_SUMMARY_INDEX}`));
+      this.conn.exec("CREATE UNIQUE INDEX temp.supercode_open_readable_ids ON tasks(readable_id) WHERE status NOT IN ('done','cancelled','archived')");
       this.overlay = true; this.statements.clear();
     }
-    const initial = !overlay && !this.one('SELECT 1 FROM main.tasks LIMIT 1');
+    const rebuilding = !overlay && this.get('rebuild_from_documents');
+    const initial = !overlay && (rebuilding || !this.one('SELECT 1 FROM main.tasks LIMIT 1'));
+    if (rebuilding) {
+      if (plan.errors.size) throw new Error(`cannot rebuild board from invalid documents: ${[...plan.errors].map(([id, why]) => `${id}: ${why}`).join('; ')}`);
+      // The imported cache can predate cards added, edited or removed in the documents. Keep its history, not its
+      // obsolete card state. Every document was re-read, including unchanged archive spans.
+      for (const { id } of this.statement('SELECT id FROM main.tasks').all()) if (!plan.rows.has(id)) plan.remove.add(id);
+    }
     const by = 'document-editor';
     const events = [];
     const fingerprintOf = (id) => {
@@ -852,12 +909,24 @@ 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) {
+      if (rebuilding) this.conn.exec(`DELETE FROM ${CARD_NUMBERS}`);
+      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) ?? {};
       const oldState = this.one(`SELECT * FROM ${schema}.supercode_cards WHERE task_id = ?`, id) ?? {};
       this.replace(schema, 'tasks', { ...oldTask, ...rows.task }, 'id');
       this.replace(schema, 'supercode_cards', { ...oldState, ...rows.state }, 'task_id');
+      if (rebuilding && ENDED.has(rows.state.stage ?? rows.task.status) && oldTask.current_run_id) {
+        this.statement("UPDATE main.task_runs SET ended_at = COALESCE(ended_at, ?), status = 'reclaimed', outcome = COALESCE(outcome, 'reclaimed') WHERE id = ? AND ended_at IS NULL").run(now(), oldTask.current_run_id);
+        this.statement('UPDATE main.tasks SET current_run_id = NULL, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL WHERE id = ?').run(id);
+      }
       this.statement(`DELETE FROM ${schema}.task_links WHERE child_id = ?`).run(id);
       for (const b of json(rows.state.blocked_by, []).filter((b) => b.kind === 'card')) this.statement(`INSERT OR IGNORE INTO ${schema}.task_links (parent_id, child_id) VALUES (?, ?)`).run(b.id, id);
       const after = fingerprintOf(id);
@@ -868,7 +937,11 @@ class ZtrackBoard {
     }
     for (const id of plan.checked) this.errors.delete(id);
     for (const [id, reason] of plan.errors) this.errors.set(id, reason);
+    // A read overlays new document cards before the owner commits them. Give that
+    // connection-local view the same names as the subsequent write.
+    fillReadableIds(this.conn);
     if (overlay) return;
+    if (rebuilding) this.drop('rebuild_from_documents');
     for (const id of plan.errors.keys()) this.refused.add(this.one('SELECT subtask_of FROM main.supercode_cards WHERE task_id = ?', id)?.subtask_of ?? id);
     for (const [tid, { key, sources }] of plan.tasks) this.statement('INSERT OR REPLACE INTO main.board_tasks (id, key, sources) VALUES (?, ?, ?)').run(tid, key, sources?.length ? JSON.stringify(sources) : null);
     for (const id of [...plan.checked, ...plan.rows.keys()]) if (!plan.errors.has(id)) this.statement('DELETE FROM main.board_errors WHERE id = ?').run(id);
@@ -915,7 +988,7 @@ class ZtrackBoard {
     const workspace = /^(scratch|dir|worktree)(?::(.*))?$/.exec(card.workspace ?? 'scratch');
     const old = this.one('SELECT * FROM main.tasks WHERE id = ?', id) ?? {};
     const runtime = Object.fromEntries(Object.entries(old).filter(([k]) => RUNTIME.has(k) || RUN_OUTPUT.has(k)));
-    const task = { ...meta, ...runtime, id, title: card.title, body: stored.body,
+    const task = { ...meta, ...runtime, id, title: card.title, readable_id: meta.readable_id == null ? old.readable_id ?? null : validateReadableId(meta.readable_id), body: stored.body,
       status: card.status, assignee: card.assignee ?? null, created_at: meta.created_at ?? old.created_at ?? now(), priority: card.priority ?? 0,
       workspace_kind: workspace?.[1] ?? 'scratch', workspace_path: runtime.workspace_path ?? (/^(\/|~|[A-Za-z]:[\\/])/.test(workspace?.[2] ?? '') ? workspace[2] : null), branch_name: card.branch ?? null };
     const state = { task_id: id, workspace_anchor: workspace?.[2] ?? null, stage: card.status, machine: card.machine ?? null, subtask_of: parent,
@@ -924,28 +997,29 @@ class ZtrackBoard {
       // carried it (or edited without it) is not an unarchive. Saying `archived: false` of an archived card is.
       paused: card.paused ? JSON.stringify(card.paused) : null, every: card.every ?? null,
       archived: (meta.archived ?? card.archived) === undefined ? Number(this.one('SELECT archived FROM main.supercode_cards WHERE task_id = ?', id)?.archived ?? 0) : ((meta.archived ?? card.archived) ? 1 : 0) };
+    if (!state.archived && !ENDED.has(card.status)) task.status = card.paused ? 'paused' : card.relations?.length ? 'blocked' : card.status;
     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}`;
       const tid = task.metadata?.id ?? this.one('SELECT id FROM main.board_tasks WHERE key = ?', key)?.id ?? `t_${randomBytes(4).toString('hex')}`;
-      // A task line carries its brief and its tick; what else the subtask holds is the store's (an older document's
-      // `metadata:` line is still read).
-      const stored = task.metadata ? null : this.one('SELECT * FROM main.tasks WHERE id = ?', tid);
-      const storedState = task.metadata ? null : this.one('SELECT * FROM main.supercode_cards WHERE task_id = ?', tid);
+      // The native identity and declared state travel with the line. Runtime history stays in the store, joined by
+      // this same identity, including when that store was rebuilt from a cache older than the subtask.
+      const stored = this.one('SELECT * FROM main.tasks WHERE id = ?', tid);
+      const storedState = this.one('SELECT * FROM main.supercode_cards WHERE task_id = ?', tid);
       const was = task.metadata?.status ?? storedState?.stage ?? stored?.status;
-      const taskCard = { ...task.metadata?.card, ...(storedState ? { paused: json(storedState.paused, null) ?? undefined, every: storedState.every || undefined } : {}),
+      const taskCard = { ...(storedState ? { paused: json(storedState.paused, null) ?? undefined, every: storedState.every || undefined } : {}), ...task.metadata?.card,
         id: tid, title: `${task.id} ${task.text}`, body: task.metadata?.body ?? task.brief ?? '',
         status: task.status === 'passed' ? (was === 'cancelled' ? 'cancelled' : 'done') : (ENDED.has(was) ? 'todo' : was ?? 'todo'),
         metadata: task.metadata?.properties ?? Object.fromEntries(Object.entries(stored ?? {}).filter(([k, v]) => declared(k, v))),
-        assignee: task.metadata?.assignee ?? stored?.assignee ?? card.assignee,
-        machine: task.metadata?.machine ?? storedState?.machine ?? card.machine, acceptanceCriteria: [], acceptance: task.lines ?? [],
+        assignee: task.metadata && 'assignee' in task.metadata ? task.metadata.assignee : stored?.assignee ?? card.assignee,
+        machine: task.metadata && 'machine' in task.metadata ? 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 +1039,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 +1053,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 +1117,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';
@@ -1127,9 +1204,13 @@ class ZtrackBoard {
       const task = parse({ id: r.id, title: r.title, status, body: r.body ?? '' });
       const blocks = json(s.blocked_by, []);
       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,
+      // Keep the identity-to-number binding and declared state durable with its line; a stale runtime cache cannot
+      // supply these for a newer subtask. Run output, clocks and active claims remain the runtime store's.
+      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,
+        metadata: { id: r.id, status, assignee: r.assignee, machine: s.machine,
+          properties: Object.fromEntries(Object.entries(r).filter(([k, v]) => declared(k, v))),
+          card: { priority: r.priority ?? 0, workspace: r.workspace_kind + (r.workspace_kind !== 'scratch' && (s.workspace_anchor ?? r.workspace_path) ? `:${s.workspace_anchor ?? r.workspace_path}` : ''),
+            branch: r.branch_name || undefined, paused: json(s.paused, null) ?? undefined, every: s.every || undefined } },
         ...(task.body ? { brief: task.body } : {}), lines: task.acceptance,
         waitingOn: messages[0]?.id,
         blockedBy: blocks.filter((block) => block !== messages[0]).map((block) => {
@@ -1140,7 +1221,97 @@ 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 with its board's key (`## VO-42 t_… — …`): the store's (store.mjs
+  // layOutNumbers, boardKey). 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 number and key where the document codec reads them, 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, ...(this.numberForm === 'keyed' ? { key: this.cardKey } : {}) } : {};
+  }
+
+  /** The board's key (store.mjs boardKey). */
+  get cardKey() { return this._cardKey ??= boardKey(this.root, this.slug); }
+
+  // How the document codec (@volter/ztrack) writes a card's number in its heading and a subtask's on its task line:
+  // `keyed` (`VO-42`), `plain` (`#42`, a codec from before numbers were keyed), or null (none). One that writes none
+  // renders, reads and indexes cards as it always did; the open document is written with the numbers in the codec's form
+  // by the first write made with it (tx), whichever was installed first.
+  get numberForm() {
+    if (this._numberForm === undefined) {
+      const writes = (key, mark) => {
+        try {
+          const task = this.preset.serializeKanbanCard({ id: 't-00000000', title: 'number', summary: '', status: 'todo', body: '', acceptanceCriteria: [{ id: 'c1', number: 2, ...(key ? { key } : {}), status: 'pending', evidence: [], text: 'number' }] }).body;
+          return this.codec.renderBoardCard({ id: 't_00000000', number: 1, ...(key ? { key } : {}), title: 'number', status: 'todo', body: '' }, 2).startsWith(`## ${mark}1 t_00000000 `) && task.includes(`- [ ] ${mark}2 c1 number`);
+        } catch { return false; }
+      };
+      this._numberForm = writes('KB', 'KB-') ? 'keyed' : writes(null, '#') ? 'plain' : null;
+    }
+    return this._numberForm;
+  }
+  get numbersRendered() { return this.numberForm !== null; }
+
+  // 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 = ?)`);
+    const holder = db.prepare(`SELECT task_id FROM ${CARD_NUMBERS} WHERE number = ?`);
+    for (const [id, number] of numbers) {
+      const other = holder.get(number)?.task_id;
+      if (other && other !== id) throw new Error(`cannot rebuild card numbers: ${number} names both ${other} and ${id}`);
+      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)?.[2] ?? 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 keyed = this.numberForm === 'keyed';
+    const line = (top) => `The board has given card numbers up to ${keyed ? `${this.cardKey}-` : '#'}${top}.`;
+    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 && (keyed ? said[1] === this.cardKey : said[1] === undefined) && Number(said[2]) >= given) return null;
+      const next = said ? text.replace(NUMBER_MARK, line(Math.max(given, Number(said[2])))) : `${text.replace(/\n*$/, '')}\n\n${line(given)}\n\n`;
+      return { index: 0, entry: { cid: null, id: null, level: 0, len: next.length, rec: null, text: next } };
+    }
+    const text = `${line(given)}\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 +1321,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 +1347,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/codex-pane-resume.mjs

@@ -0,0 +1 @@
+export { projectCodexPaneResume } from '@volter/supercode-teams/codex-pane-resume';