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.
JavaScript agentic-codingai-agentsai-governanceautonomous-agentsclaude-codeclicode-reviewcodexcoding-agentsdeveloper-toolsgit-hooksllmlocal-firstmulti-agentsoftware-factoryspec-driven-developmentverificationvibe-coding
feat(core): compose indexed resume with main [N19,N26,A6,D3]
Corey Olson2ef3907b5fbf
diff --cc docs/api.mdindex d0213270,8ae17676..7d75ac88--- a/docs/api.md+++ b/docs/api.md@@@ -607,15 -611,7 +611,17 @@@ A project may declare a `staticChecks``pullboard sentinel propose <name> --check "<command>" --every 10m|hourly|daily --owner <seat or lane>` proposes a board row. Optional `--directory <relative path>`, `--timeout <milliseconds>` and `--next "<step>"` are part of the exact proposal. The directory defaults to this project, and must stay inside it; timeout defaults to 30000 ms and is a hang ceiling. The person approves or declines through the same person-channel guard as spec rows: `pullboard sentinel approve <name>` or `pullboard sentinel decline <name> --reason "<why>"`. An agent cannot approve. Any new command, directory, schedule, owner, timeout or next step needs fresh approval. No row in SPEC.md is edited.-An approved watch runs when due on `resume` and through the background view’s ordinary resume worker. The existing board and machine `health.sentinel: false` switches suppress it. Ordered run leases prevent duplicate concurrent observers. External checks run outside the database write lock, in the approved directory, with bounded final output and an owned-child timeout; recorded replay never executes a command. On POSIX hosts shutdown drains the owned process group; Windows uses direct-child termination. A failed check notifies its owner once with its name, final output and next step; staying red posts no duplicate, and recovery posts one cleared notice. Every red run remains a `sentinel:<name>` cause receipt for Rigor, without inventing a code change. Cancellation records its outcome without creating a failure or recovery notice. `pullboard sentinels --json` lists current rows, their owners, approval, latest result and current proposal’s run history. This is engine 56; earlier engines refuse the new moves before replay.+`resume` and the background view never execute approved watch commands. When watches are due, resume prints at most one line pointing to `pullboard sentinel run`. That explicit command prepares a clean checkout of the committed local trunk, runs due approved watches there in their approved relative directories, records their results on the original board, and removes the prepared checkout after the commands finish. It never chooses an agent's working tree as the execution directory or rewrites an approved command. Relative project inputs come from committed trunk; explicitly approved absolute paths retain their literal meaning.++Ordinary `resume` reads indexed work and person obligations, fresh branch-versus-trunk facts and shared approved doctrine. It directs setup, hook wiring, dirty-file ownership and stale-work/merge inspection to `pullboard resume --diagnostics`. That explicit mode keeps their existing checks and refusal messages. Ordinary accepted receipts are labelled as awaiting landing checks, not current merge eligibility; `pullboard land` still checks the current verdict before changing trunk.+++JSON v1 is unchanged: `pullboard resume --json` computes its real `dirty`, `stale`, `toMerge` and `newWorktreeLocation` fields, including their existing diagnostics. Moving diagnostics out of the default text card does not replace those JSON values with placeholders or remove them.+++`resume` also reads the last recorded work-health findings and their recording time from the board index; it does not run the Git-heavy health scan. `pullboard sentinel run` refreshes those findings and ordinary owner alerts even when no approved watch is due. A recorded empty finding list describes that recorded scan, not a new check of the current project.++Schedule `pullboard sentinel run` independently of work sessions. For example, an hourly server cron entry is `0 * * * * cd /path/to/project && pullboard sentinel run`. A scheduled CI job can run the same command after its ordinary checkout and board-access setup; its schedule calls this command, not `resume`. The checkout used by the timer must already have normal access to the board. `pullboard sentinel run --help` describes both scheduling options. These examples do not install a timer or change approval.++The existing board and machine `health.sentinel: false` switches suppress execution. Ordered run leases prevent duplicate concurrent scheduled runs. External checks run outside the database write lock, with bounded final output and an owned-child timeout; recorded replay never executes a command. On POSIX hosts shutdown drains the owned process group; Windows uses direct-child termination. A failed check notifies its owner once with its name, final output and next step; staying red posts no duplicate, and recovery posts one cleared notice. Every red run remains a `sentinel:<name>` cause receipt for Rigor, without inventing a code change. Cancellation records its outcome without creating a failure or recovery notice. `pullboard sentinels --json` lists current rows, their owners, approval, latest result and current proposal’s run history. This is engine 56; earlier engines refuse the new moves before replay.## Approval provenancediff --cc src/cli-main.jsindex 00000000,d9a3edf9..83ccf8aemode 000000,100644..100644--- a/src/cli-main.js+++ b/src/cli-main.js@@@ -1,0 -1,320 +1,321 @@@+ /**+ * The command line's entry: parse the arguments, bind the checkout, run the relay and baseline work around the+ * command when there is any, and dispatch through the lazy command table. It loads a module only when the command+ * in hand needs it, so --version and a read pay for nothing they do not run [C7].+ */+ import { appendFileSync } from 'node:fs';+ import { loadavg } from 'node:os';+ import { resolve } from 'node:path';+ import { performance } from 'node:perf_hooks';+ import { parseArgs } from 'node:util';+ import { COMMANDS } from './commands/index.js';+ import { commandOutput } from './json.js';+ import { Refused } from './refused.js';++ export const CHECKOUT_LEASES = new WeakMap();+ export const CHECKOUT_BOARD_ONLY = new WeakMap();+ let startupMainTraced = false;++ /** Append an opt-in startup phase marker for the real CLI fixture measurement [A2,C7]. */+ export function traceServeStartup(phase) {+ const path = process.env.PULLBOARD_STARTUP_TRACE_FILE;+ const entry = process.env.PULLBOARD_STARTUP_TRACE_ENTRY;+ if (!path || !entry || resolve(process.argv[1] ?? '') !== resolve(entry)) return;+ try {+ appendFileSync(path, `${JSON.stringify({ phase, at: Date.now(), elapsedMs: performance.now(),+ processId: process.pid, cpuUsage: process.cpuUsage(), loadAverage: loadavg(),+ eventLoopUtilization: performance.eventLoopUtilization() })}\n`);+ } catch {+ // Diagnostic tracing must not change normal CLI behavior.+ }+ }++ const OPTIONS = {+ criterion: { type: 'string' },+ specs: { type: 'string' },+ parent: { type: 'string' },+ reason: { type: 'string' },+ off: { type: 'boolean' },+ port: { type: 'string' },+ slots: { type: 'string' },+ browser: { type: 'string' },+ 'new-browser': { type: 'boolean' },+ node: { type: 'string' },+ root: { type: 'string' },+ project: { type: 'boolean' },+ export: { type: 'string' },+ 'no-open': { type: 'boolean' },+ 'no-permissions': { type: 'boolean' },+ note: { type: 'string' },+ infra: { type: 'string' },+ 'note-file': { type: 'string' },+ by: { type: 'string' },+ key: { type: 'string' },+ out: { type: 'string' },+ watch: { type: 'boolean' },+ after: { type: 'string' },+ brief: { type: 'string' },+ 'brief-file': { type: 'string' },+ text: { type: 'string' },+ gate: { type: 'string' },+ aim: { type: 'boolean' },+ doctrine: { type: 'boolean' },+ source: { type: 'string' },+ section: { type: 'string' },+ blueprint: { type: 'string', multiple: true },+ route: { type: 'string' },+ family: { type: 'string' },+ model: { type: 'string' },+ as: { type: 'string' },+ check: { type: 'string' },+ // The watch command's options.+ every: { type: 'string' },+ owner: { type: 'string' },+ directory: { type: 'string' },+ timeout: { type: 'string' },+ sentinel: { type: 'boolean' },+ digest: { type: 'string' },+ // The rigor quality draft's options.+ base: { type: 'string' },+ head: { type: 'string' },+ rule: { type: 'string' },+ budget: { type: 'string' },+ 'draft-quality': { type: 'boolean' },+ yes: { type: 'boolean' },++ diagnostics: { type: 'boolean' },+ landing: { type: 'boolean' },+ adopt: { type: 'boolean' },+ waive: { type: 'string' },+ until: { type: 'string' },+ agent: { type: 'string' },+ 'agent-light': { type: 'string' },+ 'agent-mid': { type: 'string' },+ 'agent-strong': { type: 'string' },+ attempts: { type: 'string' },+ minutes: { type: 'string' },+ items: { type: 'string' },+ run: { type: 'string' },+ max: { type: 'string' },+ 'dry-run': { type: 'boolean' },+ update: { type: 'boolean' },+ before: { type: 'string' },+ target: { type: 'string' },+ next: { type: 'string' },+ add: { type: 'string' },+ remove: { type: 'string' },+ name: { type: 'string' },+ title: { type: 'string' },+ url: { type: 'string' },+ skip: { type: 'string' },+ wait: { type: 'string' },+ verify: { type: 'boolean' },+ build: { type: 'boolean' },+ all: { type: 'boolean' },+ must: { type: 'boolean' },+ json: { type: 'boolean' },+ history: { type: 'boolean' },+ verbose: { type: 'boolean' },+ since: { type: 'string' },+ window: { type: 'string' },+ decision: { type: 'boolean' },+ evidence: { type: 'string' },+ outcome: { type: 'string' },+ item: { type: 'string' },+ kinds: { type: 'string' }, to: { type: 'string' }, work: { type: 'string' }, 'review-wait': { type: 'string' },+ commit: { type: 'string' },+ ref: { type: 'string' },+ supersedes: { type: 'string' },+ conflict: { type: 'string', multiple: true },+ cause: { type: 'string' },+ 'never-again': { type: 'boolean' },+ 'draft-splits': { type: 'boolean' },+ implies: { type: 'string' },+ owns: { type: 'string' },+ red: { type: 'string' },+ green: { type: 'string' },+ help: { type: 'boolean', short: 'h' },+ version: { type: 'boolean', short: 'v' },+ };++ /** Parse --wait as a switch for add/edit and as minutes for next/run, preserving all other options. */+ function parseCommandArgs(argv) {+ let command;+ for (const wait of [{ type: 'boolean' }, OPTIONS.wait]) {+ try {+ command = parseArgs({ args: argv, options: { ...OPTIONS, wait }, allowPositionals: true }).positionals[0];+ if (['add', 'edit'].includes(command)) break;+ } catch { /* The final parser supplies the existing actionable usage error. */ }+ }+ const options = ['add', 'edit'].includes(command) ? { ...OPTIONS, wait: { type: 'boolean' } } : OPTIONS;+ return parseArgs({ args: argv, options, allowPositionals: true });+ }++ /**+ * Run one command. Returns the exit code: 0 done, 1 refused, 2 usage.+ *+ * @param {string[]} argv+ * @param {any} io+ * @returns {Promise<number>}+ */+ async function runCommand(argv, io) {+ let parsed;+ try {+ parsed = parseCommandArgs(argv);+ } catch (error) {+ const refusal = new Refused('USAGE', `${error.message}; run pullboard help`);+ io.refusal?.(refusal);+ io.err(`pullboard: ${error.message}\nRun pullboard help --all for the full list.\nnext: ${io.refusalDocument(refusal).error.next}`);+ return 2;+ }+ const { values, positionals } = parsed;+ io.jsonMode?.(values.json);+ const [command = '', first, second, ...rest] = positionals;+ const args = { first, second, rest, values };+ if ((values.version || command === 'version') && !values.help) return await (await COMMANDS.version()).run(io, args);+ // Help loads only when asked for: a command name other than help, without --help, never needs it.+ const help = !command || command === 'help' || values.help+ ? (await import('./cli-help.js')).selectedHelp(command, first, second, rest, values) : null;+ if (help) return await (await COMMANDS.help()).run(io, args, help);+ try {+ if (values.as === 'person' && !['answer', 'decisions', 'fact'].includes(command)) {+ throw new Refused('USAGE', '--as person works only with pullboard answer, decisions, or fact --never-again');+ }+ const load = COMMANDS[command];+ if (!load) return (await import('./cli-help.js')).unknownCommand(io, command);+ return await (await load()).run(io, args);+ } catch (error) {+ if (error instanceof Refused) {+ io.refusal?.(error);+ io.err(`pullboard: ${await displayedRefusal(io, error)}\nnext: ${io.refusalDocument(error).error.next}`);+ (await import('./next-steps.js')).reportBlock(io, error, { command });+ return 1;+ }+ throw error;+ }+ }++ /** Retain the primary branch on every command without creating a board for global help. */+ async function rememberTrunk(io, { repoInfo, mainCheckout }) {+ let info;+ try { info = repoInfo(io.cwd); }+ catch (error) {+ if (error instanceof Refused && ['NOT_A_REPO', 'NO_REPO', 'CORE_BARE'].includes(error.code)) return;+ throw error;+ }+ if (!info.isMain) return;+ const primary = mainCheckout(info.root);+ if (primary?.branch) (await import('./trusted-policy-read.js')).trunkRef(info.root, primary.branch);+ }++ /** Whether a parsed command line only prints version or help, which asks Git nothing. */+ function asksGitNothing(argv) {+ try {+ const { values, positionals: [command] } = parseCommandArgs(argv);+ return Boolean(values.help || values.version || command === 'help' || command === 'version');+ } catch { return true; }+ }++ /**+ * Bind this checkout to the session behind a write before any sync or side effect. Reads, help and authenticated+ * person channels keep their identity and load nothing for it.+ */+ async function bindCheckoutSession(io, positionals, values) {+ if (values.help || values.version || io.personChannel === 'view' || io.personRequest) return;+ const [command, first] = positionals;+ if (command === 'takeover' && (positionals.length !== 1 || Object.keys(values).some((key) => key !== 'json'))) {+ throw new Refused('USAGE', 'pullboard takeover takes no arguments; run pullboard takeover [--json]');+ }+ const writes = ['init', 'join', 'worktree', 'hooks', 'hook', 'skills', 'add', 'edit', 'fact', 'escalate', 'run', 'sweep',+ 'next', 'claim', 'hold', 'release', 'submit', 'done', 'verify', 'check', 'merged', 'land', 'withdraw', 'refreeze', 'reopen', 'shout', 'answer', 'pass', 'import', 'milestone', 'takeover', 'forget'];+ if (!writes.includes(command) && !(command === 'lane' && first === 'add') && !(command === 'settings' && first) && !(command === 'spec' && first === 'apply') && !(command === 'relay' && ['on', 'off'].includes(first))) return;+ if (command === 'answer' && values.as === 'person') return;+ return (await import('./cli.js')).bindWriteSession(io, positionals, values);+ }++ /** Render a refusal with agents' display names, loading the board only for a refusal that names one. */+ async function displayedRefusal(io, error) {+ return (await import('./cli-context.js')).displayedRefusal(io, error);+ }++ /** Run one command and emit its single versioned JSON result when requested (A1). */+ export async function main(argv, streams) {+ if (argv[0] === 'serve' && !startupMainTraced) {+ startupMainTraced = true;+ traceServeStartup('cli-main-enter');+ }+ // Version and help ask Git nothing, so they never load it.+ if (asksGitNothing(argv)) return runMain(argv, streams);+ const { withGitFacts } = await import('./git.js');+ return withGitFacts(() => runMain(argv, streams));+ }++ /** Parse and execute one CLI command, binding its checkout session and Git-fact scope. */+ async function runMain(argv, streams) {+ const io = commandOutput(argv, streams);+ let sync = true;+ let needsRepo = true;+ let parsed;+ let checkoutSession;+ try {+ parsed = parseCommandArgs(argv);+ const command = parsed.positionals[0];+ io.relayJson = Boolean(parsed.values.json);+ io.relayCommand = { cliOperation: command === 'done' ? 'submit' : command, cwd: resolve(io.cwd),+ positionals: parsed.positionals.slice(1),+ values: Object.fromEntries(Object.keys(parsed.values).filter(key => key !== 'json').sort().map(key => [key, parsed.values[key]])) };+ sync = Boolean(command) && !parsed.values.help && !parsed.values.version+ && !['help', 'version', 'hook', 'init', 'relay', 'tour', 'mcp', 'health', 'watch', 'digest'].includes(command)+ // A coordinator declaration on a linked clone must refuse before auto-link or relay sync.+ && !(command === 'join' && parsed.positionals[1] === (await import('./config.js')).COORDINATOR);+ needsRepo = !(parsed.values.help || parsed.values.version || command === 'help' || command === 'version');+ } catch { sync = false; needsRepo = false; }+ const git = needsRepo ? await import('./git.js') : null;+ if (parsed) {+ try {+ // Checkout identity supplies the display role even if a person-channel check refuses first.+ try { const info = needsRepo ? git.repoInfo(io.cwd) : null; if (info?.isMain) io.caller('coordinator', info.root); } catch { /* Unknown checkouts retain existing guidance. */ }+ const [command, verb] = parsed.positionals;+ const remoteRelayOn = command === 'relay' && verb === 'on' && !parsed.values.all;+ if (!parsed.values.help && !parsed.values.version &&+ (parsed.values.as === 'person' && command !== 'decisions' || command === 'relay' && ['on', 'join', 'revoke'].includes(verb) && !remoteRelayOn)) {+ (await import('./person.js')).requirePersonChannel(io.personChannel);+ io.caller('person');+ }+ checkoutSession = await bindCheckoutSession(io, parsed.positionals, parsed.values);+ if (checkoutSession?.lease) CHECKOUT_LEASES.set(io, checkoutSession.lease);+ } catch (error) {+ if (!(error instanceof Refused)) throw error;+ io.refusal(error);+ io.err(`pullboard: ${await displayedRefusal(io, error)}\nnext: ${io.refusalDocument(error).error.next}`);+ (await import('./next-steps.js')).reportBlock(io, error, { command: parsed.positionals[0] });+ io.flush(1);+ return 1;+ }+ }+ try {+ if (needsRepo) await rememberTrunk(io, git);+ traceServeStartup('cli-command-preamble-start');+ // The relay and baseline work loads only where a relay token, relay state, a link or a pending result exists.+ /** Load the work around the command when any of it could act here, or null. */+ const syncWork = async () => (sync && (await import('./local-state.js')).syncMayAct(io.cwd) ? import('./cli-sync.js') : null);+ await (await syncWork())?.syncBefore(io, main);+ traceServeStartup('cli-command-preamble-ready');+ const code = await runCommand(argv, io);+ if (code === 0) await checkoutSession?.finish?.();+ if (code === 0) await (await syncWork())?.retrySync(io);+ const status = io.exitCode(code);+ if (status === 0 && needsRepo && !parsed?.values['dry-run']) (await import('./blocks.js')).clearCompletedBlocks(io);+ io.flush(status);+ return status;+ } finally {+ CHECKOUT_LEASES.delete(io);+ CHECKOUT_BOARD_ONLY.delete(io);+ checkoutSession?.lease?.release();+ }+ }++ // This marker is emitted once when the actual CLI entrypoint finishes evaluating.+ if (process.env.PULLBOARD_STARTUP_TRACE_ENTRY+ && resolve(process.argv[1] ?? '') === resolve(process.env.PULLBOARD_STARTUP_TRACE_ENTRY)) {+ traceServeStartup('cli-module-load-complete');+ }diff --cc src/cli.jsindex 4046dcab,63006de8..f684fefa--- a/src/cli.js+++ b/src/cli.js@@@ -2265,120 -1735,4 +1735,3 @@@ export function privateNames(root, boaradd(hostname().split('.')[0]);return { names: [...names], parts: [...parts] };}-- /** Retain the primary branch on every command without creating a board for global help. */- function rememberTrunk(io) {- let info;- try { info = repoInfo(io.cwd); }- catch (error) {- if (error instanceof Refused && ['NOT_A_REPO', 'NO_REPO', 'CORE_BARE'].includes(error.code)) return;- throw error;- }- if (!info.isMain) return;- const primary = mainCheckout(info.root);- if (primary?.branch) trunkRef(info.root, primary.branch);- }-- /** Run one command and emit its single versioned JSON result when requested (A1). */- export async function main(argv, streams) {- if (argv[0] === 'serve' && !startupMainTraced) {- startupMainTraced = true;- traceServeStartup('cli-main-enter');- }- return withGitFacts(() => runMain(argv, streams));- }-- /** Parse and execute one CLI command, binding its checkout session and Git-fact scope. */- async function runMain(argv, streams) {- const io = commandOutput(argv, streams);- let sync = true;- let needsRepo = true;- let parsed;- let checkoutSession;- try {- parsed = parseCommandArgs(argv);- const command = parsed.positionals[0];- io.relayJson = Boolean(parsed.values.json);- io.relayCommand = { cliOperation: command === 'done' ? 'submit' : command, cwd: resolve(io.cwd),- positionals: parsed.positionals.slice(1),- values: Object.fromEntries(Object.keys(parsed.values).filter(key => key !== 'json').sort().map(key => [key, parsed.values[key]])) };- sync = Boolean(command) && !parsed.values.help && !parsed.values.version- && !['help', 'version', 'hook', 'init', 'relay', 'tour', 'mcp', 'health', 'watch', 'digest'].includes(command)- // A coordinator declaration on a linked clone must refuse before auto-link or relay sync.- && !(command === 'join' && parsed.positionals[1] === COORDINATOR);- needsRepo = !(parsed.values.help || parsed.values.version || command === 'help' || command === 'version');- } catch { sync = false; needsRepo = false; }- if (parsed) {- try {- // Checkout identity supplies the display role even if a person-channel check refuses first.- try { const info = needsRepo ? repoInfo(io.cwd) : null; if (info?.isMain) io.caller('coordinator', info.root); } catch { /* Unknown checkouts retain existing guidance. */ }- const [command, verb] = parsed.positionals;- const remoteRelayOn = command === 'relay' && verb === 'on' && !parsed.values.all;- if (!parsed.values.help && !parsed.values.version &&- (parsed.values.as === 'person' && command !== 'decisions' || command === 'relay' && ['on', 'join', 'revoke'].includes(verb) && !remoteRelayOn)) {- requirePersonChannel(io.personChannel);- io.caller('person');- }- checkoutSession = await bindCheckoutSession(io, parsed.positionals, parsed.values);- if (checkoutSession?.lease) CHECKOUT_LEASES.set(io, checkoutSession.lease);- } catch (error) {- if (!(error instanceof Refused)) throw error;- io.refusal(error);- io.err(`pullboard: ${displayedRefusal(io, error)}\nnext: ${io.refusalDocument(error).error.next}`);- reportBlock(io, error, { command: parsed.positionals[0] });- io.flush(1);- return 1;- }- }- try {- /** A network refusal preserves offline reads; linked mutation dispatch requires an acknowledgement. */- const retry = async () => {- try {- io.relayOutbox ??= () => relayOutboxSetting(io.cwd);- await syncRelay(io.cwd, io);- await retryCheckBaselines(io.cwd, io);- }- catch (error) {- if (!(error instanceof Refused)) throw error;- if (!['NOT_A_REPO', 'NO_REPO', 'NO_CONFIG', 'CORE_BARE'].includes(error.code)) io.err(`pullboard: ${displayedRefusal(io, error)}\nnext: ${io.refusalDocument(error).error.next}`);- }- };- if (needsRepo) rememberTrunk(io);- traceServeStartup('cli-command-preamble-start');- if (sync) {- try { await autoLinkProject(io.cwd, io); } catch (error) { if (!(error instanceof Refused)) throw error; }- await retry();- try { await executePersonRequests(io.cwd, io, main); }- catch (error) {- if (!(error instanceof Refused)) throw error;- if (!['NOT_A_REPO', 'NO_REPO', 'NO_CONFIG', 'CORE_BARE'].includes(error.code)) io.err(`pullboard: ${displayedRefusal(io, error)}\nnext: ${io.refusalDocument(error).error.next}`);- }- }- traceServeStartup('cli-command-preamble-ready');- const code = await runCommand(argv, io);- if (code === 0) await checkoutSession?.finish?.();- if (sync && code === 0) await retry();- const status = io.exitCode(code);- if (status === 0 && needsRepo && !parsed?.values['dry-run']) clearCompletedBlocks(io);- io.flush(status);- return status;- } finally {- CHECKOUT_LEASES.delete(io);- CHECKOUT_BOARD_ONLY.delete(io);- checkoutSession?.lease?.release();- }- }-- /** Result-producing command names, including aliases, for API contract coverage (A1). */- export function resultCommands() {- return Object.keys(COMMANDS).filter((name) => !UNLISTED_COMMANDS.includes(name)).sort();- }-- /** Command help follows the same dispatch declarations as execution. */- export const HELP = buildHelp(resultCommands());--- // This marker is emitted once when the actual CLI entrypoint finishes evaluating.- if (process.env.PULLBOARD_STARTUP_TRACE_ENTRY- && resolve(process.argv[1] ?? '') === resolve(process.env.PULLBOARD_STARTUP_TRACE_ENTRY)) {- traceServeStartup('cli-module-load-complete');- }diff --cc src/commands/resume.jsindex 35512d67,e74da4f9..e2a2431b--- a/src/commands/resume.js+++ b/src/commands/resume.js@@@ -201,19 -202,16 +201,18 @@@ export async function resumeHere(io, vi};});card.relayProblems = unlinkedRelayProjects();- card.diagnostics = { command: 'pullboard resume --diagnostics' };- card.hookProblems = unwiredHookProblems(root);- card.newWorktreeLocation = mainRoot- ? worktreeLocation(mainRoot, worktreeConfig)- : unavailableWorktreeLocation();+ if (diagnostics) {+ card.hookProblems = unwiredHookProblems(root);+ card.newWorktreeLocation = mainRoot+ ? worktreeLocation(mainRoot, worktreeConfig)+ : unavailableWorktreeLocation();+ }const { me } = card;const name = (id) => agentDisplayName(card.agents, ctx.config, id);- card.stale = staleFrozenItems(card.all, loadSpec(root, ctx.config).rows, staleDoctrineRows(ctx, doctrine)).map((item) => ({ ...item, ...staleItemFinding(item) }));- if (isMain) {+ if (diagnostics) card.stale = staleFrozenItems(card.all, loadSpec(root, ctx.config).rows, staleDoctrineRows(ctx, doctrine)).map((item) => ({ ...item, ...staleItemFinding(item) }));+ if (isMain && diagnostics) {card.staleFollowUps = { count: card.stale.length + card.staleIntegrations.length,- list: 'pullboard resume --json', items: card.stale, integrations: card.staleIntegrations };+ list: 'pullboard resume --diagnostics --json', items: card.stale, integrations: card.staleIntegrations };delete card.staleIntegrations;card.reviewQueue = { items: card.toVerify, awaiting: card.awaiting };}@@@ -345,7 -331,7 +344,8 @@@}/** Run `pullboard resume` and return its exit code. */-export async function run(io) {+export async function run(io, { values }) {repoInfo(io.cwd);- return resumeHere(io, await keepViewRunning(), Boolean(values.diagnostics));- return resumeHere(io, await keepViewRunning());++ // JSON v1 retains its real diagnostic fields; only the default text card defers them.++ return resumeHere(io, await keepViewRunning(), Boolean(values.diagnostics || values.json));}diff --cc src/help.jsindex 586ce261,5b099785..06c359e9--- a/src/help.js+++ b/src/help.js@@@ -56,8 -56,9 +56,9 @@@ Set upullboard relay tokens list this board's agent token ids, agents and expiry, never credentialspullboard relay revoke <token-id> revoke one token from that list; other agents keep workingpullboard relay recover --skip <sequence> person-only recovery of one blocked next relay position- pullboard resume where you are: your claim, branch, uncommitted work, what came back,+ pullboard resume [--diagnostics] where you are: your claim, branch, what came back,unread shouts, what to do next; run it to start any session+ pullboard badge write board-derived Shields endpoint JSON to docs/badges/pullboard hooks reinstall the git hooks (e.g. after a fresh clone)Workdiff --cc src/next-step-words.jsindex 00000000,cb930781..df957c20mode 000000,100644..100644--- a/src/next-step-words.js+++ b/src/next-step-words.js@@@ -1,0 -1,599 +1,599 @@@+ /** 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({+ 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',++ HEALTH_FINDINGS: 'run pullboard health to read the current findings, then run pullboard sentinel run to record a fresh observation',++ HEALTH_SCAN_STALE: 'run pullboard sentinel run 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/resume-needs.jsindex 9afac84b,00000000..79c099ebmode 100644,000000..100644--- a/src/resume-needs.js+++ b/src/resume-needs.js@@@ -1,17 -1,0 +1,17 @@@+/** Resume's complete person obligations without adding optional projections to the status path [N19,N26]. */+import * as store from './board.js';+import { pendingFit } from './blueprint-fit.js';+import { projectFit } from './blueprint-fit.js';+import { repoInfo } from './git.js';- import { personNeedsSummary } from './needs-state.js';++import { personNeedsSummary } from './needs-summary.js';+import { personNeeds } from './needs.js';+import { undraftedRigor } from './rigor-notices.js';++/** Extend the indexed summary only for resume; retain exact row decisions, fit and coordinator Rigor. */+export function resumeNeeds(root, { board, config, includeRigorUndrafted = false }) {+ const summary = personNeedsSummary(root, { board, config });+ // Resume consumes obligations, not dashboard items. Fit still decorates every current spec row.+ const fitted = projectFit(pendingFit(repoInfo(root).commonDir), { ...summary, items: [] });+ return { ...fitted, needs: personNeeds(fitted), ...(includeRigorUndrafted+ ? { rigorUndrafted: undraftedRigor(store.events(board), summary, { person: store.PERSON }) } : {}) };+}diff --cc test/git-calls.test.jsindex 155b36be,b6e2c72c..66f9262a--- a/test/git-calls.test.js+++ b/test/git-calls.test.js@@@ -1,7 -1,13 +1,13 @@@/** Count real Git child processes and prove command-scoped facts refresh after a commit [C7]. */import assert from 'node:assert/strict';+ import {+ createHash,+ randomUUID,+ } from 'node:crypto';+ import * as store from '../src/board.js';+ import { receiptBody } from '../src/gate-run-receipt.js';import { runFixtureExecFile as execFileSync, runFixtureChild as spawnSync, runFixtureChild } from './fixture-child.js';-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';import { delimiter, join, resolve } from 'node:path';import { tmpdir } from 'node:os';import { test } from 'node:test';@@@ -116,24 -131,49 +131,65 @@@ test('help starts no Git and linked-worconst status = resetAndCount(box, box.worker, 'status', '--json');assert.ok(status.count <= 4, `linked-worktree status started ${status.count} Git processes`);assert.equal(JSON.parse(status.result.stdout).me.id, 'core-1');++});++/** Keep the ordinary work card on indexed reads and four fresh Git children, with diagnostics explicit. */+test('ordinary resume reads its indexed work card with at most four Git processes [N19,N26,C7]', t => {+ const box = fixture(t);+ const resumed = resetAndCount(box, box.worker, 'resume', '--json');+ assert.ok(resumed.count <= 4, `linked-worktree resume started ${resumed.count} Git processes`);+ const card = JSON.parse(resumed.result.stdout);+ assert.equal(card.me.id, 'core-1');+ assert.equal(realpathSync(card.root), realpathSync(box.worker));- assert.equal(card.diagnostics.command, 'pullboard resume --diagnostics');- for (const name of ['setup', 'hookProblems', 'dirty', 'staleVerdicts']) {- assert.equal(Object.hasOwn(card, name), false, `${name} remains an explicit diagnostic`);- }++ assert.equal(card.dirty, 0, 'JSON v1 measures the clean private checkout');++ assert.deepEqual(card.toMerge, []);++ assert.deepEqual(card.stale, []);++ assert.equal(typeof card.newWorktreeLocation, 'string');+ assert.equal(typeof card.next, 'string');});+ /** Record schema-valid private fixture history, never represented as a real gate execution. */+ function seedRuleBudgetRun(box, { green = true, days = 0, tree, command, failures = [] } = {}) {+ const head = box.git(box.repo, 'rev-parse', 'HEAD');+ const gate = JSON.parse(readFileSync(join(box.repo, 'pullboard.json'), 'utf8')).gate;+ const receipt = { version: 1, id: randomUUID(), kind: 'gate', head, main: head,+ tree: tree ?? box.git(box.repo, 'rev-parse', 'HEAD^{tree}'),+ command: createHash('sha256').update(command ?? gate).digest('hex'), green, failures,+ at: new Date(Date.now() - days * 86_400_000).toISOString(), load: { average: [0, 0, 0], cpus: 1, freeMB: 100 } };+ const folder = join(box.repo, '.git', 'pullboard', 'gate-receipts');+ mkdirSync(folder, { recursive: true });+ writeFileSync(join(folder, `${receipt.id}.json`), receiptBody(receipt));+ const board = store.openBoard(join(box.repo, '.git', 'pullboard', 'board.sqlite'), undefined, { isMain: true });+ try { store.recordGateRun(board, { agentId: 'coordinator', receipt, lane: 'core' }); }+ finally { store.closeBoard(board); }+ }++ test('populated rule receipt history preserves the linked status Git budget and current proof [C7,S1,A1]', (t) => {+ const box = fixture(t, { ruleProof: true });+ seedRuleBudgetRun(box, { green: false, days: 8, failures: [{ file: 'test/proven.test.js', name: 'expired red' }] });+ seedRuleBudgetRun(box, { green: false, days: 2, failures: [{ file: 'test/red.test.js', name: 'recent red' }] });+ seedRuleBudgetRun(box, { tree: 'f'.repeat(40) });+ seedRuleBudgetRun(box, { command: 'true' });+ seedRuleBudgetRun(box);+ const current = resetAndCount(box, box.worker, 'status', '--json');+ assert.ok(current.count <= 4, `populated linked-worktree status started ${current.count} Git processes`);+ assert.deepEqual(JSON.parse(current.result.stdout).ruleCounts,+ { approved: 2, gated: 2, ungated: 0, proven: 1, unproven: 1, contradicted: 1 });+ box.git(box.repo, 'pack-refs', '--all', '--prune');+ const packed = resetAndCount(box, box.worker, 'status', '--json');+ assert.ok(packed.count <= 4, `packed-ref status started ${packed.count} Git processes`);+ assert.deepEqual(JSON.parse(packed.result.stdout).ruleCounts, JSON.parse(current.result.stdout).ruleCounts);+ advanceHead(box, 'advance trunk after recorded proof');+ seedRuleBudgetRun(box, { tree: 'e'.repeat(40) });+ seedRuleBudgetRun(box, { command: 'true' });+ const advanced = resetAndCount(box, box.worker, 'status', '--json');+ assert.ok(advanced.count <= 4, `advanced-trunk status started ${advanced.count} Git processes`);+ assert.deepEqual(JSON.parse(advanced.result.stdout).ruleCounts,+ { approved: 2, gated: 2, ungated: 0, proven: 0, unproven: 2, contradicted: 1 },+ 'old green, wrong tree and wrong command prove nothing on the new tip; recent red is independent');+ });+test('a runner sees the new HEAD after it commits its item [C7]', (t) => {const box = fixture(t);box.ok(box.repo, 'add', 'core', 'Refresh cached HEAD', '--specs', 'C7', '--route', 'light',