Skip to content

Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.

feat(board): name slow write holders [C7,P4,B2]

Corey Olson35114a4a265b
diff --git a/src/board-access.js b/src/board-access.js
index a486fde8..c6bbd810 100644
--- a/src/board-access.js
+++ b/src/board-access.js
@@ -1,3 +1,4 @@
+import { boardWriteHolderText } from './board-write-lock.js';
/** Name a board this process cannot write, such as one inside a read-only agent sandbox [I1,P4]. */
import { dirname } from 'node:path';
import { AGENT_SHELL_MARKERS } from './person.js';
@@ -41,5 +42,5 @@ export function boardNotWritable(file, error, environment = process.env) {
export function boardBusyError(file, startedAt, error) {
const sqliteCode = Number.isInteger(error.errcode) ? error.errcode & 0xff : null;
if (sqliteCode !== 5 && error.code !== 'SQLITE_BUSY' && !/database is locked/iu.test(error.message ?? '')) return error;
- return new Refused('BOARD_BUSY', `board file ${file} remained held by another process after ${Date.now() - startedAt}ms; wait for it to finish and retry`);
+ return new Refused('BOARD_BUSY', `board file ${file} remained held by another process after ${Date.now() - startedAt}ms; wait for it to finish and retry${boardWriteHolderText(file)}`);
}
diff --git a/src/board-busy.js b/src/board-busy.js
index 5374e880..2c494e5a 100644
--- a/src/board-busy.js
+++ b/src/board-busy.js
@@ -1,3 +1,4 @@
+import { boardWriteHolderText } from './board-write-lock.js';
/** Translate SQLite lock contention without coupling error reporting to the full board store [C7]. */
import { Refused } from './refused.js';
@@ -17,7 +18,7 @@ function isBusy(error) {
*/
export function boardBusyError(file, startedAt, error) {
if (!isBusy(error)) return error;
- return new Refused('BOARD_BUSY', `board file ${file} remained held by another process after ${Date.now() - startedAt}ms; wait for it to finish and retry`);
+ return new Refused('BOARD_BUSY', `board file ${file} remained held by another process after ${Date.now() - startedAt}ms; wait for it to finish and retry${boardWriteHolderText(file)}`);
}
/** Name a failed write admission; resolve its board path only after real contention occurs. */
diff --git a/src/board-read-open.js b/src/board-read-open.js
index 5b1c08c6..36737902 100644
--- a/src/board-read-open.js
+++ b/src/board-read-open.js
@@ -1,3 +1,4 @@
+import { closeBoardWrites } from './board-write-lock.js';
/** Open existing board data without loading move execution [C7]. */
import { existsSync } from 'node:fs';
import { DatabaseSync } from 'node:sqlite';
@@ -71,5 +72,6 @@ export function readEventLogVersion(db) {
*/
export function closeBoard(board) {
board.db.close();
+ closeBoardWrites(board.db);
}
diff --git a/src/board-write-lock.js b/src/board-write-lock.js
new file mode 100644
index 00000000..6d052d53
--- /dev/null
+++ b/src/board-write-lock.js
@@ -0,0 +1,154 @@
+/** Advisory process-owned write records; never part of native board state or lock authority [C7,P4]. */
+import { randomUUID } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { mkdirSync } from 'node:fs';
+import { writeFileSync } from 'node:fs';
+import { unlinkSync } from 'node:fs';
+import { readdirSync } from 'node:fs';
+import { realpathSync } from 'node:fs';
+import { lstatSync } from 'node:fs';
+import { openSync } from 'node:fs';
+import { fstatSync } from 'node:fs';
+import { readSync } from 'node:fs';
+import { closeSync } from 'node:fs';
+import { writeSync } from 'node:fs';
+import { constants } from 'node:fs';
+import { join } from 'node:path';
+import { parseProcessCensus } from './process-census.js';
+
+const pending = new WeakMap();
+let ownIdentity;
+let identityPrepared = false;
+const LONG_WRITE_MS = 2_000;
+
+/** Run one bounded PID-only query, without reading or changing any other process's arguments or state. */
+function identities(pids) {
+ if (!pids.length) return new Map();
+ try {
+ const result = spawnSync('/bin/ps', ['-p', [...new Set(pids)].join(','), '-o', 'pid=,ppid=,pgid=,lstart=,stat=,comm='], {
+ encoding: 'utf8', timeout: 2_000, maxBuffer: 128 * 1024,
+ env: { PATH: '/usr/bin:/bin', LANG: 'C', LC_ALL: 'C', TZ: 'UTC' },
+ });
+ return result.error || result.status !== 0 ? new Map() : parseProcessCensus(result.stdout) ?? new Map();
+ } catch { return new Map(); /* Optional process metadata cannot replace the original move or refusal. */ }
+}
+
+/** Prepare once BEFORE acquiring SQLite's outer write lock, including when process metadata is unavailable. */
+export function prepareBoardWriteIdentity() {
+ if (identityPrepared) return;
+ identityPrepared = true;
+ ownIdentity = identities([process.pid]).get(process.pid) ?? null;
+}
+
+/** Resolve a real database's local sidecar directory; memory boards have no filesystem publication. */
+function boardFile(db) {
+ const file = db.prepare('PRAGMA database_list').all().find(row => row.name === 'main')?.file;
+ return file ? realpathSync(file) : null;
+}
+
+/** Keep labels bounded and single-line; no user note, SQL, parameters, or session material is recorded. */
+function label(value, fallback) {
+ return typeof value === 'string' && /^[A-Za-z0-9_./:-]{1,100}$/u.test(value) ? value : fallback;
+}
+
+/** Resolve a registered seat from the caller's checkout, only after SQLite grants this write transaction. */
+function contextFor(db, context) {
+ let seat = context.seat;
+ if (!seat && context.path && db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='agent'").get()) {
+ seat = db.prepare('SELECT agent_id FROM agent WHERE agent_path=?').get(context.path)?.agent_id;
+ }
+ return { command: label(context.command, 'api'), seat: label(seat, 'unknown') };
+}
+
+/** Start tracking AFTER successful BEGIN; slow admission is never misreported as lock-holding time. */
+export function beginBoardWrite(db, context = {}) {
+ const record = { db, start: performance.now(), acquiredAt: Date.now(), pid: process.pid,
+ command: 'api', seat: 'unknown', marker: null, complete: false };
+ let records = pending.get(db);
+ if (!records) { records = new Set(); pending.set(db, records); }
+ records.add(record);
+ try {
+ Object.assign(record, contextFor(db, context));
+ const file = boardFile(db);
+ if (!file) return record;
+ if (!ownIdentity || ownIdentity.state.startsWith('Z')) return record;
+ const directory = file + '.write-holders';
+ mkdirSync(directory, { recursive: true, mode: 0o700 });
+ if (!lstatSync(directory).isDirectory()) return record;
+ const marker = join(directory, `${process.pid}-${randomUUID()}.json`);
+ const detail = { version: 1, pid: process.pid, started: ownIdentity.started, processSha256: ownIdentity.processSha256,
+ command: record.command, seat: record.seat, acquiredAt: record.acquiredAt };
+ writeFileSync(marker, JSON.stringify(detail) + '\n', { flag: 'wx', mode: 0o600 });
+ record.marker = marker;
+ } catch { /* Optional diagnostics cannot refuse, roll back, or change a native move. Unknown holders stay unknown. */ }
+ return record;
+}
+
+/** Complete only after COMMIT/ROLLBACK or actual connection close; unique records cannot unlink a successor. */
+export function finishBoardWrite(record, released, outcome = 'released') {
+ if (!record || record.complete || !released) return;
+ record.complete = true;
+ const durationMs = Math.max(0, Math.round(performance.now() - record.start));
+ if (durationMs > LONG_WRITE_MS) {
+ const line = { command: record.command, seat: record.seat, pid: record.pid, durationMs, outcome };
+ try { writeSync(2, 'pullboard: long board write ' + JSON.stringify(line) + '\n'); }
+ catch { /* A closed diagnostic stream must not turn an already committed move into an apparent refusal. */ }
+ }
+ if (record.marker) {
+ try { unlinkSync(record.marker); }
+ catch { /* Retain a stale advisory file if cleanup is unavailable; PID/start checks keep it non-authoritative. */ }
+ }
+ pending.get(record.db)?.delete(record);
+}
+
+/** A failed release remains observable until the caller actually closes the SQLite connection. */
+export function closeBoardWrites(db) {
+ for (const record of pending.get(db) ?? []) finishBoardWrite(record, true, 'connection-closed');
+ pending.delete(db);
+}
+
+/** Read only a bounded regular sidecar file, never a link or arbitrary native board content. */
+function readMarker(file) {
+ let fd;
+ try {
+ fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+ const stat = fstatSync(fd);
+ if (!stat.isFile() || stat.size > 4_096) return null;
+ const buffer = Buffer.alloc(stat.size);
+ if (readSync(fd, buffer, 0, buffer.length, 0) !== buffer.length) return null;
+ const value = JSON.parse(buffer.toString('utf8'));
+ if (value.version !== 1 || !Number.isSafeInteger(value.pid) || value.pid < 1 || !Number.isFinite(value.acquiredAt)
+ || typeof value.started !== 'string' || value.started.length > 100 || !/^[a-f0-9]{64}$/u.test(value.processSha256 ?? '')) return null;
+ return value;
+ } catch { return null; /* Advisory corruption/missing publication never replaces the original BOARD_BUSY refusal. */ }
+ finally {
+ if (fd !== undefined) {
+ try { closeSync(fd); }
+ catch { /* Optional marker descriptor cleanup cannot replace the original BOARD_BUSY refusal. */ }
+ }
+ }
+}
+
+/** Describe fresh observed writers, expressly advisory: SQLite and filesystem completion are not atomic. */
+export function boardWriteHolderText(file) {
+ let directory;
+ let candidates;
+ try {
+ directory = realpathSync(file) + '.write-holders';
+ if (!lstatSync(directory).isDirectory()) return '';
+ candidates = readdirSync(directory).filter(name => /^\d+-[a-f0-9-]+\.json$/u.test(name)).map(name => {
+ const path = join(directory, name);
+ try {
+ const stat = lstatSync(path);
+ return stat.isFile() ? { path, at: stat.mtimeMs } : null;
+ } catch { return null; /* A completed writer can remove its own record during this advisory read. */ }
+ }).filter(Boolean).sort((a, b) => b.at - a.at).slice(0, 32).map(row => readMarker(row.path)).filter(Boolean);
+ } catch { return ''; /* No sidecar is a normal case for older/raw SQLite writers; do not create or repair anything here. */ }
+ const live = identities(candidates.map(row => row.pid));
+ const holders = candidates.filter(row => {
+ const identity = live.get(row.pid);
+ return identity && !identity.state.startsWith('Z') && identity.started === row.started && identity.processSha256 === row.processSha256;
+ }).slice(0, 3).map(row => ({ command: label(row.command, 'unknown'), seat: label(row.seat, 'unknown'), pid: row.pid,
+ observedMs: Math.max(0, Date.now() - row.acquiredAt) }));
+ return holders.length ? '; observed writer records (advisory): ' + JSON.stringify(holders) : '';
+}
diff --git a/src/board.js b/src/board.js
index d1d63bf1..4bacf9e4 100644
--- a/src/board.js
+++ b/src/board.js
@@ -1,3 +1,9 @@
+import {
+ beginBoardWrite,
+ finishBoardWrite,
+ closeBoardWrites,
+ prepareBoardWriteIdentity,
+} from './board-write-lock.js';
import {
focusOrder,
focusReasons,
@@ -312,10 +318,10 @@ export { openBoardReadOnly } from './board-read-open.js';
*
* @param {string} file
* @param {{ now: () => Date }} [clock]
- * @param {{ isMain?: boolean, onDiagnostic?: (message: string) => void }} [options] Only the main checkout may upgrade a shared board.
+ * @param {{ isMain?: boolean, onDiagnostic?: (message: string) => void, writeContext?: {command?:string, seat?:string, path?:string} }} [options] Only the main checkout may upgrade a shared board.
* @returns {{ db: DatabaseSync, clock: { now: () => Date } }}
*/
-export function openBoard(file, clock = systemClock, { isMain, onDiagnostic } = {}) {
+export function openBoard(file, clock = systemClock, { isMain, onDiagnostic, writeContext } = {}) {
isMain = sharedSchemaOwner(file, isMain);
if (file !== ':memory:' && isMain === false) {
let boardVersion = 0;
@@ -350,13 +356,13 @@ export function openBoard(file, clock = systemClock, { isMain, onDiagnostic } =
db = new DatabaseSync(file);
db.exec(`PRAGMA busy_timeout = ${BOARD_BUSY_TIMEOUT_MS}`);
if (file !== ':memory:' && isMain !== false) db.exec('PRAGMA journal_mode = WAL');
- const board = { db, clock };
+ const board = { db, clock, writeContext };
let warmCounters = true;
if (isMain !== false || file === ':memory:') {
// Migrate and audit only a board whose version is behind; a drifted shape is reported and left alone (#1047).
const standing = boardStanding(db, SCHEMA_DIGEST, SCHEMA_VERSION, readEventLogVersion(db) < EVENT_LOG_VERSION);
if (standing === 'behind') {
- migrateEventLogVersion(db);
+ migrateEventLogVersion(db, writeContext);
migrate(db);
ensureHotIndexes(db);
db.prepare('INSERT OR IGNORE INTO board_meta (meta_key, meta_value) VALUES (?, ?)').run('board_id', randomBytes(16).toString('hex'));
@@ -383,7 +389,7 @@ export function openBoard(file, clock = systemClock, { isMain, onDiagnostic } =
if (warmCounters) atomic(board, () => ensureProofCounters(board));
return board;
} catch (error) {
- try { db?.close(); } catch {}
+ try { db?.close(); if (db) closeBoardWrites(db); } catch { /* Preserve the opening failure when SQLite cleanup also fails. */ }
throw boardNotWritable(file, boardBusyError(file, startedAt, error));
}
}
@@ -449,8 +455,11 @@ function guardStore(board) {
export { readEventLogVersion } from './board-read-open.js';
/** Refuse unknown future event records before migrating anything, and mark older boards current. */
-function migrateEventLogVersion(db) {
+function migrateEventLogVersion(db, writeContext) {
+ prepareBoardWriteIdentity();
db.exec('BEGIN IMMEDIATE');
+ const record = beginBoardWrite(db, writeContext);
+ let released = false;
try {
db.exec(SCHEMA);
const version = readEventLogVersion(db);
@@ -459,9 +468,13 @@ function migrateEventLogVersion(db) {
.run('event_log_version', String(EVENT_LOG_VERSION));
}
db.exec('COMMIT');
+ released = true;
} catch (error) {
db.exec('ROLLBACK');
+ released = true;
throw error;
+ } finally {
+ finishBoardWrite(record, released, 'migration-released');
}
}
@@ -484,23 +497,32 @@ const TRANSACTION_DEPTH = new WeakMap();
export function atomic(board, work) {
const depth = TRANSACTION_DEPTH.get(board) ?? 0;
const savepoint = `pullboard_atomic_${depth}`;
+ if (!depth) prepareBoardWriteIdentity();
const startedAt = Date.now();
try { board.db.exec(depth ? `SAVEPOINT ${savepoint}` : 'BEGIN IMMEDIATE'); }
catch (error) { throw boardWriteBusyError(board.db, startedAt, error); }
TRANSACTION_DEPTH.set(board, depth + 1);
+ const writeRecord = depth ? null : beginBoardWrite(board.db, board.writeContext);
+ let released = false;
+ let outcome = 'release-failed';
const lastEvent = board.lastEvent;
const emitted = board.emittedEvents?.length ?? 0;
try {
const result = work();
board.db.exec(depth ? `RELEASE ${savepoint}` : 'COMMIT');
+ released = true;
+ outcome = 'committed';
return result;
} catch (error) {
board.db.exec(depth ? `ROLLBACK TO ${savepoint}; RELEASE ${savepoint}` : 'ROLLBACK');
+ released = true;
+ outcome = 'rolled-back';
board.lastEvent = lastEvent;
board.emittedEvents?.splice(emitted);
throw error;
} finally {
TRANSACTION_DEPTH.set(board, depth);
+ finishBoardWrite(writeRecord, released, outcome);
}
}
diff --git a/src/cli-context.js b/src/cli-context.js
index 8f856502..9434da52 100644
--- a/src/cli-context.js
+++ b/src/cli-context.js
@@ -42,6 +42,7 @@ export {
*/
export function withBoard(ctx, work, opened) {
const board = opened ?? store.openBoard(ctx.file, ctx.clock, { isMain: ctx.allowSchemaUpgrade,
+ writeContext: { command: ctx.io.relayCommand?.cliOperation, path: ctx.info.root, ...(ctx.info.isMain ? { seat: 'coordinator' } : {}) },
/** Report each source mismatch once through this invocation's text or JSON diagnostics. */
onDiagnostic(message) {
ctx.io.schemaDiagnostics ??= new Set();
diff --git a/test/board-busy.test.js b/test/board-busy.test.js
index c4b1c7c9..8c3be0c0 100644
--- a/test/board-busy.test.js
+++ b/test/board-busy.test.js
@@ -5,6 +5,7 @@ import { after, test } from 'node:test';
import { DatabaseSync } from 'node:sqlite';
import { join, resolve } from 'node:path';
import { writeFileSync } from 'node:fs';
+import { boardWriteHolderText } from '../src/board-write-lock.js';
import { exportBoard } from '../src/exchange.js';
import { createE2eHelpers } from './e2e-helpers.js';
import { runFixtureChild, startFixtureChild } from './fixture-child.js';
@@ -164,7 +165,7 @@ test('a refused writer names the board lock holder [C7,P4,B2]', async t => {
}
assert.match(message, /private-lock-holder/u, 'the refusal names the real instrumented command');
assert.match(message, /coordinator/u, 'the refusal names the real holder seat');
- assert.match(message, new RegExp(`\b${holder.pid}\b`, 'u'), 'the refusal names the live holder PID');
+ assert.match(message, new RegExp(String.raw`\b${holder.pid}\b`, 'u'), 'the refusal names the live holder PID');
const lines = holder.stderr().split('\n').filter(line => line.startsWith('pullboard: long board write '));
assert.equal(lines.length, 1, 'only the outer transaction emits one long-write line');
const record = JSON.parse(lines[0].slice('pullboard: long board write '.length));
@@ -173,3 +174,87 @@ test('a refused writer names the board lock holder [C7,P4,B2]', async t => {
assert.equal(record.pid, holder.pid);
assert.ok(record.durationMs > 2_000, 'the real busy timeout held the writer longer than the declared 2 s threshold');
});
+
+
+/** Read only the product's structured long-write diagnostic, leaving other stderr intact. */
+function longWrites(stderr) {
+ return stderr.split('\n').filter(line => line.startsWith('pullboard: long board write '))
+ .map(line => JSON.parse(line.slice('pullboard: long board write '.length)));
+}
+
+test('a nested rolled-back writer logs once and leaves no live advisory record [C7,P4,B2]', () => {
+ const box = e2e.project();
+ const file = join(box.repo, '.git', 'pullboard', 'board.sqlite');
+ const before = snapshot(file);
+ const source = `
+ import * as store from ${JSON.stringify(new URL('../src/board.js', import.meta.url).href)};
+ const board = store.openBoard(process.argv[1], undefined, { writeContext: { command: 'private-rollback', seat: 'coordinator' } });
+ try {
+ store.atomic(board, () => store.atomic(board, () => {
+ // budget: a genuine held write must cross the product's two-second diagnostic threshold.
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2_100);
+ throw new Error('private rollback control');
+ }));
+ } catch (error) {
+ if (error.message !== 'private rollback control') throw error;
+ } finally { store.closeBoard(board); }
+ `;
+ const result = runFixtureChild(process.execPath, ['--input-type=module', '-e', source, file], {
+ cwd: box.repo, env: box.env, encoding: 'utf8',
+ });
+ assert.equal(result.status, 0, result.context);
+ const records = longWrites(result.stderr);
+ assert.equal(records.length, 1, 'nested savepoints do not duplicate the outer hold');
+ assert.equal(records[0].command, 'private-rollback');
+ assert.equal(records[0].outcome, 'rolled-back');
+ assert.ok(records[0].durationMs > 2_000);
+ assert.equal(boardWriteHolderText(file), '', 'released writers do not remain current');
+ assert.deepEqual(snapshot(file), before, 'diagnostic metadata never changes native board state');
+ const stale = join(file + '.write-holders', `${process.pid}-deadbeef.json`);
+ writeFileSync(stale, JSON.stringify({ version: 1, pid: process.pid, started: 'not this process start',
+ processSha256: 'a'.repeat(64), command: 'stale-private-writer', seat: 'coordinator', acquiredAt: Date.now() }));
+ assert.equal(boardWriteHolderText(file), '', 'a reused PID without matching identity is not a current holder');
+});
+
+test('a real CLI writer labels its long transaction without changing JSON or native counts [C7,P4,B2]', () => {
+ const box = e2e.project();
+ const file = join(box.repo, '.git', 'pullboard', 'board.sqlite');
+ const before = snapshot(file);
+ const preload = join(box.dir, 'hold-private-shout.mjs');
+ writeFileSync(preload, `
+ import { DatabaseSync } from 'node:sqlite';
+ const prepare = DatabaseSync.prototype.prepare;
+ let delayed = false;
+ /** Delay one actual private shout insertion after its outer transaction has acquired the lock. */
+ DatabaseSync.prototype.prepare = function(sql, ...args) {
+ const statement = prepare.call(this, sql, ...args);
+ if (!sql.includes('INSERT INTO shout')) return statement;
+ const run = statement.run;
+ statement.run = function(...values) {
+ if (!delayed) {
+ delayed = true;
+ // budget: exercise the genuine long-hold diagnostic, not a performance assertion.
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2_100);
+ }
+ return run.apply(this, values);
+ };
+ return statement;
+ };
+ `);
+ const result = runFixtureChild(process.execPath, ['--import', preload, BIN, 'shout', 'all', 'private timed shout', '--json'], {
+ cwd: box.web, env: box.env, encoding: 'utf8',
+ });
+ assert.equal(result.status, 0, result.context);
+ assert.equal(JSON.parse(result.stdout).version, 1, 'the diagnostic stays off JSON stdout');
+ const records = longWrites(result.stderr);
+ assert.equal(records.length, 1);
+ assert.equal(records[0].command, 'shout');
+ assert.equal(records[0].seat, 'web-1');
+ assert.equal(records[0].outcome, 'committed');
+ assert.ok(Number.isSafeInteger(records[0].pid));
+ assert.ok(records[0].durationMs > 2_000);
+ const after = snapshot(file);
+ assert.equal(after.tables.shout.length, before.tables.shout.length + 1);
+ assert.equal(after.tables.event.length, before.tables.event.length + 1);
+ assert.equal(boardWriteHolderText(file), '');
+});