@volter/supercode-orchestrator 0.5.162 → 0.5.163

package/board/cli.mjs

@@ -12,6 +12,8 @@ import { BOARD_OPERATION_VERBS, boardHome, boardOwnerSocket, CALLER_FACTS } from
 import { current, isCallersCall, ownCall, within } from './call.mjs';
 import { taskStatusOf } from './published.mjs';
 import { executionOf } from './session-work.mjs';
+import { listCardsInTurns, writeCardList } from './listing.mjs';
+import { writeOwnerAnswer } from './reply.mjs';
 import { createServer } from 'node:net';
 import { chmodSync, existsSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, copyFileSync, readFileSync, appendFileSync, writeFileSync } from 'node:fs';
 import { notRuntime, ownHome } from './owner-files.mjs';
@@ -279,9 +281,6 @@ async function requestedSponsor(args) {
   return { requestedByUnverified: { observation: args['requested-by'], label: resolved?.label ?? 'unresolved', request: args.request ?? null } };
 }
 
-// `list --json` reads each card's parents and standing block per card up to this many cards, and in one read of each past it
-const LIST_PER_CARD = 64;
-
 const tagsOf = (card) => { const tags = Array.isArray(card.tags) ? card.tags : json(card.tags, null); return Array.isArray(tags) ? tags : card.tenant ? [card.tenant] : []; };
 
 const say = (args, human, value) => { current().out(args.json ? `${JSON.stringify(value, null, 2)}\n` : `${human}\n`); };
@@ -354,7 +353,8 @@ export async function runVerb(argv) {
   // a caller that is a card's own session (its harness names it; the board recorded which session it launched)
   const listing = ['list','ls'].includes(verb);
   await loadWorkflow(root).catch((error) => { if (verb !== 'init' && verb !== 'boards') throw error; });
-  await readAgentMains(root);
+  // A listing does not authorize a transition and needs no manager's main session.
+  if (!listing) await readAgentMains(root);
   const sid = listing && !args.mine ? null : callerSession();
   // what this command records is the calling session's act (its address, as its subscriptions name it)
   current().recorded = sid && boardExists(root, slug) ? withBoard((b) => b.db.prepare(CALLER_RUN_ADDRESS).get(sid)?.address) ?? null : null;
@@ -503,16 +503,8 @@ export async function runVerb(argv) {
 
     case 'list': case 'ls': {
       const assignee = args.assignee ?? (args.mine ? callerName() : null);
-      const cards = withBoard((b) => {
-        let rows = engine.listCards(b.db, { status: args.status, assignee, machine: args.machine, includeArchived: args.archived || args.all });
-        if (args.tenant) rows = rows.filter((t) => t.tenant === args.tenant);
-        // a saved view (C4) is the Org's cards that carry its tag
-        for (const tag of [...(viewTag ? [viewTag] : []), ...(args.tag ?? [])]) rows = rows.filter((t) => tagsOf(t).includes(tag));
-        if (args.session) rows = rows.filter((t) => t.session_id === args.session);
-        if (args['workflow-template-id']) rows = rows.filter((t) => t.workflow_template_id === args['workflow-template-id']);
-        if (args['step-key']) rows = rows.filter((t) => t.current_step_key === args['step-key']);
-        return rows;
-      });
+      const cards = await withBoardAsync(b => listCardsInTurns(b.db, { detailed: Boolean(args.json), status: args.status, assignee, machine: args.machine, includeArchived: args.archived || args.all,
+        tenant: args.tenant, session: args.session, workflowTemplateId: args['workflow-template-id'], stepKey: args['step-key'], tags: [...(viewTag ? [viewTag] : []), ...(args.tag ?? [])] }));
       const sorters = {
         assignee: (a, b) => String(a.assignee ?? '').localeCompare(String(b.assignee ?? '')), created: (a, b) => a.created_at - b.created_at,
         'created-desc': (a, b) => b.created_at - a.created_at, priority: (a, b) => a.priority - b.priority, 'priority-desc': (a, b) => b.priority - a.priority,
@@ -521,44 +513,16 @@ export async function runVerb(argv) {
       };
       if (args.sort) { if (!sorters[args.sort]) throw new Error(`--sort is one of ${Object.keys(sorters).join(', ')}`); cards.sort(sorters[args.sort]); }
       if (args.json) {
-        // beyond Hermes's fields: the workflow's own status, the cards it waits on and its open run, so a reader of the
-        // whole board (a board file's sync) needs no `show` per card
-        const extra = withBoard((b) => {
-          // A whole board's parents and standing blocks are read once, not once per card. Asked per card, the block's
-          // read fetched every event row of every card through the card's index to answer from the few of these
-          // kinds (on 2026-10-11: 45,670 rows of a 17 MB table for 2,154 cards, to find 332), on the owner's event
-          // loop, for as long as the listing took. A short listing still asks per card: it reads less than the scan.
-          const whole = cards.length > LIST_PER_CARD;
-          const parentsOf = new Map(), standing = new Map();
-          if (whole) {
-            for (const row of b.db.prepare('SELECT child_id, parent_id FROM task_links ORDER BY child_id, parent_id').all()) {
-              if (!parentsOf.has(row.child_id)) parentsOf.set(row.child_id, []);
-              parentsOf.get(row.child_id).push(row.parent_id);
-            }
-            // in id order, so the last one kept for a card is its latest
-            for (const row of b.db.prepare("SELECT task_id, kind, payload FROM task_events WHERE kind IN ('blocked', 'unblocked', 'dependency_wait') ORDER BY id").all()) standing.set(row.task_id, row);
-          }
-          return new Map(cards.map((t) => {
-            const run = t.current_run_id ? b.db.prepare('SELECT id, status, started_at, metadata FROM task_runs WHERE id = ?').get(t.current_run_id) : null;
-            const session = run ? json(run.metadata, {})?.supercode ?? {} : {};
-            return [t.id, {
-              workflow_status: t.stage ?? t.status,
-              parents: whole ? parentsOf.get(t.id) ?? [] : b.db.prepare('SELECT parent_id FROM task_links WHERE child_id = ? ORDER BY parent_id').all(t.id).map((r) => r.parent_id),
-              run: run ? { id: run.id, status: run.status, started_at: run.started_at, session: session.address ?? session.session_id ?? null, execution: executionOf(run) } : null,
-              // the message whose answer its standing block waits for (`block --waiting-on`)
-              waiting_on: (() => {
-                const last = whole ? standing.get(t.id) : b.db.prepare("SELECT kind, payload FROM task_events WHERE task_id = ? AND kind IN ('blocked', 'unblocked', 'dependency_wait') ORDER BY id DESC LIMIT 1").get(t.id);
-                return last?.kind === 'blocked' ? json(last.payload, {})?.waiting_on ?? null : null;
-              })(),
-            }];
-          }));
-        });
-        say(args, '', cards.map((t) => ({ ...cardDict(t), ...extra.get(t.id) })));
+        await writeCardList(cards, t => ({ ...cardDict(t), workflow_status: t.workflow_status, parents: t.parents, run: t.run, waiting_on: t.waiting_on }), current().out);
         return 0;
       }
       const others = boardsOf(root, { includeArchived: false }).length - 1;
       if (others > 0) current().out(`Board: ${slug} (${others} other board${others === 1 ? '' : 's'} — \`supercode workflow boards list\`)\n\n`);
-      current().out(cards.length ? `${cards.map(line).join('\n')}\n` : '(no matching tasks)\n');
+      if (!cards.length) current().out('(no matching tasks)\n');
+      for (let offset = 0; offset < cards.length; offset += 64) {
+        current().out(`${cards.slice(offset, offset + 64).map(line).join('\n')}\n`);
+        await new Promise(resolve => setImmediate(resolve));
+      }
       return 0;
     }
 
@@ -1599,7 +1563,8 @@ async function answerVerbs(root, log) {
       // one answer per call, whatever the request did: a request that fails is a failed answer, never the owner's end
       answerOne(root, line)
         .catch((error) => ({ code: 1, stdout: '', stderr: `supercode workflow: ${error?.message ?? error}\n` }))
-        .then((answer) => { if (!socket.destroyed) socket.end(`${JSON.stringify(answer)}\n`); });
+        .then((answer) => writeOwnerAnswer(socket, answer))
+        .catch(() => { socket.destroy(); }); // a disconnected caller leaves no queued reply
     });
   });
   await new Promise((done, fail) => { server.once('error', fail); server.listen(path, () => { server.off('error', fail); done(); }); });
@@ -1642,14 +1607,14 @@ async function answerRequest(root, line, naming) {
     if (!facts.SUPERCODE_CONTEXT) return { code: 1, stdout: '', stderr: 'supercode workflow: the request names no Teams context (facts.SUPERCODE_CONTEXT); nothing was done\n' };
     const cwd = typeof request.cwd === 'string' && request.cwd ? request.cwd : root;
     const stdin = typeof request.stdin === 'string' ? request.stdin : null;
-    let stdout = '';
-    let stderr = '';
+    const stdout = [];
+    const stderr = [];
     let code;
-    await within({ caller, facts, cwd, stdin, out: (text) => { stdout += text; return true; }, err: (text) => { stderr += text; return true; } }, async () => {
+    await within({ caller, facts, cwd, stdin, out: (text) => { stdout.push(text); return true; }, err: (text) => { stderr.push(text); return true; } }, async () => {
       // a worker's board tool (mcp/server.mjs), answered by the board's tools in this call (board/tools.mjs)
-      if (tool) { stdout = await boardTool(root, tool.name, tool.args && typeof tool.args === 'object' ? tool.args : {}, Object.fromEntries(Object.entries(tool.env ?? {}).filter(([key, value]) => /^HERMES_(KANBAN_TASK|KANBAN_RUN_ID|KANBAN_BOARD|PROFILE)$/.test(key) && typeof value === 'string'))); code = 0; return; }
+      if (tool) { stdout.push(await boardTool(root, tool.name, tool.args && typeof tool.args === 'object' ? tool.args : {}, Object.fromEntries(Object.entries(tool.env ?? {}).filter(([key, value]) => /^HERMES_(KANBAN_TASK|KANBAN_RUN_ID|KANBAN_BOARD|PROFILE)$/.test(key) && typeof value === 'string')))); code = 0; return; }
       try { code = await runVerb([...argv, '--root', root, ...(typeof request.board === 'string' && request.board ? ['--board', request.board] : [])]); }
-      catch (error) { stderr += `supercode workflow: ${error?.message ?? error}\n`; code = 1; }
+      catch (error) { stderr.push(`supercode workflow: ${error?.message ?? error}\n`); code = 1; }
     });
     return { code: code ?? 0, stdout, stderr };
   } catch (error) {

package/board/files.mjs

@@ -14,6 +14,7 @@ import { markRemovedHeads } from './published.mjs';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
+import { LIST_REVISION, listRevision } from './listing.mjs';
 
 const STATE = '_board.json';
 
@@ -58,6 +59,7 @@ class FilesBoard {
     const self = this;
     // the connection the engine holds: SQLite's statement API over whatever snapshot is current
     this.db = {
+      [LIST_REVISION]: () => self.read(() => listRevision(self.mem)),
       prepare(sql) {
         return {
           get: (...args) => self.read(() => self.statement(sql).get(...args)),

package/board/listing.mjs

@@ -0,0 +1,134 @@
+// A listing reads at most 64 candidate tasks per turn, even when its filters match none.
+// Native SQLite calls still run on the caller's thread; this is a row bound, not a time bound.
+import { setImmediate as nextTurn } from 'node:timers/promises';
+import { noteStep } from '@volter/supercode-harness-sdk/slow-log';
+import { executionOf } from './session-work.mjs';
+
+export const LIST_BATCH = 64;
+export const LIST_CONNECTION = Symbol.for('supercode.board.listing.connection');
+export const LIST_REVISION = Symbol.for('supercode.board.listing.revision');
+const parse = (text, fallback) => { try { return JSON.parse(text) ?? fallback; } catch { return fallback; } };
+const statements = new WeakMap();
+const prepared = (db, sql) => {
+  const connection = db[LIST_CONNECTION] ?? db;
+  let held = statements.get(connection);
+  if (!held) { held = new Map(); statements.set(connection, held); }
+  if (!held.has(sql)) held.set(sql, db.prepare(sql));
+  return held.get(sql);
+};
+const measured = (name, fn) => {
+  const at = performance.now();
+  try { return fn(); } finally { noteStep(`board list: ${name}`, performance.now() - at); }
+};
+
+// Validate an optimistic read, without leaving a transaction open on the owner's shared
+// connection across awaits. data_version names commits from other connections; total_changes
+// also catches this connection's writes. Schema versions catch TEMP overlay creation/removal.
+// Files backings additionally change connection identity when they reload their projection.
+export function listRevision(db) {
+  if (db[LIST_REVISION]) return db[LIST_REVISION]();
+  const connection = db[LIST_CONNECTION] ?? db;
+  return {
+    connection,
+    data: prepared(connection, 'PRAGMA main.data_version').get().data_version,
+    changes: prepared(connection, 'SELECT total_changes() AS changes').get().changes,
+    mainSchema: prepared(connection, 'PRAGMA main.schema_version').get().schema_version,
+    tempSchema: prepared(connection, 'PRAGMA temp.schema_version').get().schema_version,
+  };
+}
+const sameRevision = (a, b) => Object.keys(a).every(key => a[key] === b[key]);
+
+// Only the fields cardDict, human lines, filters and sorters use. A human listing never reads
+// body/result/skills or run history. A JSON listing retains its existing full-text contract.
+const HUMAN_FIELDS = 'id,title,assignee,status,priority,tenant,created_at,started_at,completed_at';
+const JSON_FIELDS = `${HUMAN_FIELDS},body,result,workspace_kind,workspace_path,branch_name,project_id,created_by,skills,max_retries,model_override,provider_override,session_id,workflow_template_id,current_step_key`;
+export const TASK_SUMMARY_INDEX = 'idx_tasks_list_summary';
+export const TASK_SUMMARY_INDEX_SQL = `CREATE INDEX IF NOT EXISTS ${TASK_SUMMARY_INDEX} ON tasks(${HUMAN_FIELDS},current_run_id,session_id,workflow_template_id,current_step_key)`;
+const RUN_METADATA = `CASE WHEN json_valid(r.metadata) THEN json_object('supercode', json_object(
+  'address',json_extract(r.metadata,'$.supercode.address'),'session_id',json_extract(r.metadata,'$.supercode.session_id'),
+  'close_confirmed_at',json_extract(r.metadata,'$.supercode.close_confirmed_at'),'released',json_extract(r.metadata,'$.supercode.released'),
+  'presence_observation',json_extract(r.metadata,'$.supercode.presence_observation'),'idle_observation',json_extract(r.metadata,'$.supercode.idle_observation')
+)) END`;
+export const LIST_CANDIDATES_SQL = `SELECT MAX(id) AS last, json_group_array(id) AS ids FROM (
+  SELECT id FROM tasks WHERE id > ? AND id <= ? ORDER BY id LIMIT ${LIST_BATCH})`;
+
+// Three reverse index seeks find the latest event of the relevant kinds. Only that row's
+// blocked payload is returned, rather than every historical payload for the whole board.
+export const LAST_BLOCK_SQL = `SELECT CASE WHEN kind = 'blocked' THEN payload END FROM task_events WHERE id = (
+  SELECT MAX(id) FROM (
+    SELECT (SELECT id FROM task_events WHERE task_id = t.id AND kind = 'blocked' ORDER BY id DESC LIMIT 1) AS id
+    UNION ALL SELECT (SELECT id FROM task_events WHERE task_id = t.id AND kind = 'unblocked' ORDER BY id DESC LIMIT 1)
+    UNION ALL SELECT (SELECT id FROM task_events WHERE task_id = t.id AND kind = 'dependency_wait' ORDER BY id DESC LIMIT 1)
+  ))`;
+
+export function listPageSql(detailed, tagCount = 0) {
+  return `SELECT t.rowid AS list_order,${(detailed ? JSON_FIELDS : HUMAN_FIELDS).split(',').map(name => `t.${name}`).join(',')},
+    c.machine,c.stage${detailed ? ',c.subtask_of' : ''},
+    r.id AS run_id,r.status AS run_status,r.started_at AS run_started_at,r.ended_at AS run_ended_at,${RUN_METADATA} AS run_metadata
+    ${detailed ? `,(SELECT json_group_array(parent_id) FROM (SELECT parent_id FROM task_links WHERE child_id = t.id ORDER BY parent_id)) AS parents_json,
+      (${LAST_BLOCK_SQL}) AS block_payload` : ''}
+    FROM tasks t ${detailed ? '' : `INDEXED BY ${TASK_SUMMARY_INDEX}`} LEFT JOIN supercode_cards c ON c.task_id = t.id LEFT JOIN task_runs r ON r.id = t.current_run_id
+    WHERE t.id IN (SELECT value FROM json_each(?)) AND (? IS NULL OR t.status = ? OR c.stage = ?)
+      AND (? IS NULL OR t.assignee = ?) AND (? IS NULL OR c.machine = ?) AND (? OR t.status != 'archived')
+      AND (? IS NULL OR t.tenant = ?) AND (? IS NULL OR t.session_id = ?)
+      AND (? IS NULL OR t.workflow_template_id = ?) AND (? IS NULL OR t.current_step_key = ?)
+      ${Array.from({ length: tagCount }, () => `AND CASE WHEN json_valid(c.tags) THEN
+        CASE WHEN json_type(c.tags) = 'array' THEN EXISTS (SELECT 1 FROM json_each(c.tags) WHERE value = ?) ELSE t.tenant = ? END
+        ELSE t.tenant = ? END`).join('\n')}`;
+}
+
+export async function listCardsInTurns(db, options = {}) {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const revision = measured('read revision', () => listRevision(db));
+    const cards = await readCardsInTurns(db, options, revision);
+    if (cards !== null) return cards;
+  }
+  throw Object.assign(new Error('board changed during both listing reads; run list again'), { code: 'board_listing_changed' });
+}
+
+async function readCardsInTurns(db, { detailed = false, status = null, assignee = null, machine = null, includeArchived = false,
+  tenant = null, session = null, workflowTemplateId = null, stepKey = null, tags = [] }, revision) {
+  const out = [];
+  const page = prepared(db, listPageSql(detailed, tags.length)), candidates = prepared(db, LIST_CANDIDATES_SQL);
+  const ceiling = measured('last candidate', () => prepared(db, "SELECT COALESCE(MAX(id), '') AS cursor FROM tasks").get().cursor);
+  let cursor = '';
+  while (cursor < ceiling) {
+    if (!measured('validate revision', () => sameRevision(revision, listRevision(db)))) return null;
+    const range = measured('candidate range', () => candidates.get(cursor, ceiling));
+    if (range.last == null) break;
+    const rows = measured(detailed ? 'JSON task rows and latest blocks' : 'human task rows', () => page.all(range.ids,
+      status, status, status, assignee, assignee, machine, machine, includeArchived ? 1 : 0,
+      tenant, tenant, session, session, workflowTemplateId, workflowTemplateId, stepKey, stepKey, ...tags.flatMap(tag => [tag, tag, tag])));
+    measured('row projection', () => {
+      for (const { run_id, run_status, run_started_at, run_ended_at, run_metadata, parents_json, block_payload, ...task } of rows) {
+        const metadata = run_id ? parse(run_metadata, {}) : null;
+        const run = run_id ? { id: run_id, status: run_status, started_at: run_started_at, ended_at: run_ended_at, metadata } : null;
+        task.execution = executionOf(run);
+        if (detailed) {
+          task.skills = parse(task.skills, []);
+          task.workflow_status = task.stage ?? task.status;
+          task.parents = parse(parents_json, []);
+          task.waiting_on = parse(block_payload, {})?.waiting_on ?? null;
+          task.run = run ? { id: run.id, status: run.status, started_at: run.started_at, session: metadata.supercode?.address ?? metadata.supercode?.session_id ?? null, execution: task.execution } : null;
+        }
+        out.push(task);
+      }
+    });
+    cursor = range.last;
+    await nextTurn();
+  }
+  if (!measured('validate revision', () => sameRevision(revision, listRevision(db)))) return null;
+  // The candidate index uses id order; restore the original task row order for tied sorts.
+  measured('ordering', () => out.sort((a, b) => b.priority - a.priority || a.created_at - b.created_at || a.list_order - b.list_order));
+  return out;
+}
+
+// Keep pretty JSON and its newline while avoiding one whole-board JSON.stringify allocation.
+export async function writeCardList(cards, project, out) {
+  out(cards.length ? '[\n' : '[]\n');
+  for (let index = 0; index < cards.length; index++) {
+    measured('serialize card', () => out(`${JSON.stringify(project(cards[index]), null, 2).split('\n').map(line => `  ${line}`).join('\n')}${index + 1 < cards.length ? ',' : ''}\n`));
+    if ((index + 1) % LIST_BATCH === 0) await nextTurn();
+  }
+  if (cards.length) out(']\n');
+}

package/board/reply.mjs

@@ -0,0 +1,51 @@
+// The owner's existing one-line answer protocol, escaped and written in bounded pieces.
+// No whole stdout rope is flattened, escaped, or converted to a socket buffer here.
+import { setImmediate as nextTurn } from 'node:timers/promises';
+import { noteStep } from '@volter/supercode-harness-sdk/slow-log';
+
+export const REPLY_CHARS = 8192;
+const measured = (name, fn) => {
+  const at = performance.now();
+  try { return fn(); } finally { noteStep(`owner reply ${name}`, performance.now() - at); }
+};
+
+async function write(socket, text) {
+  if (socket.destroyed) return false;
+  // One buffer in flight. The write callback waits for this write instead of accumulating
+  // a whole answer behind a reader that has stopped taking bytes.
+  const buffer = measured('encode buffer', () => Buffer.from(text));
+  await new Promise((resolve, reject) => {
+    const closed = () => finish(new Error('board caller closed before its answer was written'));
+    const finish = (error) => { socket.off('close', closed); error ? reject(error) : resolve(); };
+    socket.once('close', closed);
+    const at = performance.now();
+    try { socket.write(buffer, finish); } catch (error) { finish(error); }
+    finally { noteStep('owner reply socket.write', performance.now() - at); }
+  });
+  await nextTurn();
+  return !socket.destroyed;
+}
+
+export async function writeOwnerAnswer(socket, { code = 0, stdout = '', stderr = '' }) {
+  if (!await write(socket, `{"code":${JSON.stringify(code)},"stdout":"`)) return;
+  for (const [index, value] of [stdout, stderr].entries()) {
+    let carry = '';
+    for (const part of Array.isArray(value) ? value : [value]) {
+      for (let offset = 0; offset < part.length;) {
+        const end = Math.min(part.length, offset + REPLY_CHARS - carry.length);
+        let chunk = carry + part.slice(offset, end);
+        carry = '';
+        offset = end;
+        // A pair can straddle either a fragment or an output part. Keep its high half
+        // until the next fragment so JSON.stringify emits the original UTF-8 wire bytes.
+        const last = chunk.charCodeAt(chunk.length - 1);
+        if (last >= 0xd800 && last <= 0xdbff) { carry = chunk.slice(-1); chunk = chunk.slice(0, -1); }
+        if (chunk && !await write(socket, measured('escape string chunk', () => JSON.stringify(chunk).slice(1, -1)))) return;
+      }
+    }
+    if (carry && !await write(socket, measured('escape string chunk', () => JSON.stringify(carry).slice(1, -1)))) return;
+    if (index === 0 && !await write(socket, '","stderr":"')) return;
+  }
+  if (!await write(socket, '"}\n')) return;
+  measured('socket.end', () => socket.end());
+}

package/board/store.mjs

@@ -19,6 +19,7 @@ import { hostname } from 'node:os';
 import { dirname, join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { openZtrackBoard } from './ztrack.mjs';
+import { 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';
@@ -222,6 +223,20 @@ function layOutEventIndex(db) {
   }
 }
 
+function layOutSummaryIndex(db) {
+  if (indexed(db, TASK_SUMMARY_INDEX)) return;
+  const report = text => { writeSync(2, text); if (current().kind === 'caller') current().err(text); };
+  report(`board: creating index ${TASK_SUMMARY_INDEX}: one-time task scan and summary index write; this synchronous migration holds the owner event loop until it finishes\n`);
+  const began = performance.now();
+  let made = false;
+  try { db.exec(TASK_SUMMARY_INDEX_SQL); made = true; }
+  finally {
+    const ms = performance.now() - began;
+    noteStep(`board open index ${TASK_SUMMARY_INDEX}`, ms);
+    report(`board: index ${TASK_SUMMARY_INDEX} ${made ? 'created' : 'creation failed'} after ${Math.round(ms)} ms\n`);
+  }
+}
+
 /** 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);
@@ -234,6 +249,8 @@ export function layOut(db, { fresh }) {
   // any statement is prepared; no statement names it, so a store without it is only slower.
   db.exec('CREATE INDEX IF NOT EXISTS idx_supercode_cards_subtask_of ON supercode_cards(subtask_of)');
   layOutEventIndex(db);
+  // A covering summary index keeps human listings out of task records' body overflow pages.
+  layOutSummaryIndex(db);
   // The calling session's run (CALLER_RUN_ADDRESS) and its cards (SESSION_CURRENT_RUNS, SESSION_BOUND, SESSION_RUNS):
   // without the session's index each lookup read every run's whole metadata, overflow pages included. `id` keeps a
   // session's runs in the order the lookups ask for, and the address makes the index answer the caller's lookup without
@@ -357,7 +374,7 @@ function heldHandle(entry, slug) {
   const guard = () => { if (entry.retired) throw Object.assign(new Error(`board ${slug}'s configuration changed while this call held it; nothing was written (read it again)`), { code: 'board_retired' }); };
   const bound = (target, key) => { const value = target[key]; return typeof value === 'function' ? value.bind(target) : value; };
   const statement = (st) => new Proxy(st, { get: (target, key) => key === 'run' ? (...args) => { guard(); return target.run(...args); } : bound(target, key) });
-  const db = new Proxy(entry.board.db, { get: (target, key) => key === 'prepare' ? (sql) => statement(target.prepare(sql)) : key === 'exec' ? (sql) => { guard(); return target.exec(sql); } : bound(target, key) });
+  const db = new Proxy(entry.board.db, { get: (target, key) => key === LIST_CONNECTION ? target : key === 'prepare' ? (sql) => statement(target.prepare(sql)) : key === 'exec' ? (sql) => { guard(); return target.exec(sql); } : bound(target, key) });
   let closed = false;
   return { ...entry.board, db, tx: (fn) => { guard(); return entry.board.tx(fn); },
     close() { if (closed) return; closed = true; entry.uses -= 1; if (entry.retired && !entry.uses) try { entry.board.close(); } catch { /* closed */ } } };

package/board/ztrack.mjs

@@ -68,6 +68,7 @@ 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';
 
 const require = createRequire(import.meta.url);
 const hash = (text) => createHash('sha256').update(text).digest('hex');
@@ -171,6 +172,7 @@ class ZtrackBoard {
     timedStep('board open errors', () => this.loadErrors());
     const self = this;
     this.db = {
+      [LIST_REVISION]: () => self.read(() => listRevision(self.conn)),
       boardErrors: self.errors,
       prepare(sql) {
         return {
@@ -768,6 +770,7 @@ class ZtrackBoard {
     if (overlay) {
       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.overlay = true; this.statements.clear();
     }
     const initial = !overlay && !this.one('SELECT 1 FROM main.tasks LIMIT 1');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.162",
+  "version": "0.5.163",
   "type": "module",
   "description": "The orchestrator runtime over the Volter Harness ontology: one typed operational model whose folder is its serialization, read and written through the harness orchestration doors (docs/ORCHESTRATOR-IR.md)",
   "exports": {