@volter/supercode-orchestrator 0.5.205 → 0.5.207

package/board/ztrack.mjs

@@ -7,14 +7,18 @@
 // triggers name the rows it touched. Only the cards whose text changed are rendered, and each is
 // spliced into the document at its indexed span. A document edited by hand is re-read only in the
 // region the edit touched. So a write costs what it changes, not the size of the board.
+//
+// A listing answered on the owner's read door (owner-door.mjs) opens the board read-only on a connection of its own and
+// reads it in one SQLite read transaction: WAL gives it the rows as one committed state, and no writer waits on it or
+// it on a writer. The documents are taken with that state (readSnapshot), never locked.
 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 } 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';
@@ -68,11 +72,13 @@ const timedStatement = (sql, fn) => {
   finally { noteStatement(sql, started, before); }
 };
 import { fire, workflowFor } from './workflow.mjs';
-import { LIST_REVISION, listRevision, TASK_SUMMARY_INDEX, TASK_SUMMARY_INDEX_SQL } from './listing.mjs';
+import { byOwner, LIST_REVISION, listRevision, TASK_SUMMARY_INDEX, TASK_SUMMARY_INDEX_SQL } from './listing.mjs';
 
 const require = createRequire(import.meta.url);
 const hash = (text) => createHash('sha256').update(text).digest('hex');
 const read = (path) => existsSync(path) ? readFileSync(path, 'utf8') : '';
+// What says a document changed: a write in place moves its size or times, a replacement its inode.
+const stampOf = (path) => { try { const s = statSync(path); return `${s.ino}:${s.size}:${s.mtimeMs}:${s.ctimeMs}`; } catch { return 'missing'; } };
 const lf = (text) => text.replace(/\r\n?/g, '\n');
 const quote = (s) => `"${String(s).replaceAll('"', '""')}"`;
 const nativeId = (id) => /^t-[a-f0-9]+$/.test(id) ? id.replace('t-', 't_') : id;
@@ -94,7 +100,13 @@ const sqliteContention = (error) => contention(error); // resolved at call time:
 const RETRY = new Error('board changed while this operation read it; retry');
 // The current archive's size before it rotates, unless the board declares its own (`archive.max_lines`).
 const ARCHIVE_LINES = 2000;
+// How many read transactions a listing begins before it leaves the board to its owner, each begun again only because a
+// 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);
@@ -109,7 +121,7 @@ DROP TABLE IF EXISTS board_export;`;
 // written to the document). board_tasks: a subtask's key on its arc's Tasks list
 // (`<arc>:c3`) and its `source:` lines, which live only in the document.
 
-export function openZtrackBoard(marker, { create = false, document = null, declared = null, seed = null, init, root, slug, held = false }) {
+export function openZtrackBoard(marker, { create = false, document = null, declared = null, seed = null, init, root, slug, held = false, readOnly = false }) {
   if (!existsSync(marker)) {
     if (!create) throw new Error(`no ztrack board ${marker}`);
     mkdirSync(dirname(marker), { recursive: true });
@@ -123,18 +135,20 @@ export function openZtrackBoard(marker, { create = false, document = null, decla
     atomic(marker, JSON.stringify({ format: 1, document: join(realpathSync(dirname(named)), basename(named)), ...said }) + '\n');
   }
   const config = JSON.parse(read(marker));
-  const backing = new ZtrackBoard({ ...config, seed, marker, init, root, slug, held });
+  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,
     documentsChanged: () => backing.documentsChanged(), documentsUnwatched: (unwatched) => { backing.unwatched = unwatched; }, saidOnOpen: () => backing.sayLate() };
 }
 
 
 class ZtrackBoard {
-  constructor({ document, seed, marker, init, root, slug, commit = false, manager = null, archive = {}, held = false }) {
+  constructor({ document, seed, marker, init, root, slug, commit = false, manager = null, archive = {}, held = false, readOnly = false }) {
     // held by the board owner (store.mjs holdBoards): opened once, its documents' stamps read again only when the
     // owner's watch says they changed or may have lost events (documentsChanged), and on every read while it keeps no
     // watch on them (unwatched); git's lateness held and refreshed on its own commits
     this.held = held; this.docsChanged = true; this.importDue = true; this.knownStamps = null;
+    // a listing's read-only view (readSnapshot): it makes, migrates, recovers, pulls and commits nothing
+    this.readOnly = readOnly;
     this.path = resolve(dirname(marker), document);
     this.archive = `${this.path}.archive.md`;
     this.baseDocs = [{ role: 'open', path: this.path }, { role: 'archived', path: this.archive }];
@@ -147,7 +161,7 @@ class ZtrackBoard {
     // `"manager"`: the board's manager (its principal or session address), whose writes it commits itself as part of its
     // own work; the backing commits only the writes the manager does not make.
     this.manager = manager;
-    this.git = commit ? new GitDocument(this.baseDocs.map((doc) => doc.path), (base, theirs, ours, path) => { try { return this.codec.mergeBoardDocument(base, theirs, ours, path)?.text ?? null; } catch { return null; } }) : null;
+    this.git = commit && !readOnly ? new GitDocument(this.baseDocs.map((doc) => doc.path), (base, theirs, ours, path) => { try { return this.codec.mergeBoardDocument(base, theirs, ours, path)?.text ?? null; } catch { return null; } }) : null;
     // what a fetch brought is written in the board's next transaction: one soon, on this loop, if none comes
     if (this.git) this.git.onTaken = () => setImmediate(() => { try { if (!this.closed) this.tx(() => {}); } catch (error) { current().err(`board: ${error.message}\n`); } });
     // A publish that is behind is said once per call, on whichever workflow verb opened the board: a refused push
@@ -158,18 +172,25 @@ class ZtrackBoard {
     else if (this.git) this.sayLate(timedStep('board open git behind', () => this.git.behind()));
     this.seed = seed; this.root = root; this.slug = slug; this.init = init;
     this.file = `${marker}.board.db`;
-    mkdirSync(dirname(this.path), { recursive: true });
+    // the store is the owner's to make, import and lay out: a listing that finds none leaves the board to it
+    if (readOnly && !(existsSync(this.file) && statSync(this.file).size > 0)) throw byOwner(`${this.file} is not laid out yet`);
+    if (!readOnly) mkdirSync(dirname(this.path), { recursive: true });
     const legacy = `${marker}.runtime.db`;
     // A 0-byte file is no store: a read through the sqlite3 CLI creates one at a path that has none (on 2026-10-01 a
     // `sqlite3 <store> "select …"` made the empty file the next release then opened instead of importing).
-    if (existsSync(this.file) && statSync(this.file).size === 0) unlinkSync(this.file);
+    if (!readOnly && existsSync(this.file) && statSync(this.file).size === 0) unlinkSync(this.file);
     if (!existsSync(this.file)) this.create(legacy);
-    this.conn = timedStep('board open connection', () => new DatabaseSync(this.file));
-    this.refuseUnimported(legacy);
+    this.conn = timedStep('board open connection', () => {
+      if (!readOnly) return new DatabaseSync(this.file);
+      try { return new DatabaseSync(this.file, { readOnly: true }); } catch (error) { throw unreadable(error) ? byOwner(error.message) : error; }
+    });
+    if (!readOnly) this.refuseUnimported(legacy);
     this.errors = new Map(); this.statements = new Map(); this.hashes = new Map();
     this.active = false; this.overlay = false; this.seen = null; this.refused = new Set();
-    timedStep('board open schema', () => this.prepareConnection());
-    timedStep('board open errors', () => this.loadErrors());
+    if (!readOnly) {
+      timedStep('board open schema', () => this.prepareConnection());
+      timedStep('board open errors', () => this.loadErrors());
+    }
     const self = this;
     this.db = {
       [LIST_REVISION]: () => self.read(() => listRevision(self.conn)),
@@ -185,10 +206,49 @@ class ZtrackBoard {
       exec(sql) { const run = () => timedStatement(sql, () => self.conn.exec(sql)); return self.active ? self.noting(run) : self.tx(run); },
       close() { self.close(); },
     };
+    if (readOnly) {
+      try { timedStep('board read: snapshot', () => this.readSnapshot()); }
+      catch (error) { this.conn.close(); throw error; }
+      return;
+    }
     // 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(() => {});
   }
+
+  // A listing's view, taken once at its open and kept until its close: the store's rows as of one read transaction, and
+  // every document as it stood when that transaction began. A document is written only after the transaction that
+  // published it committed, so a document that stood unchanged from before the transaction began until after it was
+  // read is one the transaction already describes: its published text, the text a pending publication replaces (the
+  // rows stay authoritative), or a hand edit, which is shown through connection-local copies of the card tables as
+  // every reader shows one. A document that changed in between is read again with a new transaction. Nothing here waits:
+  // WAL serves the read transaction beside any writer, and no busy timeout is set. A store not in WAL or not laid out,
+  // one a read-only connection cannot begin reading (store.mjs unreadable) or documents that keep changing leave the
+  // listing to the owner.
+  readSnapshot() {
+    const contended = (fn) => { try { return fn(); } catch (error) { throw unreadable(error) ? byOwner(error.message) : error; } };
+    if (String(contended(() => this.conn.prepare('PRAGMA journal_mode').get())?.journal_mode).toLowerCase() !== 'wal') throw byOwner(`${this.file} is not in WAL mode`);
+    for (let attempt = 0; attempt < SNAPSHOT_TRIES; attempt++) {
+      const stamps = () => this.docs.map((doc) => `${doc.path}\0${stampOf(doc.path)}`).join('\n');
+      const before = contended(stamps);
+      this.conn.exec('BEGIN');
+      let stale;
+      try {
+        // the transaction's first read begins its snapshot
+        if (!contended(() => this.one("SELECT 1 FROM main.sqlite_master WHERE type = 'index' AND name = ?", TASK_SUMMARY_INDEX))) throw byOwner(`${this.file} is not laid out yet`);
+        this.loadErrors();
+        stale = this.staleDocuments({ pending: true });
+        if (stamps() !== before) { this.conn.exec('ROLLBACK'); this.hashes.clear(); continue; }
+      } catch (error) { try { this.conn.exec('ROLLBACK'); } catch { /* not begun */ } throw error; }
+      if (!stale.length) return;
+      this.tables = this.shapes();
+      let plan;
+      try { plan = this.observe(stale); } catch { return; } // the next write reports it
+      this.applyPlan(plan, { overlay: true });
+      return;
+    }
+    throw byOwner('its documents changed during every read');
+  }
   /** The publish's lateness, said once per call (a held board's from its held reading, never by asking git). */
   sayLate(late = this.git?.lateness ?? null) {
     const said = current().said;
@@ -246,14 +306,9 @@ class ZtrackBoard {
     // What a transaction touched, for the renderer (cards whose text may change: anything beyond run fields and scheduling clocks). Plain inserts: a trigger's
     // own conflict clause yields to the outer statement's, so duplicates are removed when read.
     this.conn.exec('CREATE TEMP TABLE IF NOT EXISTS board_dirty (name TEXT NOT NULL, key TEXT NOT NULL); CREATE TEMP TABLE IF NOT EXISTS board_touched (id TEXT)');
-    this.tables = new Map();
-    const names = this.conn.prepare("SELECT name FROM main.sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE 'board_%'").all().map((row) => row.name);
+    this.tables = this.shapes();
     const trigger = (name, when, body) => this.conn.exec(`CREATE TEMP TRIGGER IF NOT EXISTS ${quote(name)} ${when} BEGIN ${body} END`);
-    for (const name of names) {
-      const columns = this.conn.prepare(`PRAGMA main.table_info(${quote(name)})`).all();
-      const keys = columns.filter((c) => c.pk).sort((a, b) => a.pk - b.pk).map((c) => c.name);
-      if (!keys.length) keys.push('rowid');
-      this.tables.set(name, { name, keys, columns: columns.map((c) => c.name) });
+    for (const { name, keys } of this.tables.values()) {
       const key = (row) => `json_array(${keys.map((k) => `${row}.${quote(k)}`).join(',')})`;
       const mark = (row) => `INSERT INTO board_dirty VALUES ('${name}', ${key(row)});`;
       trigger(`board_i_${name}`, `AFTER INSERT ON main.${quote(name)}`, mark('NEW'));
@@ -268,6 +323,18 @@ class ZtrackBoard {
     }
   }
 
+  // Each runtime table's columns and key, as the store has them.
+  shapes() {
+    const tables = new Map();
+    for (const { name } of this.conn.prepare("SELECT name FROM main.sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE 'board_%'").all()) {
+      const columns = this.conn.prepare(`PRAGMA main.table_info(${quote(name)})`).all();
+      const keys = columns.filter((c) => c.pk).sort((a, b) => a.pk - b.pk).map((c) => c.name);
+      if (!keys.length) keys.push('rowid');
+      tables.set(name, { name, keys, columns: columns.map((c) => c.name) });
+    }
+    return tables;
+  }
+
   // A store holding fewer runs than the earlier store beside it was made without the one-time import (on 2026-10-01
   // one such store, created by an opener nobody named, sent the dispatcher on to start a second session on every
   // running card). The board refuses it, so nothing runs on a board without its history.
@@ -376,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');
   }
 
@@ -388,6 +462,8 @@ class ZtrackBoard {
   }
 
   read(fn) {
+    // a listing's view is its snapshot's (readSnapshot): its statements read that, never the documents again
+    if (this.readOnly) return fn();
     if (this.active) return this.noting(fn);
     this.observeForRead();
     for (let attempt = 0; ; attempt++) {
@@ -397,8 +473,7 @@ class ZtrackBoard {
   }
 
   fileHash(path) {
-    let stamp;
-    try { const s = statSync(path); stamp = `${s.ino}:${s.size}:${s.mtimeMs}:${s.ctimeMs}`; } catch { stamp = 'missing'; }
+    const stamp = stampOf(path);
     const known = this.hashes.get(path);
     if (known?.stamp === stamp) return known;
     const raw = read(path);
@@ -462,6 +537,7 @@ class ZtrackBoard {
   // ------------------------------------------------------------------ writes
 
   tx(fn) {
+    if (this.readOnly) throw new Error('a listing reads the board and writes nothing');
     // A write inside a write is part of it: the pull below happened once, for the outermost one.
     if (this.active) return fn(this.db);
     // A pull request merged on the remote (a page edited in Git Notes) is in the document before this write reads it.
@@ -490,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) {
@@ -592,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);
@@ -633,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);
@@ -786,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) ?? {};
@@ -861,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}`;
@@ -879,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];
     });
   }
 
@@ -899,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
@@ -912,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);
@@ -975,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';
@@ -1063,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) => {
@@ -1074,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.
@@ -1084,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
@@ -1110,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/board-input.d.ts

@@ -0,0 +1,2 @@
+/** Read a remote card write's selected text file (or stdin) on the caller's machine. */
+export function prepareBoardText(argv: string[]): { argv: string[]; stdin: string | null };

package/board-input.mjs

@@ -0,0 +1,16 @@
+// A remote card write reads its text on the caller's machine, before the board door is called.
+// The board's own argument parser decides which file is used; its last value wins.
+import { readFileSync } from 'node:fs';
+import { parse } from './board/args.mjs';
+
+/** Carry a comment/create/specify text input as the owner's existing `stdin` field. */
+export function prepareBoardText(argv) {
+  const args = parse(argv);
+  const verb = args._[0];
+  const key = verb === 'comment' ? 'file' : ['create', 'specify'].includes(verb) ? 'body-file' : null;
+  const file = key === null || args.help ? undefined : args[key];
+  if (file === undefined) return { argv, stdin: null };
+  // Appending the selected flag preserves every other argument and overrides earlier occurrences. The owner
+  // reads the carried text at `-`, never an unrelated file at the caller's original path on another machine.
+  return { argv: [...argv, `--${key}`, '-'], stdin: readFileSync(file === '-' ? 0 : file, 'utf8') };
+}