@volter/supercode-orchestrator 0.5.207 → 0.5.208

package/board/published.mjs

@@ -1,3 +1,4 @@
+import { readFileSync } from 'node:fs';
 // The card writer commits the changed cards' snapshots and a retained delivery obligation together (ADR 0003: a write is
 // proportional to the cards it changed; ADR 0008: a source change and its publication are one transaction).
 //
@@ -6,6 +7,8 @@
 // publishes the marked cards and clears their marks; one that marked nothing reads one row and publishes nothing.
 import { createHash, randomUUID } from 'node:crypto';
 import { executionOf } from './session-work.mjs';
+import { cardState } from './card-state.mjs';
+import { workflowFor } from './workflow.mjs';
 import { cardAgentScopeTransition } from '../agents.mjs';
 export const PUBLICATION_SCHEMA = `
 CREATE TABLE IF NOT EXISTS supercode_publications (
@@ -28,13 +31,22 @@ CREATE TABLE IF NOT EXISTS supercode_card_agent_scopes (
 -- keyless: a writing statement's own conflict clause (an upsert, OR REPLACE, OR ABORT) governs its triggers' inserts
 -- too, so a key here would fail the writer's statement; readers take the distinct ids
 CREATE TABLE IF NOT EXISTS supercode_publication_dirty (task_id TEXT NOT NULL);
+-- the snapshot shape the live heads were published in (SNAPSHOT_SHAPE): a newer shape republishes every card once
+CREATE TABLE IF NOT EXISTS supercode_publication_shape (version INTEGER NOT NULL);
 CREATE INDEX IF NOT EXISTS supercode_publication_dirty_task ON supercode_publication_dirty(task_id);
 CREATE INDEX IF NOT EXISTS supercode_publication_heads_sequence ON supercode_publication_heads(sequence);`;
+// Columns the publication tables gained after their first layout; store.mjs layOut adds each one a store lacks. A head's
+// fingerprint is the cheap reading of its card's rows the head was last compared at (fingerprintOf); the log's prune_from
+// is where a prune under way resumes, null when none is (prunePublications).
+export const PUBLICATION_COLUMNS = { supercode_publication_heads: { fingerprint: 'TEXT' }, supercode_publication_log: { prune_from: 'INTEGER' } };
 
+// The snapshot's shape: 1 names the card as a person does (`ref`, VO-856).
+const SNAPSHOT_SHAPE = 4;
+const SNAPSHOT_RELEASE = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 const REVIEW_KIND_LIST = ['review_requested', 'approved', 'review_approved', 'changes_requested', 'escalated'];
 export const AGENT_KIND_LIST = ['agent_declared', 'agent_assignment_ended', 'agent_assignment_reassigned', 'agent_assignment_adopted'];
 // The tables a card's snapshot reads (cardSnapshot), each with the column naming its card; a link names two.
-const MARKED = [['tasks', ['id']], ['supercode_cards', ['task_id']], ['task_comments', ['task_id']], ['task_runs', ['task_id']], ['task_links', ['parent_id', 'child_id']], ['task_events', ['task_id']], ['supercode_card_agent_facts',['task_id']], ['supercode_card_agent_scopes',['task_id']]];
+const MARKED = [['tasks', ['id']], ['supercode_cards', ['task_id']], ['task_comments', ['task_id']], ['task_runs', ['task_id']], ['task_links', ['parent_id', 'child_id']], ['task_events', ['task_id']], ['supercode_card_agent_facts',['task_id']], ['supercode_card_agent_scopes',['task_id']], ['supercode_card_numbers', ['task_id']]];
 /**
  * The triggers that mark a changed card, on a store that has these tables (CREATE … IF NOT EXISTS: laid out on every
  * open). A card already marked is not marked again, so a writer's many writes while the owner is away leave one mark.
@@ -47,23 +59,31 @@ export function publicationTriggers(db) {
   const snapshotEvents = `(${[...REVIEW_KIND_LIST,...AGENT_KIND_LIST].map((kind) => `'${kind}'`).join(',')})`;
   const agentMigration = tables.has('task_events') && !db.prepare("SELECT sql FROM sqlite_master WHERE type='trigger' AND name='supercode_publish_task_events_insert'").get()?.sql.includes("'agent_assignment_adopted'");
   const scopeMigration = !db.prepare("SELECT 1 FROM sqlite_master WHERE type='trigger' AND name='supercode_publish_supercode_card_agent_scopes_insert'").get();
+  // A snapshot names its card's number: a store that numbers its cards republishes every card once, when that is watched.
+  const numberMigration = tables.has('supercode_card_numbers') && !db.prepare("SELECT 1 FROM sqlite_master WHERE type='trigger' AND name='supercode_publish_supercode_card_numbers_insert'").get();
+  // A snapshot of a newer shape (SNAPSHOT_SHAPE) than the heads were published in: every card is published once again.
+  const shapeMigration = Number(db.prepare('SELECT max(version) AS version FROM supercode_publication_shape').get()?.version ?? 0) < SNAPSHOT_SHAPE;
+  const contentMigration = !db.prepare("SELECT sql FROM sqlite_master WHERE type='trigger' AND name='supercode_publish_task_comments_update'").get()?.sql.includes('fingerprint=NULL');
   db.exec('SAVEPOINT supercode_publication_marking');
   try {
     // Existing event triggers only watched reviews. Replace that filter once, preserving the savepoint rollback.
+    if(contentMigration)for(const table of ['task_comments','task_events'])for(const verb of ['insert','update','delete'])db.exec(`DROP TRIGGER IF EXISTS supercode_publish_${table}_${verb}`);
     if(agentMigration)for(const verb of ['insert','update','delete'])db.exec(`DROP TRIGGER IF EXISTS supercode_publish_task_events_${verb}`);
     for (const [table, columns] of MARKED) {
       if (!tables.has(table)) continue;
       // Reviews and agent assignment events change a snapshot: an update marks when the
       // row was one before or is one after
       const when = (rows) => table === 'task_events' ? ` WHEN ${rows.map((row) => `${row}.kind IN ${snapshotEvents}`).join(' OR ')}` : '';
-      const mark = (row) => columns.map((column) => `INSERT INTO supercode_publication_dirty (task_id) SELECT ${row}.${column} WHERE ${row}.${column} IS NOT NULL AND NOT EXISTS (SELECT 1 FROM supercode_publication_dirty WHERE task_id = ${row}.${column});`).join(' ');
+      const invalidate = row => ['task_comments','task_events'].includes(table) ? `UPDATE supercode_publication_heads SET fingerprint=NULL WHERE resource_id=${row}.task_id;` : '';
+      const mark = (row) => invalidate(row) + columns.map((column) => `INSERT INTO supercode_publication_dirty (task_id) SELECT ${row}.${column} WHERE ${row}.${column} IS NOT NULL AND NOT EXISTS (SELECT 1 FROM supercode_publication_dirty WHERE task_id = ${row}.${column});`).join(' ');
       db.exec(`CREATE TRIGGER IF NOT EXISTS supercode_publish_${table}_insert AFTER INSERT ON ${table}${when(['NEW'])} BEGIN ${mark('NEW')} END;
         CREATE TRIGGER IF NOT EXISTS supercode_publish_${table}_update AFTER UPDATE ON ${table}${when(['OLD', 'NEW'])} BEGIN ${mark('NEW')} ${mark('OLD')} END;
         CREATE TRIGGER IF NOT EXISTS supercode_publish_${table}_delete AFTER DELETE ON ${table}${when(['OLD'])} BEGIN ${mark('OLD')} END;`);
     }
-    if ((first || agentMigration || scopeMigration) && tables.has('tasks')) db.exec(`INSERT INTO supercode_publication_dirty (task_id)
+    if ((first || contentMigration || agentMigration || scopeMigration || numberMigration || shapeMigration) && tables.has('tasks')) db.exec(`INSERT INTO supercode_publication_dirty (task_id)
       SELECT id FROM tasks UNION SELECT resource_id FROM supercode_publication_heads WHERE digest != 'removed'
       EXCEPT SELECT task_id FROM supercode_publication_dirty`);
+    if (shapeMigration) { db.exec('DELETE FROM supercode_publication_shape'); db.prepare('INSERT INTO supercode_publication_shape (version) VALUES (?)').run(SNAPSHOT_SHAPE); }
     db.exec('RELEASE supercode_publication_marking');
   } catch (error) { db.exec('ROLLBACK TO supercode_publication_marking; RELEASE supercode_publication_marking'); throw error; }
 }
@@ -75,9 +95,13 @@ export function markRemovedHeads(db) {
     SELECT resource_id FROM supercode_publication_heads WHERE digest != 'removed' AND resource_id NOT IN (SELECT id FROM tasks)
     EXCEPT SELECT task_id FROM supercode_publication_dirty`);
 }
-// Every card's head stays; older changes beyond this many are pruned in one batch once twice as many accumulate.
+// Every card's head stays; older changes beyond this many are pruned once twice as many accumulate.
 // A reader whose cursor falls below the pruned floor takes a new snapshot.
 const RETAINED_CHANGES = 1024;
+// The changes one prune transaction deletes: a change's snapshot averaged about 190 KB and reached 3.7 MB, and deleting
+// every pruned change in one statement held the owner's event loop for 291 s (2026-10-21).
+const PRUNE_BATCH = 200;
+const PRUNE_BYTES = 8 * 1024 * 1024;
 const hash = value => createHash('sha256').update(value).digest('hex');
 const parse = (value,fallback=null) => {try{return JSON.parse(value)??fallback;}catch{return fallback;}};
 const at = value => value == null ? null : new Date(Number(value)*1000).toISOString();
@@ -160,17 +184,51 @@ export function syncCardAgentScope(db,id,transition){
 /** Organization scope stays internal; the publication contract has exactly these five fields. */
 export function cardAgents(db,id){return cardAgentFacts(db,id).map(({org,...agent})=>agent);}
 /** A card's rows read one card at a time. */
-const perCard=db=>({
+const perCard=db=>{
+  // A card's short sequential number (store.mjs CARD_NUMBERS, named here as store.mjs imports this module), in a store
+  // that has numbered its cards.
+  const numbered=!!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='supercode_card_numbers'").get();
+  return {
+  number:id=>numbered?db.prepare('SELECT number FROM supercode_card_numbers WHERE task_id=?').get(id)?.number??null:null,
   own:id=>db.prepare('SELECT * FROM supercode_cards WHERE task_id=?').get(id),
   comments:id=>db.prepare('SELECT id,author,body,created_at FROM task_comments WHERE task_id=? ORDER BY id').all(id),
+  archiveReason:id=>parse(db.prepare("SELECT payload FROM task_events WHERE task_id=? AND kind='archived' ORDER BY id DESC LIMIT 1").get(id)?.payload,{}).reason??null,
   reviews:id=>db.prepare(`SELECT id,kind,payload,created_at FROM task_events WHERE task_id=? AND kind IN ${REVIEW_KINDS} ORDER BY id`).all(id),
   agents:id=>cardAgents(db,id),
   attempts:id=>db.prepare('SELECT id,profile,step_key,status,started_at,ended_at,outcome,summary,metadata,error FROM task_runs WHERE task_id=? ORDER BY id').all(id),
   parents:id=>db.prepare('SELECT parent_id FROM task_links WHERE child_id=? ORDER BY parent_id').all(id).map(link=>link.parent_id),
   children:id=>db.prepare('SELECT child_id FROM task_links WHERE parent_id=? ORDER BY child_id').all(id).map(link=>link.child_id),
+  };
+};
+// The columns of a task row that change while its card runs and that no snapshot reads (cardSnapshot).
+const UNREAD_TASK_COLUMNS = new Set(['claim_lock','claim_expires','worker_pid','last_heartbeat_at']);
+// The events a snapshot reads: its reviews, its agents and its archive reason.
+const SNAPSHOT_EVENT_KINDS = `(${[...REVIEW_KIND_LIST,...AGENT_KIND_LIST,'archived'].map((kind) => `'${kind}'`).join(',')})`;
+const fingerprintReads=db=>({
+  // comments and events are only ever added or removed by supercode's writers; their bytes catch a document edit that
+  // rewrites one in place; SQLite answers octet_length from a row's header, without reading its text
+  comments:db.prepare('SELECT count(*) AS n,max(id) AS last,total(octet_length(body)) AS bytes FROM task_comments WHERE task_id=?'),
+  events:db.prepare(`SELECT count(*) AS n,max(id) AS last,total(octet_length(payload)) AS bytes FROM task_events WHERE task_id=? AND kind IN ${SNAPSHOT_EVENT_KINDS}`),
+  facts:db.prepare('SELECT facts_json,receipt_sequence,declared_event_id FROM supercode_card_agent_facts WHERE task_id=?'),
+  scope:db.prepare('SELECT from_org,org,changed_at FROM supercode_card_agent_scopes WHERE task_id=?'),
+  // a run's metadata changes in place (its session's observations), so every run's snapshot columns are read whole
+  runs:db.prepare('SELECT id,profile,step_key,status,started_at,ended_at,outcome,summary,metadata,error FROM task_runs WHERE task_id=? ORDER BY id'),
 });
-export function cardSnapshot(db,row,rows=perCard(db)) {
-  const own=rows.own(row.id)??{};
+/**
+ * A card's fingerprint: what its snapshot is built from, read cheaply (no comment text, review or agent event payloads,
+ * and no snapshot built), with the snapshot's shape, its board's key and the options it is built with. Equal
+ * fingerprints build equal snapshots, but for a run's session observation passing its freshness (executionOf), which a
+ * snapshot's readers apply themselves.
+ */
+function fingerprintOf(reads,rows,row,key,options){
+  const task={};for(const [column,value] of Object.entries(row))if(!UNREAD_TASK_COLUMNS.has(column))task[column]=value;
+  return hash(JSON.stringify([SNAPSHOT_SHAPE,SNAPSHOT_RELEASE,key,Boolean(options.nativeHolds),task,rows.own(row.id)??null,rows.number(row.id),rows.parents(row.id),rows.children(row.id),
+    reads.comments.get(row.id),reads.events.get(row.id),reads.facts.get(row.id)??null,reads.scope.get(row.id)??null,reads.runs.all(row.id)]));
+}
+/** A card's snapshot; `key` is its board's key (store.mjs boardKey), with which `ref` names the card as a person does
+ *  (`VO-856`, store.mjs cardRef), null for a card with no number. */
+export function cardSnapshot(db,row,rows=perCard(db),key=null,options={}) {
+  const own=rows.own(row.id)??{},number=rows.number(row.id);
   const comments=rows.comments(row.id).map(comment=>({...comment,created_at:at(comment.created_at)}));
   const verdicts={review_requested:'requested',approved:'approved',review_approved:'approved',changes_requested:'changes_requested',escalated:'escalated'};
   const reviews=rows.reviews(row.id).map(event=>{const payload=parse(event.payload,{});return {id:event.id,verdict:verdicts[event.kind],by:payload.reviewer??payload.by??payload.profile,reason:payload.reason,at:at(event.created_at)};});
@@ -182,10 +240,11 @@ export function cardSnapshot(db,row,rows=perCard(db)) {
     return {id:String(run.id),profile:run.profile,step:run.step_key,status:run.status,started_at:at(run.started_at),ended_at:at(run.ended_at),outcome:run.outcome,error:run.error,execution:executionOf(run),session,handoff:run.summary||Object.keys(metadata).length?{summary:run.summary,metadata}:null};
   });
   const lane=own.stage??row.status;
-  return {id:row.id,title:row.title,body:row.body??'',assignee:row.assignee,status:taskStatusOf(lane,row.completed_at),lane,
+  const archived=Boolean(own.archived || lane==='archived');
+  return {id:row.id,readable_id:row.readable_id??null,number,ref:key&&number?`${key}-${number}`:null,title:row.title,body:row.body??'',assignee:row.assignee,status:taskStatusOf(lane,row.completed_at),board_status:cardState({...row,stage:lane,paused:own.paused,blocked_by:own.blocked_by},options).status,lane,
     execution:executionOf(runs.find(run=>run.id===row.current_run_id)),
     priority:row.priority,created_by:row.created_by,created_at:at(row.created_at),started_at:at(row.started_at),completed_at:at(row.completed_at),result:row.result,skills:parse(row.skills,[]),model:row.model_override,provider:row.provider_override,
-    tags:parse(own.tags,null)??(row.tenant?[row.tenant]:[]),sponsor:own.sponsor??null,sponsor_evidence:parse(own.sponsor_evidence),requested_by_unverified:parse(own.requested_by_unverified),machine:own.machine??null,subtask_of:own.subtask_of??null,archived:!!own.archived,
+    tags:parse(own.tags,null)??(row.tenant?[row.tenant]:[]),requested_by_unverified:parse(own.requested_by_unverified),machine:own.machine??null,subtask_of:own.subtask_of??null,archived,archive_reason:archived?rows.archiveReason(row.id):null,
     blocked_by:parse(own.blocked_by,[]),paused:parse(own.paused),detached:parse(own.detached),every:own.every??null,
     workspace:{kind:row.workspace_kind,path:row.workspace_path,branch:row.branch_name,root:own.workspace_root,anchor:own.workspace_anchor},
     parents:rows.parents(row.id),
@@ -195,60 +254,88 @@ export function cardSnapshot(db,row,rows=perCard(db)) {
 /**
  * Publish the cards this transaction (or a native writer before it) marked changed, inside the backing's own
  * transaction: each marked card's snapshot when it differs from its published head, a removal when the card is gone.
- * The marks are cleared with it. Retention is the owner's (prunePublications), never a transaction's.
+ * A marked card whose fingerprint is the one its head was last compared at builds no snapshot: a write that marks a card
+ * without changing what its snapshot reads (a run's heartbeat, a rewrite of the same values) costs the fingerprint's
+ * reads. The head keeps the fingerprint with the digest it was compared against, so a head another release moved is
+ * compared again. The marks are cleared with it. Retention is the owner's (prunePublications), never a transaction's.
  */
-export function recordCardPublications(db,actor,root) {
+export function recordCardPublications(db,actor,root,key) {
+  const options={nativeHolds:Boolean(workflowFor(root,{optional:true})?.workflow.flags?.paused)};
   const marked=db.prepare('SELECT DISTINCT task_id FROM supercode_publication_dirty').all().map(row=>row.task_id);
   if(!marked.length)return 0;
   db.prepare('INSERT INTO supercode_publication_log(id,pruned_through) SELECT ?,0 WHERE NOT EXISTS (SELECT 1 FROM supercode_publication_log)').run(`log_${randomUUID()}`);
-  const rows=perCard(db),task=db.prepare('SELECT * FROM tasks WHERE id=?'),head=db.prepare('SELECT resource_id,digest,last_event_id FROM supercode_publication_heads WHERE resource_id=?');
+  const rows=perCard(db),reads=fingerprintReads(db),task=db.prepare('SELECT * FROM tasks WHERE id=?'),head=db.prepare('SELECT resource_id,digest,last_event_id,fingerprint FROM supercode_publication_heads WHERE resource_id=?');
   const lastEvent=db.prepare('SELECT id,kind FROM task_events WHERE task_id=? ORDER BY id DESC LIMIT 1');
   const insert=db.prepare('INSERT INTO supercode_publications(id,resource_id,kind,snapshot,actor,created_at) VALUES (?,?,?,?,?,?)');
-  const upsert=db.prepare('INSERT INTO supercode_publication_heads(resource_id,digest,sequence,last_event_id) VALUES (?,?,?,?) ON CONFLICT(resource_id) DO UPDATE SET digest=excluded.digest,sequence=excluded.sequence,last_event_id=excluded.last_event_id');
+  const upsert=db.prepare('INSERT INTO supercode_publication_heads(resource_id,digest,sequence,last_event_id,fingerprint) VALUES (?,?,?,?,?) ON CONFLICT(resource_id) DO UPDATE SET digest=excluded.digest,sequence=excluded.sequence,last_event_id=excluded.last_event_id,fingerprint=excluded.fingerprint');
+  const compared=db.prepare('UPDATE supercode_publication_heads SET fingerprint=? WHERE resource_id=?');
   let changed=0;
   for(const id of marked){
     const row=task.get(id),previous=head.get(id);
     if(row){
       const transition=cardAgentScopeTransition(root,id);
       if(transition)syncCardAgentScope(db,id,transition);else compactCardAgentEvents(db,id);
-      const snapshot=JSON.stringify(cardSnapshot(db,row,rows)),digest=hash(snapshot);
-      if(previous?.digest===digest)continue;
+      const fingerprint=fingerprintOf(reads,rows,row,key,options);
+      if(previous&&previous.digest!=='removed'&&previous.fingerprint===`${fingerprint}:${previous.digest}`)continue;
+      const snapshot=JSON.stringify(cardSnapshot(db,row,rows,key,options)),digest=hash(snapshot);
+      if(previous?.digest===digest){compared.run(`${fingerprint}:${digest}`,id);continue;}
       const last=lastEvent.get(id);
       const kind=`task.${previous&&previous.digest!=='removed'?(last?.id!==previous.last_event_id?kinds[last?.kind]??'changed':'changed'):'created'}`;
       const inserted=insert.run(`event_${randomUUID()}`,id,kind,snapshot,actor,Date.now());
-      upsert.run(id,digest,Number(inserted.lastInsertRowid),last?.id??null);changed++;
+      upsert.run(id,digest,Number(inserted.lastInsertRowid),last?.id??null,`${fingerprint}:${digest}`);changed++;
     }else if(previous&&previous.digest!=='removed'){
       const inserted=insert.run(`event_${randomUUID()}`,id,'task.changed',JSON.stringify({id,removed:true}),actor,Date.now());
-      db.prepare('UPDATE supercode_publication_heads SET digest=?,sequence=? WHERE resource_id=?').run('removed',Number(inserted.lastInsertRowid),id);changed++;
+      db.prepare('UPDATE supercode_publication_heads SET digest=?,sequence=?,fingerprint=NULL WHERE resource_id=?').run('removed',Number(inserted.lastInsertRowid),id);changed++;
     }
   }
   db.prepare('DELETE FROM supercode_publication_dirty').run();
   return changed;
 }
 
-/**
- * Bounded retention, the publication owner's maintenance (never a write's): every card's head stays, and once more than
- * twice RETAINED_CHANGES older changes accumulate, all but the newest RETAINED_CHANGES of them go in one batch, the
- * floor recording where. A reader whose cursor is below the floor takes a new snapshot. Answers the changes removed.
- */
-/** Whether retention has work: an upper bound on the older changes kept (sequences above the floor that are no card's
- *  head), from the log's ends and the heads above the floor, in indexed reads. */
+// An older change: one no card's head is (the heads' sequence index answers it per change).
+const OLDER='NOT EXISTS (SELECT 1 FROM supercode_publication_heads h WHERE h.sequence=p.sequence)';
+/** Whether retention has work: a prune under way, or an upper bound on the older changes kept (sequences above the floor
+ *  that are no card's head), from the log's ends and the heads above the floor, in indexed reads. */
 export function pruneDue(db) {
-  const log=db.prepare('SELECT pruned_through FROM supercode_publication_log').get();
+  const log=db.prepare('SELECT pruned_through,prune_from FROM supercode_publication_log').get();
   if(!log)return false;
+  if(log.prune_from!=null)return true;
   const high=Number(db.prepare('SELECT MAX(sequence) AS n FROM supercode_publications').get()?.n??0);
   // the heads above the floor are not older changes; those below it were already left out by subtracting the floor
   const heads=Number(db.prepare('SELECT count(*) AS n FROM supercode_publication_heads WHERE sequence>?').get(Number(log.pruned_through)).n);
   return high-Number(log.pruned_through)-heads>2*RETAINED_CHANGES;
 }
 
+/**
+ * Bounded retention, the publication owner's maintenance (never a write's): every card's head stays, and once more than
+ * twice RETAINED_CHANGES older changes accumulate, all but the newest RETAINED_CHANGES of them go. A prune's first
+ * transaction raises the floor to the newest change it removes, so from then a reader whose cursor is below the floor
+ * takes a new snapshot and never reads the older changes still held; each transaction (this one and every later call)
+ * deletes at most PRUNE_BATCH of them, oldest first, recording where the next resumes (prune_from), and the last clears
+ * it. The owner runs one transaction per wake while pruneDue answers true. Answers the changes removed.
+ */
 export function prunePublications(db) {
   if(!pruneDue(db))return 0;
-  const history=Number(db.prepare('SELECT count(*) AS n FROM supercode_publications WHERE sequence NOT IN (SELECT sequence FROM supercode_publication_heads)').get().n);
-  if(history<=2*RETAINED_CHANGES)return 0;
-  const cut=Number(db.prepare('SELECT sequence FROM supercode_publications WHERE sequence NOT IN (SELECT sequence FROM supercode_publication_heads) ORDER BY sequence DESC LIMIT 1 OFFSET ?').get(RETAINED_CHANGES).sequence);
-  const old='SELECT id FROM supercode_publications WHERE sequence<=? AND sequence NOT IN (SELECT sequence FROM supercode_publication_heads)';
-  const removed=db.prepare(`DELETE FROM supercode_publications WHERE id IN (${old})`).run(cut).changes;
-  db.prepare('UPDATE supercode_publication_log SET pruned_through=MAX(pruned_through,?)').run(cut);
-  return Number(removed);
+  const log=db.prepare('SELECT pruned_through,prune_from FROM supercode_publication_log').get();
+  let from=log.prune_from==null?null:Number(log.prune_from);
+  if(from==null){
+    const older=db.prepare(`SELECT sequence FROM supercode_publications p WHERE ${OLDER} ORDER BY sequence DESC LIMIT 1 OFFSET ?`);
+    if(!older.get(2*RETAINED_CHANGES))return 0;
+    const cut=Number(older.get(RETAINED_CHANGES).sequence);
+    db.prepare('UPDATE supercode_publication_log SET pruned_through=MAX(pruned_through,?)').run(cut);
+    from=0;
+  }
+  const floor=Number(db.prepare('SELECT pruned_through FROM supercode_publication_log').get().pruned_through);
+  const candidates=db.prepare(`SELECT sequence,octet_length(snapshot) AS bytes FROM supercode_publications p WHERE sequence>? AND sequence<=? AND ${OLDER} ORDER BY sequence LIMIT ?`).all(from,floor,PRUNE_BATCH);
+  const batch=[];let bytes=0;
+  for(const row of candidates){
+    // A single oversized row still makes progress, in a transaction of its own.
+    if(batch.length&&bytes+Number(row.bytes)>PRUNE_BYTES)break;
+    batch.push(Number(row.sequence));bytes+=Number(row.bytes);
+    if(bytes>=PRUNE_BYTES)break;
+  }
+  const remove=db.prepare('DELETE FROM supercode_publications WHERE sequence=?');
+  for(const sequence of batch)remove.run(sequence);
+  db.prepare('UPDATE supercode_publication_log SET prune_from=?').run(candidates.length<PRUNE_BATCH&&batch.length===candidates.length?null:batch.at(-1));
+  return batch.length;
 }

package/board/readable-id.mjs

@@ -0,0 +1,34 @@
+// A mutable name for people, separate from the immutable t_* identity and sequential number.
+export function validateReadableId(value) {
+  if (typeof value !== 'string' || value.length > 32 || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(value)) {
+    throw new Error('readable_id is kebab-case, starts with a letter and has at most 32 characters');
+  }
+  return value;
+}
+
+export function readableIdFromTitle(title) {
+  const text = String(title).replace(/^(?:\[[^\]]+\]\s*)+/, '');
+  const named = /^([a-z][a-z0-9]*(?:-[a-z0-9]+)*)\s*:/.exec(text)?.[1];
+  const words = (named ?? text).normalize('NFKD').replace(/[\u0300-\u036f]/g, '').toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return (words.replace(/^[^a-z]+/, '') || 'card').slice(0, 32).replace(/-+$/, '');
+}
+
+export function allocateReadableId(db, title, requested = null, except = '') {
+  const base = requested == null ? readableIdFromTitle(title) : validateReadableId(requested);
+  const occupied = value => db.prepare("SELECT id FROM tasks WHERE readable_id=? AND id<>? AND status NOT IN ('done','cancelled','archived') LIMIT 1").get(value, except);
+  if (requested != null && occupied(base)) throw new Error(`readable_id ${base} belongs to another open card`);
+  let value = base;
+  for (let n = 2; occupied(value); n++) {
+    const suffix = `-${n}`;
+    value = `${base.slice(0, 32 - suffix.length).replace(/-+$/, '')}${suffix}`;
+  }
+  return value;
+}
+
+// Runs inside the backing's transaction, after native/document imports and before publication/rendering.
+export function fillReadableIds(db) {
+  const missing = db.prepare('SELECT id,title FROM tasks WHERE readable_id IS NULL ORDER BY created_at,id').all();
+  for (const card of missing) db.prepare('UPDATE tasks SET readable_id=? WHERE id=?')
+    .run(allocateReadableId(db, card.title, null, card.id), card.id);
+}

package/board/record-view.mjs

@@ -1,5 +1,7 @@
 // Resident local consumer of the daemon's committed record rows. Disconnects
 // preserve the last applied cursor, but held data is stale until caught up.
+import { jsonObjectReader } from '@volter/teams/lines';
+
 export class RecordView {
   constructor(open, { progressMs = 10_000 } = {}) {
     this.open = open; this.records = {}; this.positions = new Map();
@@ -27,9 +29,16 @@ export class RecordView {
     if (this.stream) return Promise.resolve();
     return this.opening ??= Promise.resolve().then(() => this.open({ after: this.cursor })).then((stream) => {
       this.stream = stream; this.ready = false; this.heardAt = Date.now();
+      const readObject = jsonObjectReader();
       stream.on('data', (frame) => {
         if (this.stream !== stream) return;
-        try { this.apply(frame); }
+        try {
+          const value = readObject(frame);
+          if (frame.json_part !== undefined) {
+            this.ready = false; this.heardAt = Date.now(); this.watchProgress();
+          }
+          if (value) this.apply(value);
+        }
         catch (error) { this.fail(error); stream.close(error.message); }
       });
       stream.on('receive-progress', ({ bytes, type }) => {

package/board/request-mail.mjs

@@ -43,14 +43,20 @@ export function pendingRequestMail(db, taskId = null) {
       nextAt = Math.min(nextAt, due * 1000);
       continue;
     }
+    // A batch of questions (state requests) is answered under its first id; a batch of tells (the board's own news, such
+    // as review waits only an act clears) is one mail listing each card's line, with nothing to answer.
     const envelope = {
       to: first.mail.to,
       message_id: first.mail.message_id,
       requester: first.mail.batch.requester,
+      title: first.mail.batch.title ?? null,
       members: group.map(row => ({ id: row.id, task_id: row.task_id, message_id: row.mail.message_id })),
-      text: `State requests from ${first.mail.batch.requester}: ${group.length} request(s) for ${new Set(group.map(row => row.task_id)).size} card(s).\n\n` +
-        group.map(row => `${row.task_id} [${row.mail.message_id}]\n${row.mail.text}`).join('\n\n---\n\n') +
-        `\n\nAnswer with reply_to ${first.mail.message_id}.`,
+      text: first.mail.message_id
+        ? `State requests from ${first.mail.batch.requester}: ${group.length} request(s) for ${new Set(group.map(row => row.task_id)).size} card(s).\n\n` +
+          group.map(row => `${row.task_id} [${row.mail.message_id}]\n${row.mail.text}`).join('\n\n---\n\n') +
+          `\n\nAnswer with reply_to ${first.mail.message_id}.`
+        : `${first.mail.batch.title ?? first.mail.batch.requester}: ${new Set(group.map(row => row.task_id)).size} card(s).\n\n` +
+          group.map(row => row.mail.text).join('\n\n'),
     };
     event(db, first.task_id, 'board_message_batch', envelope);
     ready.push(envelope);

package/board/store.mjs

@@ -13,8 +13,9 @@ import { current } from './call.mjs';
 import { fenced } from './fence.mjs';
 import { noteStep } from '@volter/supercode-harness-sdk/slow-log';
 import { redactValue } from '@volter/teams/redact';
+import { boardLabel } from '@volter/teams/board-name';
 import { randomBytes } from 'node:crypto';
-import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync, writeSync } from 'node:fs';
+import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, realpathSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { dirname, join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
@@ -22,7 +23,9 @@ import { openZtrackBoard } from './ztrack.mjs';
 import { byOwner, LIST_CONNECTION, TASK_SUMMARY_INDEX, TASK_SUMMARY_INDEX_SQL } from './listing.mjs';
 import { isFilesBoard, openFilesBoard } from './files.mjs';
 import { signalBoardWrite } from './wake.mjs';
-import { PUBLICATION_SCHEMA, pruneDue, prunePublications, publicationTriggers, recordCardPublications } from './published.mjs';
+import { PUBLICATION_COLUMNS, PUBLICATION_SCHEMA, pruneDue, prunePublications, publicationTriggers, recordCardPublications } from './published.mjs';
+
+import { fillReadableIds } from './readable-id.mjs';
 
 export const DEFAULT_BOARD = 'default';
 
@@ -87,11 +90,11 @@ CREATE TABLE IF NOT EXISTS supercode_session_operations (
 );`;
 // `stage`: the card's workflow status where kanban.db stores another (a `reviewing` card is `running` to Hermes)
 // `since`: when the card entered its workflow status; `after_fired`: which of the status's `after` moves have run since
-// `tags`: the card's ordered tags (Hermes's `tenant` holds the first); `sponsor`, `sponsor_evidence`, `requested_by_unverified`: C4
+// `tags`: the card's ordered tags (Hermes's `tenant` holds the first); `requested_by_unverified`: C4, who asked
 // An effect's attempts: how many were made, when the next may be, and, once its attempts are spent, when it failed and
 // why (engine.mjs runEffects). A failed effect is kept as the record of its terminal state and never tried again.
 const EFFECT_COLUMNS = { attempts: 'INTEGER NOT NULL DEFAULT 0', next_at: 'INTEGER NOT NULL DEFAULT 0', failed_at: 'INTEGER', last_error: 'TEXT' };
-const OURS_COLUMNS = { workspace_anchor: 'TEXT', workspace_root: 'TEXT', subtask_of: 'TEXT', stage: 'TEXT', since: 'INTEGER', after_fired: 'TEXT', blocked_by: 'TEXT', paused: 'TEXT', detached: 'TEXT', archived: 'INTEGER DEFAULT 0', every: 'TEXT', next_run_at: 'INTEGER', tags: 'TEXT', sponsor: 'TEXT', sponsor_evidence: 'TEXT', requested_by_unverified: 'TEXT' };
+const OURS_COLUMNS = { workspace_anchor: 'TEXT', workspace_root: 'TEXT', subtask_of: 'TEXT', stage: 'TEXT', since: 'INTEGER', after_fired: 'TEXT', blocked_by: 'TEXT', paused: 'TEXT', detached: 'TEXT', archived: 'INTEGER DEFAULT 0', every: 'TEXT', next_run_at: 'INTEGER', tags: 'TEXT', requested_by_unverified: 'TEXT' };
 
 // ------------------------------------------------------------------ backings
 //
@@ -137,6 +140,67 @@ export const logsDir = (root, slug = DEFAULT_BOARD) => join(boardDirOf(root, slu
  *  the board's logs and removed with them. */
 export const briefPath = (root, slug, id, run) => join(logsDir(root, slug), `${id}-r${run}.brief.md`);
 
+// A board's key: the capitals its card numbers read with (`VO-856`), as Jira and Linear key an issue. It is the board's
+// name (its label, which its address carries: `volter-org`, `volter-org/gtm`) said short: the first letter of each of
+// the label's words (`volter-org` is VO, `volter-org/gtm` is VOG), and at least two letters (`hookline` is HO). Two
+// boards of one home with the same key are refused: a key names one board.
+/** The key a board label reads its card numbers with. */
+export function keyOfLabel(label) {
+  const words = String(label).split(/[^A-Za-z0-9]+/).filter(Boolean).map((word) => word.replace(/^[0-9]+/, '')).filter(Boolean);
+  let key = words.map((word) => word[0]).join('').toUpperCase();
+  if (key.length < 2) key = (words[0] ?? 'board').slice(0, 2).toUpperCase().padEnd(2, 'B');
+  return key;
+}
+// Identity is kept beside the board, outside a rebuildable projection. A hard link claims each key once across
+// processes; a second hard link installs the winning identity on the board. Both survive home/board moves.
+// Reservations remain after removal, including archived boards. Reads of an assigned key never re-derive it.
+export function boardKey(root, slug = DEFAULT_BOARD, { creating = false, key: requested = null } = {}) {
+  const own = slug || DEFAULT_BOARD, file = join(boardDirOf(root, own), 'board-key.json');
+  if (existsSync(file)) return JSON.parse(readFileSync(file, 'utf8')).key;
+  if (creating) {
+    const peers = new Set(listBoards(root));
+    for (const peer of [...peers].sort()) if (peer !== own) boardKey(root, peer);
+  }
+  const base = requested ?? keyOfLabel(boardLabel(root, own));
+  if (!/^[A-Z][A-Z0-9]+$/.test(base)) throw new Error(`invalid board key ${base}`);
+  const reservations = join(root, 'kanban', 'board-keys');
+  mkdirSync(reservations, { recursive: true });
+  mkdirSync(dirname(file), { recursive: true });
+  for (let n = 1; ; n++) {
+    const key = n === 1 ? base : `${base}${n}`;
+    const claim = join(reservations, `${key}.json`);
+    const tmp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+    const identity = { key, board: own, id: randomBytes(16).toString('hex') };
+    writeFileSync(tmp, `${JSON.stringify(identity)}\n`, { flag: 'wx', mode: 0o600 });
+    try {
+      try { linkSync(tmp, claim); }
+      catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+        if (existsSync(file)) return JSON.parse(readFileSync(file, 'utf8')).key;
+        if (JSON.parse(readFileSync(claim, 'utf8')).board === own) {
+          try { linkSync(claim, file); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+          return JSON.parse(readFileSync(file, 'utf8')).key;
+        }
+        if (creating || requested) throw new Error(`board key ${key} is already assigned in this home; choose a different board slug`);
+        continue; // migrate a pre-existing collision without disabling either board
+      }
+      try { linkSync(tmp, file); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+      return JSON.parse(readFileSync(file, 'utf8')).key;
+    } finally { unlinkSync(tmp); }
+  }
+}
+/** A card as a person names it: its board's key and its number (`VO-856`). */
+export const cardRef = (key, number) => (number ? `${key}-${number}` : null);
+// Sessions and worktree folders retain the card's immutable keyed number (`vo-856`).
+// Branches also carry its readable id; card agents use role-readable-id.
+/** A card's handle (`vo-856`), or null for a card with no number. */
+export const cardHandle = (key, number) => (number ? `${String(key).toLowerCase()}-${number}` : null);
+/** The handle of card `id` on `board` (`vo-856`), or null before the card is filed. */
+export const cardHandleOf = (board, id) => id == null ? null : cardHandle(boardKey(board.root, board.slug), board.db.prepare(`SELECT number FROM ${CARD_NUMBERS} WHERE task_id = ?`).get(id)?.number);
+/** A branch keeps the unique number and the card's readable id. */
+export const cardBranch = (handle, readableId) => readableId ? `${handle}-${readableId}` : handle;
+export const readableIdOf = (board, id) => board.db.prepare('SELECT readable_id FROM tasks WHERE id=?').get(id)?.readable_id ?? null;
+
 /** The home's boards that exist: `default` when it does, and every named one. */
 export function listBoards(root) {
   const out = boardExists(root) ? [DEFAULT_BOARD] : [];
@@ -304,13 +368,29 @@ export function raiseCardNumbers(db, floor = 0) {
   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);
 }
 
+// Another opener may add a column after our schema read. Re-read only a duplicate-column refusal.
+function addColumns(db, table, columns) {
+  const names = () => new Set(db.prepare(`PRAGMA table_info(${table})`).all().map(c => c.name));
+  const held = names();
+  for (const [column, type] of Object.entries(columns)) if (!held.has(column)) {
+    try { db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`); }
+    catch (error) { if (!/duplicate column name/i.test(error.message) || !names().has(column)) throw error; }
+  }
+}
+
 /** 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);
   db.exec(OURS);
   db.exec(PUBLICATION_SCHEMA);
-  const have = new Set(db.prepare('PRAGMA table_info(supercode_cards)').all().map((c) => c.name));
-  for (const [column, type] of Object.entries(OURS_COLUMNS)) if (!have.has(column)) db.exec(`ALTER TABLE supercode_cards ADD COLUMN ${column} ${type}`);
+  addColumns(db, 'tasks', { readable_id: 'TEXT' });
+  for (const [table, added] of Object.entries(PUBLICATION_COLUMNS)) {
+    addColumns(db, table, added);
+  }
+  addColumns(db, 'supercode_cards', OURS_COLUMNS);
+  db.exec('CREATE INDEX IF NOT EXISTS supercode_readable_ids ON tasks(readable_id)');
+  fillReadableIds(db);
+  db.exec("CREATE UNIQUE INDEX IF NOT EXISTS supercode_open_readable_ids ON tasks(readable_id) WHERE status NOT IN ('done','cancelled','archived')");
   // A card's subtasks are read by the arc they name, for every scope built (workflow.mjs scopeOf): without this index
   // 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.
@@ -343,14 +423,13 @@ export function layOut(db, { fresh }) {
       current().err(`board: warning: ${refused.length > 1 ? 'indexes' : 'index'} ${names} on task_runs ${refused.length > 1 ? 'were' : 'was'} not created (${refused[0][1]}); the board is open without ${refused.length > 1 ? 'them' : 'it'}: each session's verb reads every run for its caller, and finds its cards from the cards. The runs that refuse ${refused.length > 1 ? 'them' : 'it'}: SELECT id FROM task_runs WHERE metadata IS NOT NULL AND NOT json_valid(metadata, 6)\n`);
     }
   }
-  const effectColumns = new Set(db.prepare('PRAGMA table_info(supercode_effects)').all().map((c) => c.name));
-  for (const [column, type] of Object.entries(EFFECT_COLUMNS)) if (!effectColumns.has(column)) db.exec(`ALTER TABLE supercode_effects ADD COLUMN ${column} ${type}`);
+  addColumns(db, 'supercode_effects', EFFECT_COLUMNS);
   // what changed is marked by the store itself, whoever writes it (published.mjs)
   publicationTriggers(db);
 }
 
 /**
- * Open (creating when `create`, in `backing`) board `slug`: `{ db, root, slug, path, backing, tx, close }`. `db` answers
+ * Open (creating when `create`, in `backing`) board `slug`: `{ db, root, slug, key, path, backing, tx, close }`. `db` answers
  * SQLite's statement API (`prepare(sql).get|all|run`, `exec`) whatever the backing.
  */
 // A home records where it was made (`.board-origin` at its root). A copy of the home carries that record elsewhere and
@@ -485,9 +564,11 @@ function openBoardNow(root, slug, { create = false, backing = null, document = n
   if (kept && backing && kept !== backing) throw new Error(`board ${slug} in ${root} is kept by the ${kept} backing, not ${backing}`);
   const use = kept ?? backing ?? 'sqlite';
   if (!BACKINGS.includes(use)) throw new Error(`a board's backing is ${BACKINGS.join(' | ')}, not ${use}`);
+  // Its key names its cards in what it publishes (`ref`, VO-856): assigned once, never re-derived.
+  const key = boardKey(root, slug, { creating: !kept });
   const path = backingPaths(root, slug)[use];
-  if (use === 'ztrack') return { ...openZtrackBoard(path, { create, document, declared, init: layOut, root, slug, held }), root, slug, path, backing: use };
-  if (use === 'files') return { ...openFilesBoard(path, { create, init: layOut, held }), root, slug, path, backing: use };
+  if (use === 'ztrack') return { ...openZtrackBoard(path, { create, document, declared, init: layOut, root, slug, held }), root, slug, key, path, backing: use };
+  if (use === 'files') return { ...openFilesBoard(path, { create, init: layOut, held }), root, slug, key, path, backing: use };
   if (!kept) mkdirSync(dirname(path), { recursive: true });
   const db = new DatabaseSync(path);
   db.exec('PRAGMA foreign_keys = OFF');
@@ -510,7 +591,7 @@ function openBoardNow(root, slug, { create = false, backing = null, document = n
       if (!contention(error)) throw error;
     }
   }
-  return { db, root, slug, path, backing: use, tx: (fn) => sqliteTx(db, fn), close: () => db.close() };
+  return { db, root, slug, key, path, backing: use, tx: (fn) => sqliteTx(db, fn), close: () => db.close() };
 }
 
 /**
@@ -523,7 +604,7 @@ export const tx = (board, fn) => {
   const caller = /at (?:async )?([\w.$<>]+) /.exec(String(new Error().stack).split('\n')[2] ?? '')?.[1] ?? 'unknown';
   const started = performance.now();
   try {
-    const result = board.tx(db => {const result=fn(db);const began=performance.now();try{recordCardPublications(db,actorOf(),board.root);}finally{noteStep('board tx publications',performance.now()-began);}return result;});
+    const result = board.tx(db => {const result=fn(db);fillReadableIds(db);const began=performance.now();try{recordCardPublications(db,actorOf(),board.root,board.key);}finally{noteStep('board tx publications',performance.now()-began);}return result;});
     signalBoardWrite(board.root, actorOf());
     return result;
   } finally { noteStep(`board tx from ${caller}`, performance.now() - started); }
@@ -543,7 +624,7 @@ export function publishMarked(root) {
       // a mark in the store, or a backing edit not yet imported into its tables (a ztrack document): the transaction
       // imports the edit, which marks its cards, and publishes them
       const marked = step('marks', () => board.db.prepare('SELECT 1 FROM supercode_publication_dirty LIMIT 1').get()) || step('unimported', () => board.unimported?.());
-      if (marked) published += step('publish', () => board.tx((db) => recordCardPublications(db, actorOf(),board.root)));
+      if (marked) published += step('publish', () => board.tx((db) => recordCardPublications(db, actorOf(), board.root, board.key)));
       if (step('prune due', () => pruneDue(board.db))) step('prune', () => board.tx((db) => prunePublications(db)));
     } finally { board?.close(); }
   }