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.

chore(core): compose provenance with lightweight readers [C7,H16]

Corey Olson976ea44689e2
diff --cc src/board-query.js
index 00000000,e53f5b04..f1072d44
mode 000000,100644..100644
--- a/src/board-query.js
+++ b/src/board-query.js
@@@ -1,0 -1,426 +1,433 @@@
+ import {
+ COORDINATION_SHOUT,
+ itemShoutReader,
+ shoutItemId,
+ UNREAD_SHOUT_SQL,
+ unreadShoutBindings,
+ } from './shout-audience.js';
+ /** Canonical board queries shared by reads and the synchronous write store [C7]. */
+ import { COORDINATOR } from './config.js';
+ import { itemFiles } from './item-files.js';
+ import { parseSpec } from './spec.js';
+ import { BOARD_SENTINEL_ENGINE } from './sentinel-engine.js';
+ import { Refused } from './refused.js';
+ export { closeBoard, openBoardForRead, openBoardReadOnly, readEventLogVersion, systemClock } from './board-read-open.js';
+ export { schemaMissing, writeRefused } from './board-migrate.js';
+ export { stats } from './board-stats.js';
+ export { submitInvariantEvents } from './board-hot.js';
+ export { acceptedVerdict, verdictReviewProblem, verdictsFor } from './verdict-reviews.js';
+
+ export const PERSON = 'person';
+
+ /**
+ * The board's time as ISO text.
+ *
+ * @param {any} board
+ * @returns {string}
+ */
+ export const now = (board) => board.clock.now().toISOString();
+
+ /**
+ * True while someone holds the item under a lease that has not lapsed.
+ *
+ * @param {any} board
+ * @param {any} item
+ * @returns {boolean}
+ */
+ export function isHeld(board, item) {
+ return item.item_status === 'claimed' && (item.item_lease_until ?? '') > now(board);
+ }
+
+ /**
+ * The item as a reader should see it: a claim whose lease lapsed reads as open (B4).
+ *
+ * @param {any} board
+ * @param {any} item
+ * @returns {any}
+ */
+ export function current(board, item) {
+ if (item.item_status !== 'claimed' || isHeld(board, item)) return { ...item };
+ return { ...item, item_status: 'open', item_owner: null, item_lease_until: null };
+ }
+
+ /** Read an observation only when it still describes the item's current check command. */
+ export function itemCheckBaseline(board, item) {
+ const row = board.db.prepare('SELECT meta_value FROM board_meta WHERE meta_key = ?').get(`item_check_baseline_${item.item_id}`);
+ if (!row) return null;
+ const baseline = JSON.parse(row.meta_value);
+ return baseline.command === item.item_check ? baseline : null;
+ }
+
+ /** Find review releases after the current submission, optionally for one reviewer [V1,R1].
+ * Older releases are ignored because a new submission starts a fresh review.
+ */
+ export function reviewReleasesSinceSubmit(board, itemId, agentId = null) {
+ const events = board.db.prepare("SELECT event_id, event_at, event_by, event_kind, event_detail FROM event WHERE item_id=? AND event_kind IN ('submit','release') ORDER BY event_id DESC")
+ .all(itemId);
+ const releases = [];
+ for (const event of events) {
+ if (event.event_kind === 'submit') return releases;
+ if (event.event_by !== agentId && agentId !== null) continue;
+ try {
+ const detail = JSON.parse(event.event_detail);
+ if (detail.review === true || detail.review === undefined) releases.push({ ...event, legacy: detail.review === undefined,
+ reason: detail.reason ?? 'reason not recorded' });
+ } catch { /* Ignore malformed legacy details rather than treating them as review releases. */ }
+ }
+ return releases;
+ }
+
+ /** The persistent local and relay identity of this board (A2). */
+ export function boardId(board) {
+ return board.db.prepare('SELECT meta_value FROM board_meta WHERE meta_key = ?').get('board_id').meta_value;
+ }
+
+ /**
+ * The item with this id, or a refusal naming the id.
+ *
+ * @param {any} board
+ * @param {number} id
+ * @returns {any}
+ */
+ export function itemById(board, id) {
+ const item = board.db.prepare('SELECT * FROM item WHERE item_id = ?').get(id);
+ if (!item) throw new Refused('NO_ITEM', `no item #${id}; see: pullboard list`);
+ return item;
+ }
+
+ /**
+ * One item as a reader should see it.
+ *
+ * @param {any} board
+ * @param {number} id
+ * @returns {any}
+ */
+ export function getItem(board, id) {
+ const item = current(board, itemById(board, id));
+ const baseline = itemCheckBaseline(board, item);
+ return baseline ? { ...item, item_check_baseline: baseline } : item;
+ }
+
+ /**
+ * Items, newest first, as a reader should see them. Closed items (verified, withdrawn) only when
+ * asked.
+ *
+ * @param {any} board
+ * @param {{ lane?: string, all?: boolean }} [filter]
+ * @returns {any[]}
+ */
+ export function listItems(board, { lane, all = false } = {}) {
+ const hasLane = lane !== undefined && lane !== null;
+ const rows = board.db
+ .prepare(`SELECT * FROM item WHERE ${all ? '1' : "item_status NOT IN ('verified','withdrawn')"}${hasLane ? ' AND item_lane=?' : ''} ORDER BY item_id DESC`)
+ .all(...(hasLane ? [lane] : []));
+ const items = rows.map((item) => current(board, item));
+ return items;
+ }
+
+ /** Read a stored status/owner slice, excluding claims whose leases have expired rather than caching items. */
+ export function itemsInStatus(board, status, owner = null) {
+ return board.db.prepare(`SELECT * FROM item WHERE item_status=?${owner === null ? '' : ' AND item_owner=?'} ORDER BY item_id DESC`)
+ .all(status, ...(owner === null ? [] : [owner])).map(item => current(board, item)).filter(item => item.item_status === status);
+ }
+
+ /**
+ * Who holds an item's review under a live lease (V15), or null. A reservation counts only while the
+ * item is submitted and its lease has not run out, and a new submission starts with none.
+ *
+ * @param {any} board
+ * @param {any} item
+ * @returns {string | null}
+ */
+ export function reviewHolder(board, item) {
+ return item.item_status === 'submitted' && item.item_review_by && (item.item_review_until ?? '') > now(board) ? item.item_review_by : null;
+ }
+
+ /** Count unreserved submissions by whether they are awaiting a first reviewer or were released [R1]. */
+ export function reviewQueueBreakdown(board) {
+ let awaitingFirstReview = 0;
+ let releasedWithoutVerdict = 0;
+ const releasedItems = [];
+ for (const item of itemsInStatus(board, 'submitted').filter((entry) => !reviewHolder(board, entry))) {
+ const releases = reviewReleasesSinceSubmit(board, item.item_id);
+ if (releases.length) {
+ releasedWithoutVerdict += 1;
+ releasedItems.push({ item: item.item_id, releases: releases.length, reason: releases[0].reason });
+ } else awaitingFirstReview += 1;
+ }
+ return { awaitingFirstReview, releasedWithoutVerdict, releasedItems };
+ }
+
+ /** Summarize outstanding reviews using live leases and the latest submission's age [Q1,V15]. */
+ export function reviewQueue(board) {
+ const pending = itemsInStatus(board, 'submitted');
+ const holders = pending.map((item) => reviewHolder(board, item)).filter(Boolean);
+ // Only the current queue needs an age. Seek each item's history, including legacy timestamps,
+ // instead of grouping every submission ever made on the board.
+ const submittedAt = board.db.prepare("SELECT MAX(event_at) AS at FROM event WHERE item_id=? AND event_kind='submit'");
+ const oldestSubmittedAt = pending.map((item) => submittedAt.get(item.item_id).at).filter(Boolean).sort()[0] ?? null;
+ return { pending: pending.length, reviewing: new Set(holders).size, reserved: holders.length, oldestSubmittedAt,
+ ageMs: oldestSubmittedAt ? Math.max(0, board.clock.now().getTime() - Date.parse(oldestSubmittedAt)) : 0 };
+ }
+
+ /**
+ * Shouts that asked for a decision nobody has answered yet, oldest first (B21). An optional
+ * recipient limits the queue; an array matches any listed recipient. Without one this returns
+ * every open decision for internal readers.
+ *
+ * @param {any} board
+ * @param {string | string[]} [recipient]
+ * @returns {any[]}
+ */
+ export function openDecisions(board, recipient = null) {
+ if (recipient === null) {
+ return board.db
+ .prepare('SELECT * FROM shout ask WHERE ask.shout_decision = 1 AND NOT EXISTS (SELECT 1 FROM shout reply WHERE reply.shout_answers = ask.shout_id) ORDER BY ask.shout_id')
+ .all();
+ }
+ const recipients = [...new Set(Array.isArray(recipient) ? recipient : [recipient])];
+ if (!recipients.length) return [];
+ return openDecisions(board).filter((ask) => recipients.includes(ask.shout_to)
+ || (ask.shout_to === COORDINATION_SHOUT && recipients.includes(COORDINATOR))
+ || (shoutItemId(ask.shout_to) !== null && recipients.some((agent) => itemShoutReader(board.db, shoutItemId(ask.shout_to), agent))));
+ }
+
+ /**
+ * How many shouts an agent has not read, without marking them.
+ *
+ * @param {any} board
+ * @param {string} agentId
+ * @returns {number}
+ */
+ export function unreadCount(board, agentId) {
+ const agent = board.db.prepare('SELECT * FROM agent WHERE agent_id = ?').get(agentId);
+ if (!agent) return 0;
+ const { total } = board.db
+ .prepare(`SELECT COUNT(*) AS total ${UNREAD_SQL}`)
+ .get(...unreadShoutBindings(agent.agent_last_shout_id, agentId, agent.agent_lane));
+ return total;
+ }
+
+ /**
+ * The event log, oldest first, for one item or the whole board.
+ *
+ * @param {any} board
+ * @param {{ itemId?: number }} [filter]
+ * @returns {any[]}
+ */
+ export function events(board, { itemId } = {}) {
+ if (itemId === undefined || itemId === null) {
+ return board.db.prepare('SELECT * FROM event ORDER BY event_id').all();
+ }
+ return board.db.prepare('SELECT * FROM event WHERE item_id = ? ORDER BY event_id').all(itemId);
+ }
+
+ /** Read every move and fact in append order, including superseded facts and full original text [B31,B32]. */
+ export function itemThread(board, id) {
+ itemById(board, id);
+ return events(board, { itemId: id }).map((event) => event.event_kind === 'fact'
+ ? { type: 'fact', ...factFromEvent(event) }
+ : { type: 'move', eventId: event.event_id, kind: event.event_kind, by: event.event_by,
+ at: event.event_at, detail: JSON.parse(event.event_detail) });
+ }
+
+ /**
+ * Every held lane.
+ *
+ * @param {any} board
+ * @returns {any[]}
+ */
+ export function laneHolds(board) {
+ return board.db.prepare('SELECT * FROM hold ORDER BY hold_lane').all();
+ }
+
+ /** Current person decisions, including applied receipts, stored without checkout-dependent state. */
+ export function rowDecisions(board) {
+ const row = board.db.prepare('SELECT meta_value FROM board_meta WHERE meta_key=?').get('row_decisions');
+ return row ? JSON.parse(row.meta_value) : [];
+ }
+
+ /**
+ * The SQL that picks an agent's unread shouts: to it, to its lane, or to all, from anyone else.
+ */
+ export const UNREAD_SQL = UNREAD_SHOUT_SQL;
+
+ /**
+ * The agent registered for a worktree path, if any.
+ *
+ * @param {any} board
+ * @param {string} path
+ * @returns {any}
+ */
+ export function agentAt(board, path) {
+ const agent = board.db.prepare('SELECT * FROM agent WHERE agent_path = ?').get(path);
+ return withModel(board, agent);
+ }
+
+ /** Read one seat and its model without loading every registered seat and model on the board. */
+ export function agentById(board, id) {
+ return withModel(board, board.db.prepare('SELECT * FROM agent WHERE agent_id = ?').get(id));
+ }
+
+ /** Read the model label kept beside other board metadata, avoiding any board-schema migration. */
+ export function agentModel(board, id) {
+ return board.db.prepare('SELECT meta_value FROM board_meta WHERE meta_key = ?').get(`agent_model:${id}`)?.meta_value ?? null;
+ }
+
+ /** Attach an agent's model to a row from the legacy stable agent table. */
+ export function withModel(board, agent) {
+ return agent ? { ...agent, agent_model: agentModel(board, agent.agent_id), agent_parent_session: agentParent(board, agent.agent_id) } : agent;
+ }
+
+ /**
+ * Every registered agent, oldest first.
+ *
+ * @param {any} board
+ * @returns {any[]}
+ */
+ export function listAgents(board) {
+ return board.db.prepare(`SELECT agent.*, board_meta.meta_value AS agent_model FROM agent
+ LEFT JOIN board_meta ON board_meta.meta_key='agent_model:' || agent.agent_id ORDER BY agent.rowid`).all().map(agent => ({ ...agent, agent_parent_session: agentParent(board, agent.agent_id) }));
+ }
+
+ /** The optional engine-20 fields of a fact, present only when its event set them. */
+ export function decisionFields(detail) {
+ return { ...(detail.implies ? { implies: detail.implies } : {}), ...(detail.decision ? { decision: detail.decision } : {}),
+ ...(detail.supersededBy ? { supersededBy: detail.supersededBy } : {}) };
+ }
+
+ /** Give facts the same stamped identity on CLI, API, export and replica reads; a never-again keeps its cause [B29,B31,D1]. */
+ export function factFromEvent(event) {
+ const detail = JSON.parse(event.event_detail);
+ return { id: detail.id, eventId: event.event_id, kind: detail.kind, text: detail.text,
+ by: event.event_by, at: event.event_at, ref: detail.ref ?? null, supersedes: detail.supersedes ?? null, ...decisionFields(detail),
+ ...(detail.neverAgain ? { cause: detail.cause, neverAgain: true } : {}) };
+ }
+
+ export const KEY = 'spec_approval_baseline';
+
+ /** Validate the exact source carried by an ordered snapshot, including the empty initial set. */
+ export function validBaseline(value) {
+ if (!value || value.version !== 1 || typeof value.file !== 'string' || !value.file
+ || !(value.anchor === null || /^[a-f0-9]{40,64}$/u.test(value.anchor)) || !Array.isArray(value.rows)) return false;
+ const seen = new Set();
+ return value.rows.every(row => {
+ if (!row || typeof row.id !== 'string' || typeof row.text !== 'string' || typeof row.source !== 'string'
+ || /[\r\n]/u.test(row.source) || seen.has(row.id)) return false;
+ const parsed = parseSpec(`## Baseline\n${row.source}\n`).rows;
+ seen.add(row.id);
+ return parsed.length === 1 && parsed[0].id === row.id && parsed[0].text === row.text && parsed[0].status === 'approved';
+ });
+ }
+
+ /** Compare the snapshot payload without incidental event attribution or JSON property order. */
+ export function canonicalBaseline(baseline) {
+ return { version: 1, file: baseline.file, anchor: baseline.anchor,
+ rows: baseline.rows.map(({ id, text, source }) => ({ id, text, source })) };
+ }
+
+ /** Distinguish a missing migration marker from an unreadable one without replacing either. */
+ export function specApprovalBaselineExists(board) {
+ return Boolean(board.db.prepare('SELECT 1 FROM board_meta WHERE meta_key=?').get(KEY)
+ || board.db.prepare('SELECT 1 FROM event WHERE event_kind=? LIMIT 1').get(KEY));
+ }
+
+ /** Read the original snapshot without interpreting it as authenticated approval or reseeding it. */
+ export function specApprovalBaseline(board) {
+ const stored = board.db.prepare('SELECT meta_value FROM board_meta WHERE meta_key=?').get(KEY);
+ const events = board.db.prepare('SELECT event_by,event_detail FROM event WHERE event_kind=?').all(KEY);
+ if (!stored && !events.length) return null;
+ let value;
+ let recorded;
+ try {
+ value = stored && JSON.parse(stored.meta_value);
+ recorded = events.length === 1 && events[0].event_by === COORDINATOR && JSON.parse(events[0].event_detail);
+ } catch { /* The same typed recovery covers malformed and incompatible records. */ }
+ if (!validBaseline(value) || !validBaseline(recorded)
+ || JSON.stringify(canonicalBaseline(value)) !== JSON.stringify(canonicalBaseline(recorded))) {
+ throw new Refused('SPEC_APPROVAL_BASELINE', 'the approval baseline is unreadable or disagrees with its original event; restore it from a known-good board export');
+ }
+ return value;
+ }
+
+ /** Pending watches are the person's calls: one Needs-you entry each, with the evidence that proposed it. */
+ export function sentinelDraftNeeds(rows) {
+ return rows.filter(row => row.status === 'pending').map(row => ({
+ kind: 'sentinel-draft', id: `sentinel:${row.name}`, ref: row.name,
+ check: row.check, directory: row.directory, every: row.every, owner: row.owner, digest: row.digest,
+ text: `Sentinel draft: ${row.name} runs ${row.check} ${row.every === 'daily' || row.every === 'hourly' ? row.every : 'every ' + row.every}, reporting to ${row.owner}`,
+ what: `pullboard sentinel approve ${row.name}, or decline it with --reason`, target: `sentinel:${row.name}`,
+ ...(row.evidence ? { cause: row.evidence.key, evidence: row.evidence } : {}),
+ }));
+ }
+
+ /** Read only allocated receipts; legacy events with similar names never enable command execution. */
+ export function sentinels(board) {
+ const rows = new Map();
+ const events = board.db.prepare("SELECT * FROM event WHERE event_kind IN ('sentinel-proposal','sentinel-decision','sentinel-start','sentinel-run') ORDER BY event_id").all();
+ for (const event of events) {
+ const detail = JSON.parse(event.event_detail);
+ if (detail.engine !== BOARD_SENTINEL_ENGINE) continue;
+ if (event.event_kind === 'sentinel-proposal') {
+ rows.set(detail.row.name, { ...detail.row, digest: detail.digest, status: 'pending', proposedBy: event.event_by,
+ proposedAt: event.event_at, evidence: detail.evidence ?? null, lastRun: null, activeRun: null, history: [] });
+ continue;
+ }
+ const row = rows.get(detail.name);
+ if (!row || row.digest !== detail.digest) continue;
+ if (event.event_kind === 'sentinel-decision' && event.event_by === PERSON) {
+ row.status = detail.decision === 'approve' ? 'approved' : 'declined';
+ row.reason = detail.reason; row.decidedAt = event.event_at; row.activeRun = null;
+ } else if (event.event_kind === 'sentinel-start') {
+ row.activeRun = { id: detail.run, by: event.event_by, startedAt: event.event_at, until: detail.until };
+ } else if (event.event_kind === 'sentinel-run' && row.activeRun?.id === detail.run) {
+ row.lastRun = { ...detail.result, id: detail.run, at: event.event_at };
+ row.history.push(row.lastRun); row.activeRun = null;
+ }
+ }
+ return [...rows.values()];
+ }
+
+ /** Ask the CLI adapter for the original coordinator-housekeeping write path. */
+ export class ReadNeedsWrite extends Error {}
+
+ /** A matching coordinator needs no write; registration or a path change uses the full store. */
+ export function ensureCoordinator(board, path) {
+ const existing = agentById(board, COORDINATOR);
+ if (!existing || existing.agent_path !== path) throw new ReadNeedsWrite('coordinator registration or path update requires the write store');
+ return COORDINATOR;
+ }
+
+ /**
+ * Finished items that touched the same files as this one, most shared first (N21). A builder
+ * starting cold reads how its neighbours were done instead of rediscovering it. File overlap, not
+ * word similarity: in one real build, an item shared a source file with one of the three before it
+ * in its lane 56% of the time.
+ *
+ * @param {any} board
+ * @param {any} item
+ * @param {number} [limit]
+ * @returns {{ item: any, shared: string[] }[]}
+ */
+ export function relatedItems(board, item, limit = 3) {
+ const mine = new Set(itemFiles(item));
+ if (!mine.size) return [];
+ return listItems(board, { all: true })
+ .filter((other) => other.item_id !== item.item_id && other.item_status === 'verified')
+ .map((other) => ({ item: other, shared: itemFiles(other).filter((path) => mine.has(path)) }))
+ .filter((entry) => entry.shared.length)
+ .sort((first, second) => second.shared.length - first.shared.length || second.item.item_id - first.item.item_id)
+ .slice(0, limit);
+ }
+
+ /** Read a seat's immutable parent session digest; unknown parents remain separate seats. */
+ export function agentParent(board, id) {
+ return board.db.prepare('SELECT meta_value FROM board_meta WHERE meta_key = ?').get(`agent_parent_session:${id}`)?.meta_value ?? null;
+ }
++
++/** Every stamped receipt for one item, in recorded order. */
++export function proofReceipts(board, itemId) {
++ return board.db.prepare("SELECT event_id, event_detail FROM event WHERE item_id = ? AND event_kind = 'proof-run' ORDER BY event_id").all(itemId)
++ .map(row => ({ eventId: row.event_id, ...JSON.parse(row.event_detail).receipt }));
++}
++
diff --cc src/commands/show.js
index 19595080,034fa2c1..3d6e1c71
--- a/src/commands/show.js
+++ b/src/commands/show.js
@@@ -31,34 -32,35 +32,37 @@@ import
idArg,
itemLine,
sayBrief,
- withBoardRead,
- } from '../cli.js';
- import { relayStatus } from '../relay.js';
+ } from '../cli-read-context.js';
+ import { relayStateExists } from '../local-state.js';
/** Run `pullboard show` and return its exit code. */
- export function run(io, { first, values }) {
+ export async function run(io, { first, values }) {
const ctx = context(io);
const id = idArg(first);
- const { item, verdicts, moves, thread, related, reviewer, agents, mainMerge, infra, approval, proofReceipts } = withBoardRead(ctx, (board) => ({
- item: verdictProjector(ctx.info.root, board).project(store.getItem(board, id)),
- verdicts: store.verdictsFor(board, id),
- moves: store.events(board, { itemId: id }).filter((event) => ['attempt', 'escalate'].includes(event.event_kind)),
- thread: store.itemThread(board, id),
- related: store.relatedItems(board, store.getItem(board, id)),
- reviewer: store.reviewHolder(board, store.getItem(board, id)),
- agents: store.listAgents(board), mainMerge: mainMergeFor(board, id), infra: infraNotes.infraNoteOf(store.events(board, { itemId: id })),
- approval: specApprovalState(ctx.info.root, { board, config: ctx.config }),
- proofReceipts: store.proofReceipts(board, id),
- }));
- const agentName = (id) => displayAgentName(agents.find((agent) => agent.agent_id === id) ?? { agent_id: id }, ctx.config.agents.names);
- const { item, verdicts, moves, thread, related, reviewer, agents, mainMerge, infra, approval } = await withBoardRead(ctx, (board) => {
++ const { item, verdicts, moves, thread, related, reviewer, agents, mainMerge, infra, approval, proofReceipts } = await withBoardRead(ctx, (board) => {
+ const item = verdictProjector(ctx.info.root, board).project(store.getItem(board, id));
+ const result = { item, verdicts: store.verdictsFor(board, id), thread: store.itemThread(board, id),
++ proofReceipts: store.proofReceipts(board, id),
+ approval: specApprovalState(ctx.info.root, { board, config: ctx.config }) };
+ // JSON retains every public detail field; text-only labels and related-item searches add nothing to it.
+ if (values.json) return result;
+ const history = store.events(board, { itemId: id });
+ return { ...result, moves: history.filter((event) => ['attempt', 'escalate'].includes(event.event_kind)),
+ related: store.relatedItems(board, item), reviewer: store.reviewHolder(board, item),
+ agents: store.listAgents(board), mainMerge: mainMergeFor(board, id), infra: infraNotes.infraNoteOf(history) };
+ });
++
const agentApproved = itemAgentApprovals(item, approval);
const approvalQualification = agentApprovalLine(agentApproved);
// #922: moves on this item made while the relay was down wait in this machine's relay outbox until it answers.
- const relayPending = (relayStatus(ctx.info.root).outbox ?? []).filter((move) => move.item === id);
+ // Without a relay link or deleted-copy notice there is no outbox to read, so the relay client never loads.
+ const outbox = relayStateExists(ctx.info.commonDir) ? (await import('../relay.js')).relayStatus(ctx.info.root).outbox : undefined;
+ const relayPending = (outbox ?? []).filter((move) => move.item === id);
if (values.json) {
- io.result({ ...item, verdicts, thread, agentApproved, approvalQualification, ...(relayPending.length ? { relayPending } : {}) });
+ io.result({ ...item, verdicts, thread, proofReceipts, agentApproved, approvalQualification, ...(relayPending.length ? { relayPending } : {}) });
return 0;
}
+ const agentName = (id) => displayAgentName(agents.find((agent) => agent.agent_id === id) ?? { agent_id: id }, ctx.config.agents.names);
io.say(itemLine(item, agentName, Boolean(mainMerge)));
if (item.item_status === 'verified' && approvalQualification) io.say(approvalQualification);
if (item.item_verdict_state) io.say(staleVerdictRefusal(item, item.item_verdict_state).message);
diff --cc src/gate.js
index add340f8,82d170ab..e2db81c7
--- a/src/gate.js
+++ b/src/gate.js
@@@ -266,57 -191,6 +198,7 @@@ export function isStampedGreen(root)
return tree !== null && existsSync(file) && readFileSync(file, 'utf8').trim() === tree;
}
- /**
- * Run a shell command in a checkout for a digest: both streams in one pipe, in order, read whole
- * however long, stdin closed so nothing waits on a person. With `stages`, each top-level stage's
- * exit status and own output are kept too, or `stages` is null when the command cannot be split.
- *
- * @param {string} root
- * @param {string} command
- * @param {{ pipefail?: boolean, env?: NodeJS.ProcessEnv, stages?: boolean, timeoutMs?: number }} [options] - Gate-only pipefail, additional child environment values and per-stage accounting.
- * @returns {{ isGreen: boolean, output: string, seconds: number, sandboxBlocked: string|null, stages?: Array<{ status: number|null, output: string, pipeline?: Array<{ status: number|null, output: string|null }> }> | null }}
- */
- export function runShell(root, command, { pipefail = false, env = {}, stages = false, timeoutMs } = {}) {
- const started = Date.now();
- const environment = executionEnvironment();
- const options = { cwd: root, env: { ...gitChildEnv(root), ...env }, shell: true, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8', maxBuffer: 2 ** 30 };
- let prefix = '';
- if (pipefail) {
- // Probe the same shell as the command, with no load-sensitive deadline or alternate shell.
- const probe = spawnSync('set -o pipefail', options);
- if (probe.status === 0) prefix = 'set -o pipefail\n';
- else if (hasPipeline(command)) {
- throw new Refused('PIPEFAIL_UNAVAILABLE', 'the repo gate shell cannot enable pipefail; rewrite the gate without a pipe');
- }
- }
- const split = stages ? gateStages(command) : null;
- const marker = `PULLBOARD_STAGE_${randomUUID().replaceAll('-', '')}`;
- const pipes = split?.some((stage) => stage.pipeline.length > 1) ? mkdtempSync(join(tmpdir(), 'pullboard-pipes-')) : null;
- // Newlines, not spaces, around the command, so a trailing comment in it cannot swallow the `)`.
- const script = `${prefix}(\n${split ? stagedScript(split, marker, pipes) : command}\n) 2>&1`;
- const timedDirectory = timeoutMs ? mkdtempSync(join(tmpdir(), 'pullboard-timed-output-')) : null;
- const outputFile = timedDirectory ? join(timedDirectory, 'output.log') : null;
- const timed = timeoutMs ? spawnSync(process.execPath, [fileURLToPath(new URL('./timed-shell-worker.js', import.meta.url))], { ...options, shell: false, stdio: ['pipe', 'pipe', 'pipe'], input: JSON.stringify({ command: script, timeoutMs, outputFile }) }) : null;
- if (timed && (timed.status !== 0 || timed.error)) throw new Refused('LAND_TIMEOUT_CUSTODY', 'the timed gate worker did not prove cleanup; inspect its owned processes before landing again');
- const result = timed ? { ...JSON.parse(timed.stdout || '{}'), stdout: '', stderr: timed.stderr } : spawnSync(script, options);
- if (timed && result.error) throw new Refused('LAND_GATE_OUTPUT', `the timed gate stopped and drained after its output failed (${result.error}); inspect free disk space and ${timedDirectory} before landing again`);
- if (timed) result.stdout = readFileSync(outputFile, 'utf8') + (result.timedOut ? `\n[LAND_GATE_TIMEOUT] landing gate exceeded ${timeoutMs}ms; its owned processes are stopped\n` : '');
- if (timedDirectory) rmSync(timedDirectory, { recursive: true, force: true });
- if (result.timedOut || result.overflow || result.error) result.status = 1;
- invalidateGitFacts();
- const pipeStatuses = pipes ? readPipes(split, pipes) : null;
- if (pipes) rmSync(pipes, { recursive: true, force: true });
- const raw = `${result.stdout ?? ''}${result.stderr ?? ''}`;
- const seconds = Math.round((Date.now() - started) / 1000);
- const blocked = (output) => (result.status === 0 ? null : sandboxBlockedOperation(root, output));
- if (!stages) return { isGreen: result.status === 0, exitCode: result.status, output: raw, seconds, environment, ...(timed ? { timedOut: result.timedOut } : {}), sandboxBlocked: blocked(raw) };
- if (!split) return { isGreen: result.status === 0, exitCode: result.status, output: raw, seconds, environment, stages: null, ...(timed ? { timedOut: result.timedOut } : {}), sandboxBlocked: blocked(raw) };
- const staged = readStages(raw, marker, split.length);
- // Each pipeline component's own status rides on its stage, so no failing producer hides behind a later one.
- const withPipes = staged.stages.map((stage, index) => (pipeStatuses?.[index] ? { ...stage, pipeline: pipeStatuses[index] } : stage));
- return { isGreen: result.status === 0, exitCode: result.status, seconds, environment, ...(timed ? { timedOut: result.timedOut } : {}), ...staged, stages: withPipes, sandboxBlocked: blocked(staged.output) };
- }
+
/** Refuse an environment-blocked proof after its ordinary raw logs and timings are persisted. */
export function refuseSandboxBlocked(run) {
if (run.sandboxBlocked) throw new Refused('SANDBOX_BLOCKED',
diff --cc src/next-step-words.js
index 00000000,cb930781..97c9365a
mode 000000,100644..100644
--- a/src/next-step-words.js
+++ b/src/next-step-words.js
@@@ -1,0 -1,599 +1,604 @@@
+ /** Pure refusal guidance shared by JSON and CLI output without loading ledger or Git [P4,W4,C7]. */
+ import { RECORDED_GENERIC_NEXT } from './recorded-refusal.js';
+
+ /** The coordinator carries every seat's request for a person decision [B26]. */
+ export const COORDINATOR_PERSON_REQUEST = 'ask the coordinator to bring it to the person: pullboard shout coordinator "<what is needed>" --decision';
+
+ /**
+ * Route presentation-only person requests for a known seat; unknown callers retain existing text.
+ * This does not change a refusal receipt, actor identity or permission to make the person's move.
+ *
+ * @param {string} step
+ * @param {{ caller?: 'seat'|'coordinator'|'person'|'unknown' }} [options]
+ * @returns {string}
+ */
+ export function personRequestStep(step, { caller } = {}) {
+ return caller === 'seat' && /\bask the person\b/iu.test(step) ? COORDINATOR_PERSON_REQUEST : step;
+ }
+
+ /** Keep quoted user text out of generated repair-clause rewriting. */
+ function quotedAt(text, at) {
+ let quoted = false;
+ let escaped = false;
+ for (let index = 0; index < at; index += 1) {
+ if (escaped) { escaped = false; continue; }
+ if (text[index] === '\\') { escaped = true; continue; }
+ if (text[index] === '"') quoted = !quoted;
+ }
+ return quoted;
+ }
+
+ /**
+ * Present a generated person-request clause for a seat, keeping its reason and requested action.
+ * Only the explanatory first line and an explicit final next footer are guidance; raw diagnostic
+ * lines and quoted user text remain intact. Setup questions opt in to a leading imperative.
+ *
+ * @param {string} message
+ * @param {{ caller?: 'seat'|'coordinator'|'person'|'unknown', leading?: boolean }} [options]
+ * @returns {string}
+ */
+ export function personRequestGuidance(message, { caller, leading = false } = {}) {
+ if (caller !== 'seat') return message;
+ const lines = String(message).split('\n');
+ /** Route only an unquoted imperative, preserving clauses that explain the refusal. */
+ const route = line => line.replace(/(^|[;.:]\s+|\b(?:or|and)\s+)ask the person(?=$|[\s:;])([^;\n]*)/giu,
+ (whole, before, action, at) => {
+ if ((!before && !leading) || quotedAt(line, at + before.length)) return whole;
+ const request = action.trim().replace(/^:?\s*(?:to\s+|for\s+)?/iu, '');
+ const needed = request.replace(/\bask the person(?:\s+to)?\s*/giu,
+ (words, offset) => quotedAt(request, offset) ? words : '');
+ return `${before}${COORDINATOR_PERSON_REQUEST}${needed ? ` (needed: ${needed})` : ''}`;
+ });
+ lines[0] = route(lines[0]);
+ if (lines.length > 1 && /^next:[ \t]*\S/u.test(lines.at(-1))) lines[lines.length - 1] = route(lines.at(-1));
+ return lines.join('\n');
+ }
+
+ /** @type {Readonly<Record<string, string>>} */
+ export const NEXT_STEPS = Object.freeze({
++ PROOF_RUN_UNAVAILABLE: 'restore writable native receipt storage, run the item check with current Pullboard, then read pullboard show <id>',
++ PROOF_RUN_UNBOUND: 'run the item check with current Pullboard and use its stored native receipt; read pullboard show <id> for the proof chain',
++ PROOF_RUN_ACTOR: 'run the check from your own joined seat and use the native receipt that belongs to that seat',
++ PROOF_RUN_STALE: 'read pullboard show <id> for the current frozen criterion, then run a fresh item check',
++ PROOF_RUN_CHANGED: 'preserve the original receipt and run a new item check to obtain a new native receipt id',
+ ACCOUNT_STORAGE_LIMIT: 'remove an unneeded relay copy through the approved phone flow, or ask the relay operator to increase the account quota; uploads resume when space is available',
+ BAD_PAGE: 'retry the saved upload with a current linked CLI; send only its original bounded encrypted objects',
+ BAD_PAGE_PATH: 'refresh the board on the phone, then follow the encrypted references from its new read pin',
+ BAD_SENDER: 'use the authenticated board credential belonging to the acting person, machine or agent, then retry',
+ BAD_SEQUENCE: 'refresh the relay head and retry the saved operation at its declared coverage sequence; keep the durable pending record',
+ FLAKE_EVIDENCE: 'retain the original gate log, timing profile and pinned source; ask the coordinator to repair the failure-evidence recorder before recording again',
+ GATE_RUN_EVIDENCE: 'run the gate again from a clean, committed checkout so the run can name its tree, its failing test ids and the host load',
+ GATE_RUN_UNBOUND: 'run the gate on this machine; it stores its own receipt and records its runs itself, and a run written by hand never counts',
+ GATE_RUN_CHANGED: 'keep the original gate run unchanged; record a new run with a new id instead of replacing historical evidence',
+ FLAKE_OBSERVATION_CHANGED: 'keep the original observation unchanged; record a new gate failure with a new observation identity instead of replacing historical evidence',
+ CI_RESULT: 'save each CI attempt as a ci-result.json manifest beside its TAP file (provider, run, attempt, job, runner, node, commit, root, conclusion, at, tap), then run pullboard flakes import <folder> again',
+ CI_COMMIT_UNKNOWN: 'fetch the CI commit into this checkout with git fetch origin <commit>, then run pullboard flakes import <folder> again',
+ HEALTH_FINDINGS: 'run pullboard health to read the current findings, then run pullboard resume to capture a fresh observation',
+ HEALTH_SCAN_STALE: 'run pullboard resume again to scan the current board before posting sentinel notices',
+ A5_GRAMMAR_VERSION: 'upgrade Pullboard: npm install -g pullboard@latest',
+ AGENT_SESSION: 'run pullboard takeover from the agent session that should own this checkout',
+ ALREADY_ANSWERED: 'read the answer with pullboard inbox; ask again with a new pullboard shout <to> "<text>" --decision',
+ ALREADY_JOINED: 'create a worktree for the other lane: pullboard worktree <lane> --model "<model name>", then work from the path it prints',
+ ALREADY_MERGED: 'file the follow-up as a new item: pullboard add <lane> "<title>"',
+ AMBIGUOUS: 'name the code with an explicit line range: path:line-line@commit',
+ API_ORIGIN: 'call the API from the address pullboard serve printed',
+ API_LISTEN: 'choose a free port with --port 0, then retry pullboard serve',
+ API_POLL: 'pass a poll interval from 10 to 60000 milliseconds',
+ APPROVED_ROW_CHANGE: 'restore the committed file: git checkout HEAD -- <file>',
+ AUTH_REQUIRED: 'run pullboard relay on to sign in again, or use the address and secret pullboard serve printed',
+ B26_PERSON_ANSWER: 'ask your coordinator to answer or pass the decision: pullboard shout coordinator "<question>" --decision',
+ B26_PERSON_APPROVAL: 'ask the person to decide in pullboard view',
+ B26_PERSON_CHANNEL: 'record it as the person through pullboard view or the person\'s own terminal',
+ B26_PERSON_DECISION: 'ask your coordinator: pullboard shout coordinator "<question>" --decision',
+ BAD_BOARD: 'run the command from the board\'s own repo, where pullboard status names its board id',
+ BAD_BROWSER_RESOURCE: 'request the "gate" resource with browser: true',
+ BAD_CHECK: 'ask your coordinator to set the check: pullboard edit <id> --check "<command>"',
+ BAD_CHECK_BASELINE: 'the coordinator sets the check again: pullboard edit <id> --check "<command>"',
+ CHECK_MASKS_EXIT: 'set the check to run its proof alone, or capture the output first and test it, then retry: pullboard edit <id> --check "<command>"',
+ BAD_SETTINGS: 'restore the named setting to its documented type in its source file, then retry GET /api/v1/settings',
+ BAD_CONFIG: 'fix pullboard.json as the message says, then commit it: git commit -m "chore: fix pullboard config" pullboard.json',
+ BAD_CURSOR: 'pass a nonnegative integer from the last response you received',
+ BAD_DECISION: 'choose accept or reject with a supported reason: pullboard verify <id> reject --reason TEST_FAILURE --note "<what failed>"',
+ BAD_DEPENDENCIES: 'use --after with item ids, such as --after 1,2, or --after none',
+ BAD_EVIDENCE: 'pass the evidence fields the message names, then retry',
+ BAD_FACT_ID: 'upgrade to the current Pullboard engine, then retry the original fact operation',
+ BAD_CAUSE: 'name the cause as test:<file>::<title>, refusal:<CODE>, row:<id> or doctrine:<id>, or leave --cause out',
+ BAD_FACT_KIND: 'use a supported kind, such as note: pullboard fact <id> note "<what you observed>"',
+ BAD_FACT_REF: 'cite code as path:line[-line]@<full 40-character commit>, from git rev-parse HEAD',
+ BAD_FIRST_COMMIT: 'commit the repository first, then run pullboard spec signers add',
+ BAD_LANE: 'choose a lane name made of lowercase letters, digits and dashes, then retry pullboard lane add',
+ BAD_LANE_PATH: 'give pullboard lane add a folder path inside the repository, relative to its root',
+ BAD_GATE_SLOTS: 'choose a positive gateSlots value no lower than browserSlots shown by pullboard settings: pullboard settings gateSlots <n>',
+ BAD_SHORT_SLOTS: 'choose gate.shortSlots as a whole number, 0 or more (0 turns short slots off): pullboard settings gate.shortSlots <n>',
+ BAD_SHORT_SLOT_REQUEST: 'ask for a short slot only from a machine gate run that names its test files; landings and diagnostics use ordinary gate slots',
+ BAD_BROWSER_SLOTS: 'choose browserSlots from 1 through gateSlots shown by pullboard settings: pullboard settings browserSlots <n>',
+ BAD_MACHINE_SETTINGS: 'fix or remove the machine settings file the message names, then run pullboard settings',
+ MACHINE_HOME_NOT_WRITABLE: 'give the agent write access to the named machine-home directory, or run the command outside the sandbox',
+ BAD_REASON: 'accept with --note "how you proved it", or reject with --reason TEST_FAILURE, BEHAVIOR_MISMATCH, INSUFFICIENT_EVIDENCE, STALE_HEAD or OTHER',
+ BAD_REF: 'name the code as path:line-line@commit using a full 40-character commit SHA, such as src/serve.js:12-30@<full-sha>',
+ BAD_BLUEPRINT: 'fix the blueprint JSON fields named in the message, then run pullboard blueprint add <file> again',
+ BAD_REMOTE_RESOURCE: 'request remote execution through the machine gate with name: "gate"',
+ BAD_RUNNER: 'run pullboard runner add <ssh-host> --slots <positive-count> --browser <count-from-zero-through-slots>; remote node and root overrides must be absolute paths',
+ BAD_RUNNER_POOL: 'fix runnerProvider to return an array of unique hosts with positive slots and browser capacity from zero through slots',
+ BAD_RUNNER_SETTINGS: 'pass updateRunnerSettings a nonempty configured host and a function that persists its settings',
+ BAD_REQUEST: 'send the request body the message names as an application/json object',
+ BAD_RESOURCE_CAPACITY: 'pass a positive integer capacity',
+ BAD_RESOURCE_METADATA: 'pass the resource item and kind as text',
+ BAD_RESOURCE_NAME: 'pass a nonempty resource name',
+ BAD_RESOURCE_PRIORITY: 'request the slot as one kind: a landing, an item check or a diagnostic',
+ BAD_RESOURCE_SCOPE: 'use the machine or repo scope',
+ BAD_ROUTE: 'use --route light, mid or strong',
+ BAD_PARENT: 'join again with --parent <stable-session-id> from your own runtime session',
+ BAD_SEAT_ID: 'create the seat again from the same checkout without naming it, so Pullboard picks the next free name: pullboard worktree <lane> --model "<model name>"',
+ BAD_SIGNATURE: 'make sure the signer is listed, then record a fresh sign-off: pullboard spec signoff <ids>',
+ BAD_SIGNER: 'set git config user.email, or pass --by <principal>',
+ BAD_SIGNERS_BASE: 'restore .pullboard/signers.initial and its hash from git: git checkout HEAD -- .pullboard',
+ BAD_SIGNOFF: 'sign the current approved rows from this repository: pullboard spec signoff <ids>',
+ BAD_VERDICT_REVIEW: 'restore the submitted commit and reviewed Git objects, then re-review the clean composition with current Pullboard',
+ BAD_SIGNOFFS: 'restore the sign-off file from git: git checkout HEAD -- .pullboard/signoffs.jsonl',
+ BAD_SINCE: 'pass a date: --since 2026-10-08',
+ BLOCKED: 'take another item with pullboard next, or shout the lane it waits on: pullboard shout <lane> "<text>"',
+ BLUEPRINT_EXISTS: 'choose a file that does not exist: pullboard blueprint save <new-file>',
+ BLUEPRINT_ITEM_UNCHECKED: 'give the starter item named in the message a criterion and a check command, then run pullboard blueprint add <file> again',
+ BLUEPRINT_KIND_TAKEN: 'keep at most one product and one architecture blueprint, then run the same command again',
+ BLUEPRINT_NOT_ADDED: 'add the blueprint to this board first: pullboard blueprint add <name or file>',
+ BLUEPRINT_NO_SOURCE: 'give the rule named in the message the reference it paraphrases as source { name, id, url }, then run pullboard blueprint add <file> again',
+ BLUEPRINT_URL: 'download and read the blueprint yourself, then run pullboard blueprint add <local-file>',
+ BOARD_BUSY: 'wait for the other pullboard process to finish, then retry',
+ BOARD_NOT_WRITABLE: 'give the agent write access to the repo\'s .git/pullboard folder, or run the command outside the sandbox',
+ BOARD_SCHEMA_BEHIND: 'run a command that changes the board, such as pullboard shout or pullboard add, which upgrades it; then run this again',
+ BOARD_SCOPE_UNAVAILABLE: 'link the board: pullboard relay on',
+ BOARD_UNAVAILABLE: 'restore the repo, or drop it: pullboard forget <path>',
+ BRIEF_LANE: 'split the item by lane, or add the other lane\'s part as its own item and wait on it with --after',
+ BRIEF_TOO_LONG: 'shorten the brief and point to a longer doc by path, or pass --brief-file <file>',
+ BROWSER_SLOT_REQUIRED: 'release the gate lease and take it again with browser: true',
+ RUNNER_CAPACITY_BUSY: 'nothing to do on that runner: rerun once its running jobs end, and it runs at its new registered size',
+ RUNNER_BROWSER_SLOT_REQUIRED: 'nothing to do: the run reruns on a local gate slot; if it repeats, set gate.browserByLaunch the same on this machine and that runner',
+ CANNOT_SIGN: 'sign only approved rows: pullboard spec signoff <approved ids>',
+ CHECKOUT_SESSION: 'run pullboard takeover from the agent session that owns this checkout',
+ CHECKOUT_BUSY: 'let the named command finish, or stop it if it is stuck, then commit again',
+ CHECK_SYNTAX: 'close the quote the shell names, then set the check again: inside single quotes write an apostrophe as \'\\\'\' or match it with ., and test with sh -n -c "<command>"',
+ CHECK_ACCEPT_PERSON_ONLY: 'ask the coordinator to bring the check to the person: pullboard shout coordinator "#<id> needs the person to accept its check" --decision',
+ CHECK_ACCEPT_STALE: 'read the current check with pullboard show <id>, then the person accepts it again: pullboard check accept <id>',
+ CHECK_CANNOT_FAIL: 'write a check that exits nonzero on the problem, then add the item again',
+ CHECK_CONFIRM: 'read the check command, then run pullboard check <id> --yes',
+ GUARD_CANNOT_FAIL: 'reject: the check does not test the guard; ask for one that fails with the guard reverted: pullboard verify <id> reject --reason TEST_FAILURE --note "<what the check missed>"',
+ GUARD_NOT_FOUND: 'reject: the named guard is not in the submitted commit; fix the guard line in the criterion with the coordinator: pullboard shout coordinator --decision "<id> guard does not match the commit"',
+ CHECK_RED: 'reject with what failed: pullboard verify <id> reject --reason TEST_FAILURE --note "<what failed>"',
+ CHECK_UNVERIFIED: 'restore the install or check environment, then run pullboard verify <id> again',
+ CHILDREN_OPEN: 'finish the child items (pullboard list --all), or ask the coordinator to withdraw them',
+ CLOSED: 'read its state with pullboard show <id>, then take open work: pullboard next',
+ CODE_NOT_AVAILABLE: 'read code through pullboard view or a local pullboard serve',
+ COMMAND_FAILED: 'read the reported output above, fix what it names, and run the command again',
+ CORE_BARE: 'turn off core.bare: git config core.bare false',
+ COORDINATOR_CHECK: 'ask your coordinator to set the check: pullboard shout coordinator "please set a check on #<id>"',
+ COORDINATOR_ONLY: 'ask the coordinator to do it: pullboard shout coordinator "<what you need>"',
+ COORDINATOR_HELD: 'coordinate from the main checkout the refusal names, or run pullboard takeover in this main checkout to take the coordinator here',
+ COORDINATOR_TAKEOVER: 'link the board with pullboard relay on in the main checkout, then run pullboard takeover there',
+ COORDINATOR_VERIFIES: 'leave the review to the coordinator; shout it when the item is ready: pullboard shout coordinator "#<id> is ready to verify"',
+ CRITERIA_CHANGED: 'ask the coordinator to refreeze it: pullboard shout coordinator "please refreeze #<id>"',
+ CRITERION_PROVES_NOTHING: 'set a check that fails before the work: pullboard edit <id> --check "<command>", or ask the person to accept this one: pullboard check accept <id>',
+ DELTA_NOT_AVAILABLE: 'read the full board state from this API instead of since=N',
+ DEPENDENCY_CYCLE: 'change --after so no item waits on itself',
+ DEVICE_ACCOUNT: 'run pullboard relay revoke <device> again and sign in to the GitHub account that paired the device',
+ DEVICE_CRYPTO: 'use Node 22 or newer, or a browser on a secure (https) page',
+ DEVICE_ENDPOINT: 'upgrade Pullboard on this machine and the phone, then retry',
+ DEVICE_ENROLLMENT: 'make a fresh pairing link: pullboard relay on --all',
+ DEVICE_ENROLL_AUTH: 'make a fresh pairing link: pullboard relay on --all',
+ DEVICE_EXISTS: 'make a fresh pairing link: pullboard relay on --all',
+ DEVICE_FORMAT: 'make a fresh pairing link: pullboard relay on --all',
+ DEVICE_ID: 'list paired devices with pullboard relay devices and name one of them',
+ DEVICE_KEY: 'pair the device again: pullboard relay on --all',
+ DEVICE_NOT_ENROLLED: 'list paired devices with pullboard relay devices, or pair one: pullboard relay on --all',
+ DEVICE_PAIR_EXPIRED: 'make a fresh pairing link: pullboard relay on --all',
+ DEVICE_PAIR_SECRET: 'open the pairing link exactly as printed, or make a fresh one: pullboard relay on --all',
+ DEVICE_PAIR_USED: 'make a fresh pairing link: pullboard relay on --all',
+ DEVICE_REVOKED: 'pair the device again: pullboard relay on --all',
+ DEVICE_REVOKE_CANCELLED: 'run pullboard relay revoke <device> again when ready and complete the fresh GitHub sign-in',
+ DEVICE_WRAP_AUTH: 'pair the device again: pullboard relay on --all',
+ DEVICE_WRAP_BINDING: 'upgrade Pullboard, then pair the device again: pullboard relay on --all',
+ DEVICE_WRAP_KEY: 'pair the device again: pullboard relay on --all',
+ DIFF_TOO_LARGE: 'split the change into smaller commits',
+ DIGEST_SIZE: 'shout the coordinator with the board size: pullboard shout coordinator "digest outgrew 50 KB"',
+ DIGEST_WRITE: 'choose a writable file outside .git: pullboard digest --out briefing.md',
+ DIRTY: 'commit your changes, then run the command again',
+ EMPTY_FACT: 'give nonempty fact text: pullboard fact <id> note "<what you saw>"',
+ EMPTY_BLUEPRINT: 'ask the person to approve exportable rows written as "<rule> Why: <reason>", then run pullboard blueprint save again',
+ FIT_CHANGED: 'read the batch again with pullboard spec fit, then approve it with the batch code it prints: pullboard spec fit approve <batch>',
+ FIT_READING: 'read the batch again with pullboard spec fit, then approve it with the batch code it prints: pullboard spec fit approve <batch>',
+ FIT_FILE: 'restore or remove .git/pullboard/blueprint-fit.json, then have the seat record its proposals again with pullboard blueprint fit',
+ FIT_OWN_PROPOSAL: 'ask the person to approve the batch: pullboard spec fit approve <batch>',
+ FIT_PROPOSAL: 'retry with keep, adapt --text "<new text>" --reason "why", drop --reason "why", or answer --text "<choice>"',
+ FIT_STALE: 'read what is left with pullboard spec fit, then approve it with the batch code it prints: pullboard spec fit approve <batch>',
+ FIT_TARGET: 'pick a target the message lists, or read the waiting batch with pullboard spec fit',
+ NO_FIT_PROPOSALS: 'have a seat record proposals with pullboard blueprint fit <name or file> <target> keep|adapt|drop|answer',
+ EMPTY_NOTE: 'say why: pullboard pass <id> --note "<reason>"',
+ BAD_SHOUT_ITEM: 'name an existing positive item: pullboard shout --item <id> "<text>"',
+ EMPTY_SHOUT: 'give the shout text: pullboard shout <to> "<text>"',
+ EMPTY_SIGNERS: 'restore the signer list from Git: git restore --source=HEAD -- .pullboard/signers',
+ ENGINE_VERSION: 'upgrade Pullboard: npm install -g pullboard@latest',
+ EVENT_LOG_VERSION: 'upgrade Pullboard: npm install -g pullboard@latest',
+ EXPORT_EXISTS: 'name an empty folder for the export',
+ FACT_JUDGEMENT: 'use a nonjudgement fact kind such as note, or ask the coordinator to record a judgement: pullboard fact <id> note "<what you observed>"',
+ FLAG_NOT_ALLOWED: 'drop the flag; pullboard help spec lists what each spec command takes',
+ GATE_RED: 'fix what the gate report names, commit, and submit again',
+ GATE_ARGUMENT: 'use pullboard resources for status, or pullboard gate with no extra words to run the gate',
+ GATE_SLOT_LEASE_LOST: 'let the parent process take the gate slot again, then restart the child',
+ GATE_SLOT_LEASE_REQUIRED: 'start the child test process with the live gate lease',
+ GATE_SLOT_MARKER_INVALID: 'restart the child with gateSlotEnvironment(lease)',
+ GATE_SLOT_TOKEN_REQUIRED: 'restart the child with gateSlotEnvironment(lease)',
+ NO_SNAPSHOT: 'run pullboard relay from the linked computer to publish its saved snapshot, then refresh the phone',
+ RELAY_API_VERSION: 'upgrade Pullboard on every joined computer and the configured relay before retrying; keep the local board and pending data',
+ RELAY_CLOCK: 'ask the relay operator to restore a valid service clock, then retry the saved upload or read',
+ RELAY_CLOSED: 'restart the relay service before retrying the saved operation',
+ RELAY_CONFIG: 'ask the relay operator to repair the named service setting and restart; retain the local board and pending upload',
+ RELAY_PAGE_CACHE: 'close other local Pullboard commands, then restore the private relay-pages cache permissions or remove only that device cache and retry; keep the board, relay link and key',
+ INFRA_NOTE_REQUIRED: 'run pullboard submit <id> --infra "<why>" with the reason the edit to an existing test or gate file is needed',
+ SHORT_SLOT_FULL_SUITE: 'run the whole suite outside the short check, where it queues for an ordinary gate slot; short slots are only for runs that name their test files',
+ GIT_GRAFTS: 'ask the coordinator to remove the git graft file: pullboard shout coordinator "please remove .git/info/grafts"',
+ HEAD_NOT_NEW: 'commit the rework, then pullboard submit <id>',
+ HELD: 'take another item: pullboard next',
+ REOPEN_HELD_FOR_BUILDER: 'wait until the named deadline, or ask the builder to run pullboard release <id>',
+ HOST_NAME: 'reword the named commit\'s message without this machine\'s name (git rebase -i, then reword), then run pullboard submit <id> again',
+ HUMAN_REQUIRED: 'send it from the paired phone, or run pullboard relay on --all from the person\'s terminal',
+ IMPORT_FORMAT: 'make an export with pullboard export > board.json, then import that file',
+ IMPORT_NOT_EMPTY: 'import into a fresh repo whose board is empty: git init <dir> && cd <dir> && pullboard init',
+ IMPORT_SCHEMA: 'export and import with the same Pullboard version',
+ IMPORT_VERSION: 'export the board again with this Pullboard version: pullboard export > board.json',
+ INLINE_GATE: 'use the gate as its own flag: pullboard spec draft "<text>" --gate "<check>"',
+ INTERNAL: 'run the command again; if it repeats, report it with pullboard shout coordinator "<command and output>"',
+ ITEM_HELD: 'take another item with pullboard next while the coordinator holds this one',
+ ITEM_LEASE_LOST: 'read pullboard show <id>; if the item is free, claim it again for a build or reserve it with pullboard next --verify <id> for a review, then retry',
+ ITEM_NOT_AVAILABLE: 'read the item from this API\'s board state',
+ ITEM_NOT_OPEN: 'hold only open or claimed items; see pullboard list',
+ LANDING_FAILURE_REQUIRED: 'reopen with --note "<test file>: <test name>; merge commit <sha>", or with --conflict <file> for each conflicting file when it only conflicts with the trunk',
+ NOT_CONFLICTING: 'merge it; reopen only after a red landing, with --note "<test file>: <test name>; merge commit <sha>"',
+ CONFLICT_FILES: 'name only the files Git reports as conflicting with the trunk: pullboard reopen <id> --conflict <file> [--conflict <file>]',
+ NOT_ACCEPTED: 'reopen a submission with --note "why"; --conflict is for accepted work',
+ BAD_CONFLICT: 'run pullboard reopen <id> --conflict <file> [--conflict <file>] from the main checkout',
+ LANE_TAKEN: 'choose a different lane name with pullboard lane add',
+ LAND_ADOPT: 'read pullboard resume, then run pullboard land --adopt, or pullboard land when nothing is unfinished',
+ LAND_CANDIDATE: 'read pullboard resume and the saved candidate logs, restore the recorded candidate worktree and board, then run pullboard land --adopt',
+ LAND_PARALLEL_NESTED_GATE: 'run pullboard land from the coordinator main checkout outside a gate command so each candidate can obtain its own slot',
+ LAND_LEASE_CORRUPT: 'restore a consistent board export before running pullboard land',
+ LAND_LEASE_LOST: 'stop this landing command, read pullboard resume, then adopt only after the current holder finishes',
+ LAND_LEASE_REQUEST: 'start a new pullboard land command from the coordinator main checkout',
+ LAND_RELAY_REQUIRED: 'restore the linked relay connection, then run pullboard land again',
+ LAND_TIMEOUT_CUSTODY: 'inspect the saved timed gate cleanup state and stop only its proven owned processes before starting another landing',
+ LAND_GATE_OUTPUT: 'inspect the retained timed gate output directory and free disk space, then start another landing',
+ LAND_GATE_TIMEOUT: 'read the recorded landing log, correct the gate or its configured landing timeout, then start another landing after its cadence',
+ LAND_WORKER: 'read pullboard resume and the saved landing logs, stop any owned gate still running, then run pullboard land --adopt',
+ RELAY_CONFIRMATION_PENDING: 'wait for the local moves to receive ordered relay receipts before running pullboard land',
+ LAND_BATCH: 'adopt the recorded batch: pullboard land --adopt',
+ LAND_ENVIRONMENT: 'run pullboard land on a machine whose platform, architecture and Node version match landing.environment in pullboard.json',
+ LAND_EVIDENCE: 'preserve earlier gate and diagnostic evidence, then pullboard land --adopt',
+ LAND_SOURCE_CHANGED: 'inspect the recorded landing logs and restore the batch source before pullboard land --adopt',
+ LAND_DIAGNOSTIC: 'read the landing log the message names, and make the test reporter print file names',
+ LAND_DIRTY: 'inspect the landing worktree, commit or remove its edits, then pullboard land --adopt',
+ LAND_FLAKE: 'fix the flaky test, or ask the person for a waiver: pullboard land --waive <test> --until <date> --reason "why"',
+ LAND_HOST_NOT_JOINED: 'on the matching machine, run pullboard settings landing.pool on, then pullboard land',
+ LAND_HEADER: 'shorten the item\'s cited rows (pullboard edit <id>), then pullboard land',
+ LAND_INTERACTION: 'read the batch\'s failing tests, then land the items in separate batches',
+ LAND_ITEM_MOVED: 'rebuild the batch from current verified work: pullboard land',
+ LAND_MERGE: 'inspect the landing worktree and its hooks, then pullboard land --adopt',
+ LAND_MOVED: 'read pullboard resume, then adopt the current batch: pullboard land --adopt',
+ LAND_NOT_PUSHED: 'push the batch, then pullboard land --adopt',
+ LAND_PERSON_ONLY: 'ask the person to waive it from their terminal or pullboard view',
+ LAND_PUSH: 'inspect the remote and hooks, then pullboard land --adopt',
+ LAND_REMOTE_MOVED: 'inspect the remote branch, then pullboard land --adopt',
+ LAND_TEST_DEFECT: 'commit a correction to the test named by the held defect, or ask the person for an expiring test waiver; then run pullboard land again',
+ LAND_TRUNK: 'check the recorded trunk branch with pullboard resume, then switch the main checkout to that branch: git switch <trunk-branch>',
+ LAND_TRUNK_MOVED: 'rebuild the batch from the new main: pullboard land',
+ LAND_WAIVER: 'pullboard land --waive <test> --until <date> --reason "why"',
+ LAND_WORKTREE: 'restore the landing worktree the message names, then pullboard land --adopt',
+ LANE_HELD: 'wait for the lane: pullboard next --wait 9 (minutes)',
+ LOCAL_RUNNER_REQUEUE: 'call requeueRunner only on a lease with a runner; release a local lease normally',
+ MAIN_IS_COORDINATOR: 'use an independent agent checkout for agent work, or run person-only actions from the main checkout as the coordinator',
+ MERGE_CHECK_FAILED: 'use Git 2.38 or newer (git --version), then retry',
+ MERGE_CONFLICT: 'merge main into your branch, resolve the conflicts, commit, and run the command again',
+ MILESTONES_CORRUPT: 'restore the board from a known-good export: pullboard import <file>',
+ MILESTONE_COMMIT: 'commit to main, then ship from the main checkout: pullboard milestone ship <name>',
+ MILESTONE_EDIT: 'pass --name, --note or --target: pullboard milestone edit <name> --note "<text>"',
+ MILESTONE_EXISTS: 'pick another name, or edit the existing one: pullboard milestone edit <name>',
+ MILESTONE_ITEMS: 'list item ids once each: pullboard milestone add <name> --items 1,2',
+ MILESTONE_NAME: 'pullboard milestone add <name>',
+ MILESTONE_NOTE: 'pass the note text: --note "<text>"',
+ MILESTONE_ORDER: 'move it before a different milestone; see pullboard roadmap',
+ MILESTONE_SHIPPED: 'add the item to the next milestone instead: pullboard milestone items <next> --add <id>',
+ MILESTONE_TARGET: 'pass a date and time: pullboard milestone edit <name> --target 2026-10-20T18:00Z',
+ MISSING_SIGNATURE: 'have the person repeat approval for the named row: pullboard spec approve <id>',
+ MISSING_SIGNERS: 'restore the signer list from git: git checkout HEAD -- .pullboard/signers',
+ MODEL_REQUIRED: 'pass --model "<model name>", or set PULLBOARD_MODEL in this shell',
+ MOVED_DURING_GATE: 'leave the worktree alone until the gate finishes, then submit again',
+ BAR_REASON: 'say what the old bar got wrong: pullboard edit <id> --reason "..."',
+ NOTE_REQUIRED: 'add --note "<what happened>"',
+ NOTHING_FREE: 'wait for work: pullboard next --wait 9 (minutes)',
+ NOT_AT_COMMIT: 'check out the submitted commit shown by pullboard show <id>: git switch --detach <commit>',
+ NOT_A_DECISION: 'reply with a shout: pullboard shout <to> "<text>"',
+ NOT_A_REPO: 'cd into a git repo, or make one: git init',
+ NOT_CLAIMABLE: 'take open work: pullboard next',
+ NOT_COMMITTED: 'commit the files the message names, then run the command again',
+ NOT_COORDINATOR_DECISION: 'list open decisions with pullboard decisions and answer one of those',
+ NOT_HELD: 'see what is held with pullboard status',
+ NOT_HOLDING: 'name an item: pullboard check <id>, or run the project gate: pullboard gate',
+ NOT_JOINED: 'join a lane from this worktree: pullboard join <lane> --model "<model name>" (see: pullboard lanes)',
+ NOT_MAIN: 'run this coordinator-owned operation from the main checkout, or ask the coordinator to do it',
+ NOT_APPROVER: 'ask one of the approvers pullboard.json names to do it, signed in as themselves; to change the list, an approver commits it and runs pullboard relay on',
+ BAD_APPROVERS: 'list approvers in pullboard.json as distinct GitHub logins, at most fifty, then run pullboard relay on',
+ NOT_MERGED: 'merge the item\'s commit onto the trunk, then pullboard merged <id>',
+ NOT_SSH_KEY: 'add a valid OpenSSH public key: pullboard spec signers add --key ~/.ssh/id_ed25519.pub',
+ NOT_SSH_KEY_PATH: 'set user.signingkey to an SSH key file: git config user.signingkey ~/.ssh/id_ed25519.pub',
+ NOT_SUBMITTED: 'see its state with pullboard show <id>; verify only submitted items: pullboard next --verify',
+ NOT_VERIFIED: 'merge only verified items; see pullboard list --all',
+ NOT_YOURS: 'shout its holder or the coordinator: pullboard shout coordinator "<what you need>"',
+ NOT_YOUR_CHECKOUT: 'make an independent checkout with git worktree add -b <lane>/<n> ../<repo>-<lane>-<n>, then run pullboard join <lane> --model "<model name>" there; the same agent in a new session should run pullboard takeover from its own shell',
+ RIGOR_RANGE: 'pass --base the commit or branch this change grew from: pullboard rigor quality --base main',
+ RIGOR_RULE: 'name a rule pullboard help rigor lists: pullboard rigor quality --rule silent-catch',
+ RIGOR_UNNOTICED: 'run pullboard rigor and draft a cause it lists, or wait until the cause repeats',
+ RIGOR_UNPROVEN: 'name a check that fails at --red and passes at --green: pullboard rigor draft <key> "<rule>" --check "<command>" --red <commit> --green <commit>',
+ RIGOR_PERSON_ONLY: 'ask the person to mark it from the main checkout: pullboard fact <id> root-cause "<why>" --cause <key> --never-again --as person',
+ SANDBOX_BLOCKED: `${COORDINATOR_PERSON_REQUEST}; or run the gate outside the sandbox; keep the tests unchanged`,
+ NOT_YOUR_DECISION: 'answer only decisions addressed to you; see pullboard inbox',
+ NO_AGENT: 'create and join a lane worktree: pullboard worktree <lane> --model "<model name>"',
+ NO_BOARD: 'initialize the board in this repository: pullboard init',
+ NO_BLUEPRINT: 'choose a bundled blueprint named in the message, or pass an existing local JSON file to pullboard blueprint add',
+ NO_BRIEF: 'add the missing fields with pullboard edit <id> --brief "..." --criterion "..."',
+ NO_CHECK: 'run the project gate: pullboard gate',
+ NO_COMMIT: 'commit your work, or name a commit that exists: git log --oneline',
+ NO_CONFIG: 'run pullboard init in the main checkout and commit pullboard.json',
+ READ_ONLY: 'read settings with GET /api/v1/settings; use pullboard settings for supported machine-setting changes',
+ SETTINGS_NOT_AVAILABLE: 'use the authenticated local API address printed by pullboard serve to read machine and repository settings',
+ NO_ENDPOINT: 'use a path under /api/v1/boards',
+ NO_EVIDENCE: 'cite the row id in a test name, or build it first',
+ NO_FACT: 'name a fact id from pullboard show <id> --json',
+ NO_FILE: 'check the path and pass a file that exists',
+ NO_FILES_LANE: 'run pullboard lanes, then file the build in a lane that owns files, or pass --after <id> if it reviews that item',
+ NO_FIRST_COMMIT: 'commit the repo, then pullboard spec signers add',
+ NO_GATE: 'in the main checkout, run pullboard gate set "<project test command>", then commit pullboard.json',
+ NO_ITEM: 'find the item id: pullboard list --all',
+ NO_LANE: 'pick a lane from pullboard lanes',
+ NO_LINES: 'name a line range inside the file',
+ NO_MILESTONE: 'name a milestone from pullboard roadmap',
+ NO_NEXT_MILESTONE: 'add the next milestone, or name one: pullboard milestone ship <name> --next <milestone>',
+ NO_POLICY: 'restore and commit pullboard.json, then run the command again',
+ NO_READER: 'name a lane, an agent or all: pullboard shout all "<text>"',
+ NO_REPO: 'run pullboard init in the repo, or pick a project in pullboard view',
+ NO_ROLE: 'choose one of the roles listed by pullboard skills',
+ NO_ROW: 'list the rows with pullboard spec --json, then name one of them',
+ NO_SECTION: 'add a section heading such as "## G · Goals" to the spec, then draft the row',
+ NO_SHOUT: 'name a shout id from pullboard inbox',
+ NO_SIGNERS: 'add an SSH signer: pullboard spec signers add',
+ NO_SIGNING_COMMIT: 'commit the repo, then sign again',
+ NO_SPEC: 'run pullboard init',
+ NO_TITLE: 'give a title: pullboard add <lane> "<title>"',
+ NO_TRUNK: 'in the main checkout, switch to the repository’s trunk branch and run pullboard inbox',
+ O2_FAMILY_MATCH: 'ask the coordinator for a verifier from another family: pullboard shout coordinator "#<id> needs a verifier from another family"',
+ OAUTH_CANCELLED: 'start sign-in again: pullboard relay on',
+ OAUTH_CLEANUP: 'run pullboard relay on again once the relay answers',
+ OAUTH_EXPIRED: 'start sign-in again: pullboard relay on',
+ ONE_CLAIM: 'submit or release the item you hold: pullboard release <id> --note "why"',
+ ONE_COORDINATOR: 'make a lane worktree and join it as an agent: pullboard worktree <lane> --model "<model name>"',
+ OUTSIDE_LANE: 'move those changes out of this commit, and shout the lane that owns them: pullboard shout <lane> "<text>"',
+ PAIR_BUSY: 'let sync finish, then pair again: pullboard relay pair',
+ PAIR_CODE_INVALID: 'ask the linked device for a new code: pullboard relay pair',
+ PAIR_LINK_LONG: 'open the printed link instead of scanning the code',
+ PAIR_PACKAGE: 'make a fresh code on the linked device: pullboard relay pair',
+ PAIR_PACKAGE_SIZE: 'ask the linked device for a smaller package, or join from a fresh clone',
+ PAIR_PENDING: 'finish sync first (pullboard status), then pair again',
+ PAIR_RELAY: 'run pullboard relay join with the relay address the code came from',
+ PAIR_REPOSITORY: 'ask the linked device for a fresh code, then join inside the matching clone',
+ PAIR_STATE: 'sync this device (pullboard status), then pair again',
+ PATH_OWNED: 'choose a folder no existing lane owns, or edit the lane ownership in pullboard.json from the main checkout',
+ PARENT_CLOSED: 'add the item without --parent, or under an open parent',
+ PARENT_LANE: 'add the child in its parent\'s lane',
+ PARENT_SESSION_CHANGED: 'create a fresh worktree and join it from the new parent session',
+ PENDING_REFREEZE: 'the coordinator runs pullboard refreeze <id>',
+ PRIVATE_BLUEPRINT: 'choose a blueprint name and title that identify no person or private project, then retry pullboard blueprint save',
+ RATCHET_ROSE: 'fix the new doctrine problems named in the report, commit, and submit again; only the person can sign an increased count',
+ RATCHET_UNCOUNTED: 'fix the named doctrine check to exit zero or one within its configured timeout, or ask the coordinator to repair it, then submit again',
+ PERSON_REQUEST_CLOSED: 'read the request\'s original result in pullboard view',
+ PERSON_REQUEST_ID: 'reload the paired view and send a new request',
+ PERSON_REQUEST_RECEIPT: 'upgrade Pullboard on the linked machine, then retry from the paired view',
+ PERSON_REQUEST_TAKEN: 'wait for the other machine\'s receipt in pullboard view',
+ PERSON_REQUEST_VERSION: 'upgrade Pullboard on the linked machine and reload the view',
+ PHONE_APPROVAL_AUTH: 'request a fresh approval on the phone and retry',
+ PHONE_APPROVAL_CONTEXT: 'request approval for this exact board, action and command',
+ PHONE_APPROVAL_EXPIRED: 'run the command again and approve it on the phone',
+ PHONE_APPROVAL_UNAVAILABLE: 'retry the phone approval when the relay answers; if it repeats, pair again with pullboard relay on --all',
+ PHONE_APPROVAL_PENDING: 'approve the named action on the paired phone before it expires',
+ PHONE_NOT_PAIRED: 'pair the phone: pullboard relay on --all',
+ PIN_FAILED: 'fix what git reported, then run pullboard run again',
+ PIPEFAIL_UNAVAILABLE: 'rewrite the gate in pullboard.json without a pipe',
+ PORT_BUSY: 'stop the other view on that port, then run pullboard view again',
+ PROJECT_NOT_REGISTERED: 'run pullboard view --project inside a registered repo, or plain pullboard view',
+ PROJECT_SCOPE: 'scope the API to one registered project repo',
+ PROOF_REQUIRED: 'say how you proved it: --note "what you broke or which edge you tried, and what happened"',
+ RELAY_ACTOR: 'send the move with the token of the agent that makes it',
+ RELAY_ANSWER: 'use pullboard answer <id> "<answer>" or pullboard pass <id> --note "<reason>"',
+ RELAY_BASELINE_EXISTS: 'save the board with pullboard export > board.json, then pullboard relay off',
+ RELAY_BASELINE_UNCERTAIN: 'run the command again when the relay answers; it first checks whether the relay kept the board upload',
+ RELAY_BOARD_DELETED: 'keep working locally, or run pullboard relay on to link the board again',
+ RELAY_BUSY: 'run the command again after the other worktree finishes sending',
+ RELAY_OUTBOX: 'keep the relay-outbox.sealed file and the board as they are, then ask for help before relinking',
+ RELAY_OUTBOX_UNBOUND: 'run the command again once the relay answers; pullboard status shows when the outbox has gone up',
+ RELAY_OUTBOX_PENDING: 'run pullboard status once the relay answers; it sends the queued moves in order first',
+ RELAY_CURSOR: 'fetch a consistent snapshot: pullboard relay',
+ RELAY_DIVERGED: 'run pullboard relay off, then pullboard relay on to link again from this machine',
+ RELAY_KEYCHAIN: 'unlock the system keychain, then run the command again',
+ RELAY_KEY_EXISTS: 'keep this clone\'s key, and join from a fresh device home',
+ RELAY_KEY_FILE_ENV_MISMATCH: 'unset PULLBOARD_RELAY_KEY, or set it to this device\'s key',
+ RELAY_KEY_MISSING: 'pair this device again: pullboard relay on --all',
+ RELAY_KEY_STORAGE: 'restore owner-only permissions: chmod 700 on the relay-keys folder, 600 on its files',
+ RELAY_LINKED: 'run pullboard relay off before linking it elsewhere, or use a fresh clone',
+ RELAY_LOCAL_CHANGED: 'save the board with pullboard export > board.json, then retry the recovery',
+ RELAY_MACHINE_STORAGE: 'restore owner-only permissions on the relay-machine folder (700) and its files (600)',
+ RELAY_MOVE: 'upgrade Pullboard: npm install -g pullboard@latest',
+ RELAY_NOT_LINKED: 'link the board: pullboard relay on --all',
+ RELAY_OFF: 'link the board: pullboard relay on',
+ RELAY_ORDER: 'fetch and apply the missing moves: pullboard relay',
+ RELAY_ORIGIN: 'set a GitHub origin: git remote add origin https://github.com/<owner>/<repo>.git, then pullboard relay on',
+ RELAY_PERSON_ONLY: 'do it as the person from the paired phone or the person\'s own session',
+ RELAY_PRESENTATION_PENDING: 'run pullboard status again',
+ RELAY_RECOVERY_HEALTHY: 'replay it normally: pullboard relay',
+ RELAY_RECOVERY_PENDING: 'finish the saved recovery: pullboard relay recover --skip <sequence>',
+ RELAY_REGISTRATION: 'create the seat again from its creating seat\'s checkout, or from the main checkout: pullboard worktree <lane> --model "<model name>"',
+ RELAY_REPLAY_REQUIRED: 'upgrade Pullboard: npm install -g pullboard@latest',
+ RELAY_RESPONSE: 'retry once the relay answers; if it repeats, pair again: pullboard relay on --all',
+ RELAY_REFUSED: 'retry after fixing the displayed relay refusal; if it repeats, upgrade Pullboard and report the refusal to the service owner',
+ RELAY_CHECKPOINT_REFUSED: 'upgrade Pullboard or run pullboard relay off then pullboard relay on --all; if it repeats, report the displayed checkpoint refusal',
+ RELAY_SNAPSHOT_LIMIT: 'upgrade the configured relay and Pullboard for bounded snapshots, then retry the retained upload',
+ RELAY_RECORD: 'retry the relay action after the displayed blocker is resolved',
+ RELAY_RETRY_PENDING: 'repeat the interrupted command exactly to get its original outcome',
+ RELAY_ROSTER_PATH: 'upgrade Pullboard on this machine, then run pullboard relay devices again',
+ RELAY_SEAL: 'continue with the next record: pullboard relay',
+ RELAY_SENDER: 'restore the record\'s sender before replaying it',
+ RELAY_SENDER_MISMATCH: 'send the move as the agent that makes it, from that agent\'s worktree',
+ RELAY_SEQUENCE: 'inspect pullboard relay and skip only the blocked next sequence',
+ RELAY_SESSION: 'link this project and pair the phone: pullboard relay on --all',
+ RELAY_SNAPSHOT: 'fetch a consistent snapshot (pullboard relay), or join by pairing',
+ RELAY_SNAPSHOT_BUSY: 'run the command again',
+ RELAY_STORAGE: 'restore relay.json as an owner-only file (chmod 600), or pullboard relay off and on again',
+ RELAY_UNAVAILABLE: 'keep working offline, and run the command again when the relay answers',
+ RELAY_UNLINK_PENDING: 'finish unlinking: pullboard relay off',
+ RELAY_URL: 'use an HTTPS relay address, such as https://app.pullboard.dev',
+ RELAY_VERSION: 'upgrade Pullboard: npm install -g pullboard@latest',
+ REMOTE_COORDINATOR_MODEL: 'run the command in the coordinator\'s own checkout',
+ REMOTE_GATE_SLOT_NOT_INHERITABLE: 'start a local child with its local gate lease; execute remote children on the runner instead of inheriting its lease locally',
+ RESERVED_RUNNER_RESOURCE: 'request the gate resource with name: "gate"; configure runner capacity with pullboard runner add <ssh-host> --slots <n> --browser <n>',
+ REQUEST_CLOSED: 'read pullboard inbox before answering another request',
+ REQUEST_OUTCOME: 'pullboard answer <id> done "<reason>", or pullboard answer <id> declined "<reason>"',
+ RESOURCE_BUSY: 'check the holder and queue with pullboard resources, wait for the resource to become free, then retry',
+ RESOURCE_CAPACITY_MISMATCH: 'check the configured capacity with pullboard settings, then retry using that capacity',
+ RESOURCE_LEASE_LOST: 'take the resource again, then retry',
+ SLOT_DB_LOCKED: 'the run never started, so it is not a red; rerun the same command once the named process releases the slot database',
+ REVIEW_COOLDOWN: 'take another review: pullboard next --verify',
+ REVIEW_NOT_READY: 'wait for the submit with pullboard watch, or check back: pullboard next --verify',
+ REVIEW_HELD: 'take another review: pullboard next --verify',
+ RUNNER_BUSY: 'wait for the named runner\'s active tests to finish, then retry its settings change',
+ RUNNER_CAPACITY_MISMATCH: 'wait for active runner leases to fit the configured capacity, then retry the run',
+ RUNNER_CLEANUP_TIMEOUT: 'inspect the named job under that runner\'s namespace and confirm its cleanup before starting another run',
+ RUNNER_NOT_REGISTERED: 'choose a host already registered in this machine\'s runner settings, then run pullboard runner remove <ssh-host> again',
+ RUNNER_OUTPUT_LIMIT: 'reduce the command output, or keep the run local',
+ RUNNER_REQUEST_LIMIT: 'keep the run local, or reduce the runner request before retrying',
+ RUNNER_SCAN_LIMIT: 'keep the run local, or reduce the oversized source blob, history or tag set named by the scan',
+ RUNNER_SETUP_REFUSED: 'run pullboard resources and pullboard settings on the named runner, correct its resource pool, then retry the run',
+ RUNNER_SECRET: 'remove the flagged secret or private path from the selected source, history, metadata or command before remote execution',
+ RUNNER_SOURCE: 'restore readable committed Git source and history, then retry; keep unsupported source objects local',
+ RUNNER_SOURCE_CHANGED: 'restore the committed source selected for the queued run, then retry it',
+ RUNNER_TOOLING_CHANGED: 'restore or commit the selected Pullboard tooling revision before remote execution',
+ RUNNER_TOOLING_IDENTITY: 'reinstall Pullboard from a named Pullboard installation before remote execution',
+ RUNNER_TOOLING_SECRET: 'restore a trusted Pullboard installation before transferring runner tooling',
+ ROUTE: 'take an item your route covers: pullboard next',
+ ROW_DECISION: 'pullboard spec approve <ids>, or pullboard spec decline <ids>',
+ ROW_DRAFT: 'pullboard spec draft "<text>" from an agent seat; the person approves the returned id',
+ ROW_ID_TAKEN: 'run the same command again for the next free id',
+ SEAL_AUTH_FAILED: 'fetch the board again, or pair this device again: pullboard relay on --all',
+ SEAL_BINDING: 'upgrade Pullboard on this device, then retry',
+ SEAL_CRYPTO: 'use Node 22 or newer, or a browser on a secure (https) page',
+ SEAL_FORMAT: 'fetch the board again: pullboard relay',
+ SEAL_KEY: 'pair this device again: pullboard relay on --all',
+ SEAL_VERSION: 'upgrade Pullboard on this device: npm install -g pullboard@latest',
+ SELF_SHOUT: 'name another agent, a lane or all: pullboard shout all "<text>"',
+ SELF_VERIFY: 'ask a different agent to verify it; from main create its worktree with pullboard worktree <lane> --model "<model name>"',
+ SESSION_LEDGER: 'make the agent-session ledger named in the message writable by this user, then run the command again',
+ SELF_SESSION_VERIFY: 'ask another agent session to verify it: pullboard next --verify from that session\'s own worktree',
+ SERVICE_ERROR: 'retry the call; if it repeats, restart pullboard serve',
+ SHALLOW_BEFORE_OPT_IN: 'git fetch --unshallow, then pullboard spec signers add',
+ SHOUT_NOT_AVAILABLE: 'read shouts with pullboard inbox, or refresh the snapshot with a current CLI',
+ SNAPSHOT_FORMAT: 'refresh the snapshot from a linked machine: pullboard relay',
+ SNAPSHOT_GRAPH: 'retry publication from the linked CLI with every referenced encrypted page present; never install a partial graph',
+ SNAPSHOT_PAGE_CONFLICT: 'retry the original immutable bytes from the saved upload; repair a damaged device cache instead of overwriting an existing content id',
+ SNAPSHOT_PAGE_FORMAT: 'refresh the snapshot from a linked computer, or upgrade Pullboard before reading this sealed-page format',
+ SNAPSHOT_PAGE_MISSING: 'refresh the phone board, or run pullboard relay from its linked computer to restage the missing encrypted pages',
+ SNAPSHOT_READ_EXPIRED: 'refresh the phone board to obtain a new read pin, then retry the older-history read',
+ SNAPSHOT_UPLOAD_EXPIRED: 'retry the saved upload; the linked CLI starts a fresh upload session without discarding pending data',
+ SPEC_APPROVAL_BASELINE: 'ask the coordinator to restore the original approval baseline from a known-good board export',
+ AGENT_APPROVAL_REQUIRED: 'ask the person to confirm or decline the named row through pullboard view or their own terminal',
+ SPEC_ANSWER: 'read the row with pullboard spec show <id>; the person answers a pending question with pullboard spec answer <id> "<choice or text>"',
+ SPEC_ANSWER_CHOICES: 'the person approves the exact answered text instead: pullboard spec approve <id> --text "<ask>: <answer>. Choices: <choices>."',
+ SPEC_BEHIND_MAIN: 'git merge main',
+ SPEC_INVALID: 'fix the unparsed row the message names, then pullboard spec check',
+ SPEC_SECTION: 'name a section the spec has; see pullboard spec',
+ SSH_KEY_FAILED: 'check the SSH key and that ssh-keygen is installed: ssh-keygen -l -f <key>',
+ SSH_KEY_NOT_FOUND: 'pass the key path: --key ~/.ssh/id_ed25519.pub',
+ STALE_VERDICT: 'merge current main into the submitted commit, commit a clean composition, then ask another agent to re-review it before landing',
+ STACKED_ON_UNVERIFIED: 'wait for the earlier item to be accepted, or rebuild on main without its commits',
+ STALE_ROW_DECISION: 'ask the person to approve the current row again in pullboard view',
+ SUBMISSION_PROOF: 'rerun pullboard submit <id> with the current CLI so its selected files and fallback are recorded',
+ TOKEN_EXPIRED: 'ask the coordinator for a fresh seat: pullboard worktree <lane> --model "<model name>"; for the coordinator\'s own token, the person runs pullboard relay on in the main checkout',
+ TOKEN_REVOKED: 'stop using this seat and ask the coordinator for a fresh one: pullboard worktree <lane> --model "<model name>"',
+ TOKENS_NOT_AVAILABLE: 'manage agent tokens in pullboard view or the signed-in relay account',
+ TOKEN_NOT_OWNED: 'name a token id from pullboard relay tokens',
+ BAD_SENTINEL: 'read pullboard sentinel --help and propose an exact command, project directory, owner and schedule',
+ BAD_JOB: 'name the job and a cadence like 10m, 2h or daily: pullboard loop declare <name> --every 10m --owner <seat or lane>',
+ UNKNOWN_JOB: 'ask the coordinator to declare it: pullboard shout coordinator "declare job <name>"; read the declared jobs with pullboard loop',
+ JOB_CADENCE_COORDINATOR_ONLY: 'ask the coordinator to change the cadence: pullboard shout coordinator "<job> needs cadence <every>" --decision',
+ STALE_SENTINEL: 'read pullboard sentinels and ask the person to approve the current exact proposal',
+ SENTINEL_ABORTED: 'resume this board again when the background view is running',
+ SENTINEL_DRAIN: 'inspect the latest watch outcome with pullboard sentinels; report the shutdown failure to its owner before retrying',
+ TOO_LARGE: 'open the file in your editor instead',
+ UNAUTHORIZED_SIGNERS_CHANGE: 'restore the previous signer list (git checkout HEAD -- .pullboard/signers), or sign the change with a listed key',
+ UNKNOWN_SPEC: 'ask the coordinator to restore the named spec rows or withdraw the item: pullboard shout coordinator "please fix the rows cited by #<id>"',
+ UNLISTED_SIGNER: 'add the signer: pullboard spec signers add --by <principal> --key <path>',
+ UNMERGED_SCHEMA: 'merge this code into the main checkout first, or test it against its own board',
+ UNTRACKED: 'commit or ignore the untracked files, then run the command again',
+ UNKNOWN_TOOL: 'call tools/list and use a tool name returned by that MCP server',
+ USAGE: 'run pullboard help',
+ VERIFIER_STANDING: 'ask the coordinator to make an independent verifier from the main checkout: pullboard worktree <lane> --model "<model name>"',
+ VERDICT_ENVIRONMENT: 'run the frozen check with current Pullboard, then have an independent reviewer record a fresh verdict with its actual executor environment',
+ VERDICT_TRUNK_MOVED: 'merge the latest main into the submitted commit and ask another agent to re-review the clean composition',
+ VIEW_START: 'run pullboard view in the foreground to see why it stopped',
+ VIEW_PAIRING_CLEANUP: 'run pullboard relay off, then pullboard relay on --all to finish pairing cleanup',
+ VIEW_STATE: 'check that the Pullboard home folder is writable, then run pullboard view again',
+ VIEW_UNAVAILABLE: 'start the view with pullboard view, then export again',
+ VIEW_PAIRING_NOT_READY: 'read this sign-in’s status again: pullboard view',
+ VIEW_SIGN_IN_AUTH: 'open the link pullboard view printed and send its session key only in the x-pullboard-key header',
+ VIEW_SIGN_IN_BUSY: 'finish or cancel the sign-in already in progress, then start it again',
+ VIEW_SIGN_IN_FAILED: 'start sign-in again from pullboard view and read the reported error if it still cannot finish',
+ VIEW_SIGN_IN_JSON: 'send application/json with one JSON object containing only the supported sign-in action and its intent id when required',
+ VIEW_SIGN_IN_LINKING: 'let the current board-linking batch finish before starting another sign-in',
+ VIEW_SIGN_IN_METHOD: 'read the invitation with GET or send sign-in actions as an application/json POST',
+ VIEW_SIGN_IN_RESPONSE: 'check the configured relay address, then start sign-in again',
+ VIEW_SIGN_IN_SCOPE: 'open the full machine view with pullboard view, then start sign-in there',
+ VIEW_SIGN_IN_STOPPED: 'start sign-in again with pullboard view',
+ VIEW_SIGN_IN_UNKNOWN: 'start sign-in again with pullboard view',
+ WITHDRAWN: 'wait on an item that is not withdrawn; see pullboard list --all',
+ WRONG_BOARD: 'open the repository registered to this board and confirm its identity with pullboard status',
+ WRONG_LANE: 'create a worktree in the required lane with pullboard worktree <lane> --model "<model name>", or take an item in your lane with pullboard next',
+ });
+
+ /**
+ * Take the step a message already spells out: the clause from its first repair word to the end of
+ * that line. One line only, so a multi-line report (a gate digest) is never repeated as the step.
+ *
+ * @param {string} message
+ * @returns {string | undefined}
+ */
+ function stepInMessage(message) {
+ const line = String(message).split('\n')[0];
+ const match = /(?:^|; |\. |: )((?:run|install|upgrade|fix|restore|commit|merge|test|check out|set|give|use|reject|ask your coordinator|answer from the main checkout|the coordinator(?= (?:runs?|sets?|restores?|either|must)\b)|to keep looking|never work around)\b.*)/i.exec(line);
+ const step = match?.[1];
+ // UNKNOWN_MOVE contains a documentation placeholder, not a supported reason value.
+ return step && !/--reason\s+CODE\b/u.test(step) ? step : undefined;
+ }
+
+ /**
+ * The next step for one refusal: its existing final next line, else the step its raise site passed,
+ * else prose guidance or this code's row. Unknown remote codes name the service owner and rule.
+ *
+ * @param {{ code?: string, next?: string } | null | undefined} error
+ * @param {string} message
+ * @param {{ caller?: 'seat'|'coordinator'|'person'|'unknown' }} [options]
+ * @returns {string}
+ */
+ export function nextStepFor(error, message, options = {}) {
+ if (personRequestGuidance(String(message), options) !== String(message)) return COORDINATOR_PERSON_REQUEST;
+ const code = typeof error?.code === 'string' ? error.code : '';
+ const finalStep = /(?:^|\r?\n)next:[ \t]*([^\r\n]*\S)[ \t]*(?:\r?\n)*$/u.exec(String(message))?.[1];
+ if (finalStep) return personRequestStep(finalStep.trim(), options);
+ if (typeof error?.next === 'string' && error.next.trim() && error.next.trim() !== RECORDED_GENERIC_NEXT) return personRequestStep(error.next.trim(), options);
+ if (code === 'SPEC_BEHIND_MAIN') return NEXT_STEPS.SPEC_BEHIND_MAIN;
+ return personRequestStep(stepInMessage(message) ?? NEXT_STEPS[code]
+ ?? `ask the service owner about refusal code ${code || '(unknown)'}, including the displayed refusal`, options);
+ }
+
diff --cc src/proof-receipts.js
index 7692e651,00000000..cd3049b4
mode 100644,000000..100644
--- a/src/proof-receipts.js
+++ b/src/proof-receipts.js
@@@ -1,78 -1,0 +1,74 @@@
++import { proofReceipts } from './board-query.js';
++export { proofReceipts };
+/** Stamp the gate's own immutable receipt with the board's seat and recorded parent [C7,H16]. */
+import {
+ atomic,
+ getItem,
+ listAgents,
+ logEvent,
+} from './board.js';
+import {
+ boardReceiptStore,
+ readGateReceipt,
+ receiptBody,
+ receiptFields,
+} from './gate-run-receipt.js';
+import { ENGINE_VERSION } from './machine.js';
+import { PROOF_RUN_ENGINE } from './proof-run-engine.js';
+import { Refused } from './refused.js';
+import * as seats from './seats.js';
+
+/** Read the native gate's file before sealing a replayable move; caller-supplied fields are not evidence. */
+export function boundProofReceipt(board, request) {
+ const id = request?.receiptId ?? request?.receipt?.id;
+ const stored = readGateReceipt(boardReceiptStore(board), id);
+ if (!stored || stored.version !== 2 || request?.receipt && receiptBody(request.receipt) !== receiptBody(stored)) {
+ throw new Refused('PROOF_RUN_UNBOUND', 'proof provenance comes from the gate receipt it stored; run the check, then read pullboard show <id>');
+ }
+ return stored;
+}
+
- /** Every stamped receipt for one item, in recorded order. */
- export function proofReceipts(board, itemId) {
- return board.db.prepare("SELECT event_id, event_detail FROM event WHERE item_id = ? AND event_kind = 'proof-run' ORDER BY event_id").all(itemId)
- .map(row => ({ eventId: row.event_id, ...JSON.parse(row.event_detail).receipt }));
- }
-
+/** Validate native facts against current board-owned identities without changing the board. */
+export function proofRunReceipt(board, request) {
+ const { agentId, itemId } = request;
+ if (!listAgents(board).some(agent => agent.agent_id === agentId)) throw new Refused('NOT_JOINED', 'join before recording a proof run');
+ // Only the engine establishes this in-process replay context after origin sealing, as for legacy gate runs.
+ // A replica cannot read the origin's receipt file; normal direct calls always require that file.
+ const run = board.executionEngineVersion === undefined ? boundProofReceipt(board, request) : receiptFields(request.receipt);
+ if (!run || run.version !== 2 || run.proof.item !== itemId) throw new Refused('PROOF_RUN_UNBOUND', 'the native receipt must name this item; run its check and read pullboard show <id>');
+ if (run.proof.seat !== agentId) throw new Refused('PROOF_RUN_ACTOR', 'the native receipt belongs to another seat; use the receipts from your own check');
+ const item = getItem(board, itemId);
+ if (run.proof.frozenDigest !== (item.item_frozen_digest ?? null)) throw new Refused('PROOF_RUN_STALE', 'the criterion changed during this proof; read pullboard show <id> before checking again');
+ const receipt = { id: run.id, kind: run.kind, item: itemId, commit: run.head, tree: run.tree,
+ frozenDigest: run.proof.frozenDigest, environment: run.proof.environment, runner: run.proof.runner,
+ seat: agentId, parentSession: seats.agentParent?.(board, agentId) ?? null, exitCode: run.proof.exitCode,
+ counts: run.proof.counts, durationMs: run.proof.durationMs, sourceClean: run.proof.sourceClean, at: run.at };
+ const existing = proofReceipts(board, itemId).find(value => value.id === receipt.id);
+ if (existing) {
+ const { eventId, ...fields } = existing;
+ // Later registration cannot retroactively upgrade an originally unknown parent.
+ receipt.parentSession = existing.parentSession;
+ if (JSON.stringify(fields) !== JSON.stringify(receipt)) throw new Refused('PROOF_RUN_CHANGED', 'that receipt id already binds different facts; keep the original and run a new check');
+ }
+ return { receipt, existing };
+}
+
+/** Record native facts atomically, revalidating after the native adapter's read-only preflight. */
+export function recordProofRun(board, request) {
+ if ((board.executionEngineVersion ?? ENGINE_VERSION) < PROOF_RUN_ENGINE) {
+ throw new Refused('ENGINE_VERSION', `proof receipts require engine ${PROOF_RUN_ENGINE}; upgrade Pullboard`);
+ }
+ return atomic(board, () => {
+ const { receipt, existing } = proofRunReceipt(board, request);
+ if (existing) return existing;
+ logEvent(board, request.agentId, 'proof-run', request.itemId, { engine: PROOF_RUN_ENGINE, receipt });
+ return receipt;
+ });
+}
+
+/** A short pointer replaces repeated provenance narratives in shouts. */
+export function refuseLongShout(text) {
+ if (Array.from(String(text)).length > 400) {
+ throw new Refused('SHOUT_TOO_LONG', 'a shout is at most 400 characters; cite proof receipt ids and use pullboard show <id> for the chain');
+ }
+}
diff --cc src/shell-run.js
index 00000000,1e8caddf..62dcc382
mode 000000,100644..100644
--- a/src/shell-run.js
+++ b/src/shell-run.js
@@@ -1,0 -1,86 +1,86 @@@
+ /**
+ * Run one shell command in a checkout and keep its output, apart from the gate's queue, runners and receipts. A
+ * board read that replays a check baseline needs only this, so it never loads the gate [C7].
+ */
+ import { spawnSync } from 'node:child_process';
+ import { executionEnvironment } from './execution-environment.js';
+ import { randomUUID } from 'node:crypto';
+ import {
+ mkdtempSync,
+ readFileSync,
+ rmSync,
+ } from 'node:fs';
+ import { tmpdir } from 'node:os';
+ import { join } from 'node:path';
+ import { fileURLToPath } from 'node:url';
+ import {
+ gitChildEnv,
+ invalidateGitFacts,
+ } from './git.js';
+ import {
+ gateStages,
+ readPipes,
+ readStages,
+ stagedScript,
+ } from './gate-stages.js';
+ import { Refused } from './refused.js';
+ import { sandboxBlockedOperation } from './sandbox-denial.js';
+
+ /**
+ * Run a shell command in a checkout for a digest: both streams in one pipe, in order, read whole
+ * however long, stdin closed so nothing waits on a person. With `stages`, each top-level stage's
+ * exit status and own output are kept too, or `stages` is null when the command cannot be split.
+ *
+ * @param {string} root
+ * @param {string} command
+ * @param {{ pipefail?: boolean, env?: NodeJS.ProcessEnv, stages?: boolean, timeoutMs?: number }} [options] - Gate-only pipefail, additional child environment values and per-stage accounting.
+ * @returns {{ isGreen: boolean, output: string, seconds: number, sandboxBlocked: string|null, stages?: Array<{ status: number|null, output: string, pipeline?: Array<{ status: number|null, output: string|null }> }> | null }}
+ */
+ export function runShell(root, command, { pipefail = false, env = {}, stages = false, timeoutMs } = {}) {
+ const started = Date.now();
+ const environment = executionEnvironment();
+ const options = { cwd: root, env: { ...gitChildEnv(root), ...env }, shell: true, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8', maxBuffer: 2 ** 30 };
+ let prefix = '';
+ if (pipefail) {
+ // Probe the same shell as the command, with no load-sensitive deadline or alternate shell.
+ const probe = spawnSync('set -o pipefail', options);
+ if (probe.status === 0) prefix = 'set -o pipefail\n';
+ else if (hasPipeline(command)) {
+ throw new Refused('PIPEFAIL_UNAVAILABLE', 'the repo gate shell cannot enable pipefail; rewrite the gate without a pipe');
+ }
+ }
+ const split = stages ? gateStages(command) : null;
+ const marker = `PULLBOARD_STAGE_${randomUUID().replaceAll('-', '')}`;
+ const pipes = split?.some((stage) => stage.pipeline.length > 1) ? mkdtempSync(join(tmpdir(), 'pullboard-pipes-')) : null;
+ // Newlines, not spaces, around the command, so a trailing comment in it cannot swallow the `)`.
+ const script = `${prefix}(\n${split ? stagedScript(split, marker, pipes) : command}\n) 2>&1`;
+ const timedDirectory = timeoutMs ? mkdtempSync(join(tmpdir(), 'pullboard-timed-output-')) : null;
+ const outputFile = timedDirectory ? join(timedDirectory, 'output.log') : null;
+ const timed = timeoutMs ? spawnSync(process.execPath, [fileURLToPath(new URL('./timed-shell-worker.js', import.meta.url))], { ...options, shell: false, stdio: ['pipe', 'pipe', 'pipe'], input: JSON.stringify({ command: script, timeoutMs, outputFile }) }) : null;
+ if (timed && (timed.status !== 0 || timed.error)) throw new Refused('LAND_TIMEOUT_CUSTODY', 'the timed gate worker did not prove cleanup; inspect its owned processes before landing again');
+ const result = timed ? { ...JSON.parse(timed.stdout || '{}'), stdout: '', stderr: timed.stderr } : spawnSync(script, options);
+ if (timed && result.error) throw new Refused('LAND_GATE_OUTPUT', `the timed gate stopped and drained after its output failed (${result.error}); inspect free disk space and ${timedDirectory} before landing again`);
+ if (timed) result.stdout = readFileSync(outputFile, 'utf8') + (result.timedOut ? `\n[LAND_GATE_TIMEOUT] landing gate exceeded ${timeoutMs}ms; its owned processes are stopped\n` : '');
+ if (timedDirectory) rmSync(timedDirectory, { recursive: true, force: true });
+ if (result.timedOut || result.overflow || result.error) result.status = 1;
+ invalidateGitFacts();
+ const pipeStatuses = pipes ? readPipes(split, pipes) : null;
+ if (pipes) rmSync(pipes, { recursive: true, force: true });
+ const raw = `${result.stdout ?? ''}${result.stderr ?? ''}`;
+ const seconds = Math.round((Date.now() - started) / 1000);
+ const blocked = (output) => (result.status === 0 ? null : sandboxBlockedOperation(root, output));
- if (!stages) return { isGreen: result.status === 0, output: raw, seconds, environment, ...(timed ? { timedOut: result.timedOut } : {}), sandboxBlocked: blocked(raw) };
- if (!split) return { isGreen: result.status === 0, output: raw, seconds, environment, ...(timed ? { timedOut: result.timedOut } : {}), stages: null, sandboxBlocked: blocked(raw) };
++ if (!stages) return { isGreen: result.status === 0, exitCode: result.status, output: raw, seconds, environment, ...(timed ? { timedOut: result.timedOut } : {}), sandboxBlocked: blocked(raw) };
++ if (!split) return { isGreen: result.status === 0, exitCode: result.status, output: raw, seconds, environment, ...(timed ? { timedOut: result.timedOut } : {}), stages: null, sandboxBlocked: blocked(raw) };
+ const staged = readStages(raw, marker, split.length);
+ // Each pipeline component's own status rides on its stage, so no failing producer hides behind a later one.
+ const withPipes = staged.stages.map((stage, index) => (pipeStatuses?.[index] ? { ...stage, pipeline: pipeStatuses[index] } : stage));
- return { isGreen: result.status === 0, seconds, environment, ...(timed ? { timedOut: result.timedOut } : {}), ...staged, stages: withPipes, sandboxBlocked: blocked(staged.output) };
++ return { isGreen: result.status === 0, exitCode: result.status, seconds, environment, ...(timed ? { timedOut: result.timedOut } : {}), ...staged, stages: withPipes, sandboxBlocked: blocked(staged.output) };
+ }
+
+ /** Conservatively detect a pipe when the configured gate shell cannot enforce every stage's status. */
+ function hasPipeline(command) {
+ for (let index = 0; index < command.length; index += 1) {
+ if (command[index] === '|' && command[index + 1] !== '|' && command[index - 1] !== '|') return true;
+ }
+ return false;
+ }
diff --cc src/trusted-policy.js
index 5fb6099c,8e615111..dfd6ea41
--- a/src/trusted-policy.js
+++ b/src/trusted-policy.js
@@@ -44,37 -47,7 +48,8 @@@ import
import { secretsIn } from './hooks.js';
import { outOfLane } from './lanes.js';
import { Refused } from './refused.js';
+import { proofCounts } from './proof-provenance.js';
- /** Read raw Git output, retaining NUL-delimited names without exposing Git diagnostics. */
- function policyGit(root, args) {
- const result = spawnSync('git', ['-c', 'core.quotepath=false', ...args], { cwd: root, env: cleanGitEnvironment(), encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
- if (result.status !== 0) throw new Refused('NO_POLICY', 'the committed coordinator policy or claim base is missing; restore its Git objects or ask the coordinator to refreeze the item');
- return result.stdout;
- }
-
- /** Resolve the primary checkout's committed HEAD, independently of a linked or detached checkout. */
- export function mainPolicy(root) {
- const checkout = mainCheckout(root);
- if (!checkout) throw new Refused('NO_POLICY', 'the coordinator checkout is detached for review; ask it to return to its main branch before claiming or running the project gate');
- if (!checkout.commit) throw new Refused('NO_POLICY', 'the coordinator checkout has no commit on ' + checkout.branch + '; create its first commit before claiming or running the project gate');
- return policyAt(root, checkout.commit);
- }
-
- /** Retain the local primary branch outside replicated board data and read-only diagnostics [B34,V6]. */
- export function trunkRef(root, branch) {
- const read = gitConfig(root, 'pullboard.trunk', { local: true, clean: true, flags: false, noReplace: true });
- if (read.status !== 0 && read.status !== 1) throw new Refused('NO_POLICY', 'the retained trunk cannot be read; restore the local Git configuration and retry');
- const current = read.status === 0 ? read.stdout.trim() : null;
- if (branch === undefined || branch === current) return current;
- const saved = spawnSync('git', ['--no-replace-objects', 'config', '--local', '--replace-all', 'pullboard.trunk', branch], {
- cwd: root, env: cleanGitEnvironment(), encoding: 'utf8',
- });
- invalidateGitFacts();
- if (saved.status !== 0) throw new Refused('NO_POLICY', 'the trunk branch cannot be recorded; restore writable local Git configuration and retry');
- return branch;
- }
-
/** Resolve the trunk snapshot and refuse a conflict without touching an index or worktree [B34,V6].
*
* Returning the exact ref and tip lets later candidate checks use the same snapshot this merge