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.

perf(resume): read indexed card with explicit diagnostics [N19,N26]

Corey Olsona43d24391723
diff --git a/docs/api.md b/docs/api.md
index 10a9f386..d0213270 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -609,6 +609,8 @@ A project may declare a `staticChecks` command in `pullboard.json` (empty by def
`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.
+
`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.
diff --git a/src/cli.js b/src/cli.js
index 48f9c5d2..3e3df7d1 100644
--- a/src/cli.js
+++ b/src/cli.js
@@ -535,6 +535,7 @@ const OPTIONS = {
...SENTINEL_OPTIONS,
...QUALITY_OPTIONS,
yes: { type: 'boolean' },
+ diagnostics: { type: 'boolean' },
landing: { type: 'boolean' },
adopt: { type: 'boolean' },
waive: { type: 'string' },
diff --git a/src/commands/resume.js b/src/commands/resume.js
index 07cc9dc4..8bd180a7 100644
--- a/src/commands/resume.js
+++ b/src/commands/resume.js
@@ -66,6 +66,7 @@ import {
loadSpec,
} from '../spec.js';
import { initialSpecApprovalBaseline } from '../spec-approval-bootstrap.js';
+import { readResumeSources } from '../resume-sources.js';
import {
flowAlertLine,
} from '../stats-flow.js';
@@ -132,9 +133,10 @@ function keylessBookkeeping(send) {
*
* @param {any} io
* @param {Awaited<ReturnType<typeof keepViewRunning>>} view what keeping the background view running did
+ * @param {boolean} diagnostics include explicit setup, hook and stale-work inspection
* @returns {number}
*/
-export async function resumeHere(io, view) {
+export async function resumeHere(io, view, diagnostics = false) {
const ctx = context(io);
const ordered = keylessBookkeeping(sendOrdered);
const initialBaseline = withBoardRead(ctx, board => {
@@ -150,16 +152,18 @@ export async function resumeHere(io, view) {
}
resumeSentinels({ ctx, withBoard: withBoardRead });
const { root, isMain } = ctx.info;
- const mainRoot = primaryCheckoutRoot(ctx.info);
+ const mainRoot = diagnostics ? primaryCheckoutRoot(ctx.info) : null;
const worktreeConfig = mainRoot ? (isMain ? ctx.config : loadConfig(mainRoot)) : null;
let setupScope;
let doctrine;
- const card = withBoardRead(ctx, (board) => {
- setupScope = setupIdentity(board);
- doctrine = agentDoctrine(ctx, board);
+ let sources;
+ const card = await withBoardRead(ctx, async (board) => {
+ setupScope = diagnostics ? setupIdentity(board) : null;
+ sources = diagnostics ? null : await readResumeSources(ctx, board);
+ doctrine = diagnostics ? agentDoctrine(ctx, board) : sources.doctrine;
const me = whoAmI(ctx, board);
- const projector = verdictProjector(root, board);
- const all = store.listItems(board, { all: true }).map(projector.project);
+ const projector = diagnostics ? verdictProjector(root, board) : null;
+ const all = store.listItems(board, { all: true }).map(item => projector ? projector.project(item) : item);
const pendingMerges = all.filter((item) => item.item_status === 'verified' && !item.item_merged_commit)
.map(item => ({ ...item, item_checked_commit: store.checkedLandingCommit(board, item) }));
const toMerge = pendingMerges.filter(item => !item.item_verdict_state);
@@ -173,7 +177,7 @@ export async function resumeHere(io, view) {
all,
needsYou: personNeeds(needsState),
...(me.id === COORDINATOR ? { rigor: { undrafted: needsState.rigorUndrafted } } : {}),
- ...(decisionSections ? { ...decisions, ...verifiedMergeGroups(root, pendingMerges, shouts, ctx.clock.now().getTime()),
+ ...(decisionSections ? { ...decisions, ...(diagnostics ? verifiedMergeGroups(root, pendingMerges, shouts, ctx.clock.now().getTime()) : {}),
flow: proofStats(board, { now: ctx.clock.now().getTime() }).flow } : {}),
requests: me.id === COORDINATOR ? store.openRequests(board) : [],
holding: all.filter((item) => item.item_status === 'claimed' && item.item_owner === me.id),
@@ -185,8 +189,7 @@ export async function resumeHere(io, view) {
mainMerges: mainMergesFor(board, all.filter((item) => item.item_status === 'open' && item.item_built_by === me.id)),
awaiting: all.filter((item) => item.item_status === 'submitted' && item.item_built_by === me.id),
toVerify: all.filter((item) => item.item_status === 'submitted' && item.item_built_by !== me.id),
- toMerge,
- staleVerdicts,
+ ...(diagnostics ? { toMerge, staleVerdicts } : { acceptedAwaitingLanding: pendingMerges }),
...(isMain ? { landingBatches: store.landingBatches(board) } : {}),
open: all.filter((item) => item.item_status === 'open'),
hold: store.laneHold(board, me.lane),
@@ -195,20 +198,23 @@ export async function resumeHere(io, view) {
newest: store.peekShouts(board, me.id, 1),
...(me.id === COORDINATOR ? { inbox: coordinatorInbox(board, me.id, decisions.openDecisions ?? store.openDecisions(board, COORDINATOR)) } : {}),
agents: store.listAgents(board),
- viewOpened: viewSetupComplete(ctx, board),
+ ...(diagnostics ? { viewOpened: viewSetupComplete(ctx, board) } : {}),
};
});
card.relayProblems = unlinkedRelayProjects();
- card.hookProblems = unwiredHookProblems(root);
- card.newWorktreeLocation = mainRoot
- ? worktreeLocation(mainRoot, worktreeConfig)
- : unavailableWorktreeLocation();
+ card.diagnostics = { command: 'pullboard resume --diagnostics' };
+ 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 };
}
@@ -222,7 +228,7 @@ export async function resumeHere(io, view) {
if (releaseNotes?.omitted) say(`${releaseNotes.omitted} earlier release${releaseNotes.omitted === 1 ? '' : 's'} omitted; see the full notes in CHANGELOG.md`);
else if (releaseNotes?.releases.length) say('Full release notes: CHANGELOG.md');
for (const problem of card.relayProblems) say(problem.message);
- for (const problem of card.hookProblems) say(`${problem.message}; ${problem.next}`);
+ for (const problem of card.hookProblems ?? []) say(`${problem.message}; ${problem.next}`);
const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
say(`resume: ${me.displayName}${me.family ? ` [family ${me.family}]` : ''}, ${me.lane} lane${isMain ? ', the main checkout' : ''}, at ${root}`);
if (card.health.recordedAt) {
@@ -233,8 +239,10 @@ export async function resumeHere(io, view) {
// A view left running needs no line at every session start; a start, a busy port or a failure does.
if (view.state !== 'running' && backgroundViewLine(view)) say(backgroundViewLine(view));
if (card.inbox) for (const line of coordinatorInboxLines(card.inbox, name, (at) => span(ctx, at), firstLine)) say(line);
- say(`New agent worktrees: ${card.newWorktreeLocation}`);
- card.setup = withBoardRead(ctx, board => withStarterWork(boardSetup(ctx, card, setupScope), { board, me, main: isMain, config: ctx.config, root, seat: ctx.io.callerRole() === 'seat' }));
+ if (diagnostics) {
+ say(`New agent worktrees: ${card.newWorktreeLocation}`);
+ card.setup = withBoardRead(ctx, board => withStarterWork(boardSetup(ctx, card, setupScope), { board, me, main: isMain, config: ctx.config, root, seat: ctx.io.callerRole() === 'seat' }));
+ } else say('Setup, hook and stale-work diagnostics: pullboard resume --diagnostics.');
if (!loadSpec(root, ctx.config).rows.length && card.all.length) say('Spec rows are optional; add a requirement later: pullboard spec draft "<text>".');
if (card.setup) {
say(`Setting up: step ${card.setup.step} of 5`);
@@ -243,18 +251,20 @@ export async function resumeHere(io, view) {
if (card.setup.afterAnswer) say(card.setup.afterAnswer);
if (card.setup.meanwhile) say(card.setup.meanwhile);
}
- const dirty = dirtyFiles(root).length;
+ const dirty = diagnostics ? dirtyFiles(root).length : undefined;
if (!isMain) {
- const branch = tryGit(root, ['rev-parse', '--abbrev-ref', 'HEAD']).stdout || 'HEAD';
+ const branch = diagnostics ? tryGit(root, ['rev-parse', '--abbrev-ref', 'HEAD']).stdout || 'HEAD' : sources.branch;
// Against the main checkout's branch, not its HEAD, which is detached while the coordinator verifies.
- const mainRef = worktreeEntries(root)[0]?.branch;
- const [behind = 0, ahead = 0] = mainRef ? tryGit(root, ['rev-list', '--left-right', '--count', `${mainRef}...HEAD`]).stdout.split(/\s+/).map(Number) : [];
+ const mainRef = diagnostics ? worktreeEntries(root)[0]?.branch : sources.mainRef;
+ const [behind = 0, ahead = 0] = diagnostics
+ ? mainRef ? tryGit(root, ['rev-list', '--left-right', '--count', `${mainRef}...HEAD`]).stdout.split(/\s+/).map(Number) : []
+ : [sources.behind, sources.ahead];
const against = mainRef ? `${ahead} ahead of main, ${behind} behind${behind ? ' (merge main before you submit)' : ''}` : 'main is detached for a verification, so ahead and behind are unknown';
say(`branch ${branch}: ${against}${dirty ? `; ${plural(dirty, 'file')} uncommitted` : ''}`);
} else if (dirty) {
say(`${plural(dirty, 'file')} uncommitted in the main checkout`);
}
- if (isMain) {
+ if (isMain && diagnostics) {
card.commits = commitOwners(uncommittedSetup(root, ctx.config)?.differ ?? [], [ctx.config.spec, ctx.config.practice], root);
for (const line of commitOwnerLines(card.commits)) say(line);
}
@@ -271,9 +281,9 @@ export async function resumeHere(io, view) {
say(`sent back: #${item.item_id} ${verdict ? `${verdict.verdict_reason} by ${name(verdict.verdict_by)}: ${firstLine(verdict.verdict_note)}` : 'rejected'}`);
}
for (const { item, merge } of card.mainMerges) say(mainMergeLines(item, merge, name).join('; '));
- if (isMain && card.staleFollowUps.count) say(`${plural(card.staleFollowUps.count, 'stale follow-up')}; list them with ${card.staleFollowUps.list}`);
- else if (!isMain) for (const item of card.stale) say(`stale: ${item.message}; next: ${item.next}`);
- for (const item of card.staleVerdicts) say(staleVerdictRefusal(item, item.item_verdict_state).message);
+ if (isMain && diagnostics && card.staleFollowUps.count) say(`${plural(card.staleFollowUps.count, 'stale follow-up')}; list them with ${card.staleFollowUps.list}`);
+ else if (!isMain && diagnostics) for (const item of card.stale) say(`stale: ${item.message}; next: ${item.next}`);
+ for (const item of card.staleVerdicts ?? []) say(staleVerdictRefusal(item, item.item_verdict_state).message);
if (card.awaiting.length) say(`awaiting a verdict: ${card.awaiting.map((item) => `#${item.item_id} (${span(ctx, item.item_updated_at)})`).join(', ')}`);
if (isMain) {
for (const batch of card.landingBatches.filter((entry) => !['landed', 'blocked'].includes(entry.state))) say(`landing ${batch.id}: ${batch.state}, owner ${batch.owner}, tip ${batch.tip}; log ${batch.logPath}; next: pullboard land --adopt`);
@@ -284,13 +294,13 @@ export async function resumeHere(io, view) {
};
section(card.openDecisions, (ask) => `open decision #${ask.id} from ${name(ask.asker)} (${ask.age}): ${firstLine(ask.question)}`);
section(card.recentAnswers, (answer) => `recent decision #${answer.id}: ${name(answer.answeredBy)} answered ${name(answer.asker)} (${answer.age} ago): ${firstLine(answer.answer)}`);
- if (card.toMerge.length || card.staleVerdicts.length) {
+ if (diagnostics && (card.toMerge.length || card.staleVerdicts.length)) {
const groups = card.verifiedNotMerged;
// Conflicts remain useful diagnostics even when the acceptance must be re-reviewed.
const freshness = item => item.item_verdict_state ? ' [STALE_VERDICT]' : '';
/** Keep merge groups on one line while retaining all entries in JSON. */
const listed = (entries, line) => entries.slice(0, 3).map(line).join(', ')
- + (entries.length > 3 ? `, +${entries.length - 3} more (pullboard resume --json)` : '') || 'none';
+ + (entries.length > 3 ? `, +${entries.length - 3} more (pullboard resume --diagnostics --json)` : '') || 'none';
say(`verified, not merged — merges cleanly: ${listed(groups.clean, (item) => `#${item.item_id} ${firstLine(item.item_title)}${freshness(item)}`)}`);
say(`verified, not merged — conflicts: ${listed(groups.conflicts, ({ item, files }) => `#${item.item_id} ${firstLine(item.item_title)} (${files.join(', ') || 'files unavailable'})${freshness(item)}`)}`);
say(`verified, not merged — claimed for integration: ${listed(groups.integrating, ({ item, by, at, commit }) => `#${item.item_id} by ${name(by)} at ${at} (${commit.slice(0, 12)})${freshness(item)}`)}`);
@@ -301,7 +311,8 @@ export async function resumeHere(io, view) {
section(card.rigor?.undrafted ?? [], (cause) => `Rigor needs a proved draft: ${cause.key}, items ${cause.items.map(item => `#${item.id}`).join(', ')}; pullboard rigor draft "${cause.key.replaceAll('"', '\\"')}" "<rule>" --check "<command>" --red <commit> --green <commit>`);
if (card.toVerify.length) say('review queue:');
section(card.toVerify, (item) => ` to verify: #${item.item_id} ${item.item_lane} (${span(ctx, item.item_updated_at)})`);
- if (card.toMerge.length) say('merge verified work, run the gate, then record each with pullboard merged <id> <commit>');
+ if (diagnostics && card.toMerge.length) say('merge verified work, run the gate, then record each with pullboard merged <id> <commit>');
+ if (!diagnostics && card.acceptedAwaitingLanding.length) say(`Last accepted receipts awaiting landing checks: ${card.acceptedAwaitingLanding.map(item => `#${item.item_id}`).join(', ')}; pullboard land checks their current verdicts.`);
for (const hold of card.holds) say(`held: the ${hold.hold_lane} lane, ${hold.hold_reason}`);
const byLane = Object.entries(Map.groupBy(card.open, (item) => item.item_lane)).map(([lane, items]) => `${lane} ${items.length}`);
say(`open: ${card.open.length}${byLane.length ? ` (${byLane.join(', ')})` : ''}`);
@@ -313,7 +324,10 @@ export async function resumeHere(io, view) {
const isVerified = (id) => card.all.find((other) => other.item_id === Number(id))?.item_status === 'verified';
const ready = inLane.filter((item) => !item.item_after || item.item_after.split(',').every(isVerified)).length;
let next;
- if (isMain) next = coordinatorNext(card, loadSpec(root, ctx.config).rows);
+ if (isMain) {
+ next = coordinatorNext(diagnostics ? card : { ...card, toMerge: card.acceptedAwaitingLanding, staleVerdicts: [] }, loadSpec(root, ctx.config).rows);
+ if (!diagnostics && next.startsWith('merge #')) next = 'pullboard land (checks current verdicts before merging)';
+ }
else if (card.holding.length) next = buildNext(card);
else if (card.sentBack.length) next = reworkNext(card);
else if (card.hold) next = 'wait for the hold to lift: pullboard next --wait 9 (minutes)';
@@ -324,7 +338,7 @@ export async function resumeHere(io, view) {
if (card.setup) next = card.setup.agentNext ?? card.setup.command;
if (card.commits) next = commitFirst(card.commits, next);
if (card.inbox) next = inboxFirst(card.inbox, next);
- io.result?.({ ...card, root, dirty, next });
+ io.result?.({ ...card, root, ...(diagnostics ? { dirty } : {}), next });
say(`next: ${next}`);
const flowAlert = isMain ? flowAlertLine(card.flow) : null;
if (flowAlert) say(flowAlert);
@@ -332,7 +346,7 @@ export async function resumeHere(io, view) {
}
/** 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());
+ return resumeHere(io, await keepViewRunning(), Boolean(values.diagnostics));
}
diff --git a/src/committed-file-reader.js b/src/committed-file-reader.js
new file mode 100644
index 00000000..5302feb6
--- /dev/null
+++ b/src/committed-file-reader.js
@@ -0,0 +1,80 @@
+/** Read pinned committed text files through one fresh Git batch, never a candidate's working bytes [N19,D1]. */
+import { spawn } from 'node:child_process';
+import { cleanGitEnvironment } from './git.js';
+import { Refused } from './refused.js';
+
+/** Keep one child for sequential dependent file requests, and drain it on success or the original read failure. */
+export async function withCommittedFiles(root, action) {
+ const child = spawn('git', ['--no-replace-objects', 'cat-file', '--batch'], {
+ cwd: root, env: cleanGitEnvironment(), stdio: ['pipe', 'pipe', 'pipe'],
+ });
+ const finished = new Promise(resolve => {
+ child.once('error', error => resolve({ error }));
+ child.once('close', (code, signal) => resolve({ code, signal }));
+ });
+ // The read/exit result reports a broken pipe without an unrelated unhandled stream error.
+ child.stdin.on('error', () => {});
+ child.stderr.resume();
+ const chunks = child.stdout[Symbol.asyncIterator]();
+ let buffer = Buffer.alloc(0);
+ let failed = false;
+ const files = new Map();
+ /** Collect exactly the bytes the Git header declares, retaining anything for the next frame. */
+ async function bytes(size) {
+ while (buffer.length < size) {
+ const chunk = await chunks.next();
+ if (chunk.done) throw new Refused('NO_POLICY', 'committed resume sources could not be read; inspect them with pullboard resume --diagnostics');
+ buffer = Buffer.concat([buffer, chunk.value]);
+ }
+ const result = buffer.subarray(0, size);
+ buffer = buffer.subarray(size);
+ return result;
+ }
+ /** Read a bounded metadata line without treating file contents as Git protocol. */
+ async function header() {
+ for (;;) {
+ const end = buffer.indexOf(10);
+ if (end >= 0) return (await bytes(end + 1)).subarray(0, end).toString('utf8');
+ if (buffer.length > 8192) throw new Refused('NO_POLICY', 'the committed-file response header is invalid; run pullboard doctor');
+ const chunk = await chunks.next();
+ if (chunk.done) throw new Refused('NO_POLICY', 'the committed-file reader stopped; inspect the project with pullboard doctor');
+ buffer = Buffer.concat([buffer, chunk.value]);
+ }
+ }
+ /** Request only an exact commit and one ordinary file path; a missing blob keeps existing fallback behavior. */
+ async function readOne(commit, file) {
+ if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u.test(commit ?? '') || typeof file !== 'string' || /[\r\n\0]/u.test(file)) {
+ throw new Refused('NO_POLICY', 'the committed resume source is not a valid file reference; run pullboard resume --diagnostics');
+ }
+ const key = `${commit}:${file}`;
+ if (files.has(key)) return files.get(key);
+ child.stdin.write(`${key}\n`);
+ const line = await header();
+ if (line === `${key} missing`) { files.set(key, null); return null; }
+ const matched = /^(?:[0-9a-f]{40}|[0-9a-f]{64}) blob ([0-9]+)$/u.exec(line);
+ const size = matched ? Number(matched[1]) : NaN;
+ if (!Number.isSafeInteger(size) || size < 0 || size > 32 * 1024 * 1024) {
+ throw new Refused('NO_POLICY', 'the committed resume source is not a bounded regular file; run pullboard resume --diagnostics');
+ }
+ const source = (await bytes(size)).toString('utf8');
+ if ((await bytes(1))[0] !== 10) throw new Refused('NO_POLICY', 'the committed-file response is incomplete; run pullboard doctor');
+ files.set(key, source);
+ return source;
+ }
+ let pending = Promise.resolve();
+ /** Serialize requests so concurrent consumers cannot cross the batch response frames. */
+ function read(commit, file) {
+ const result = pending.then(() => readOne(commit, file));
+ pending = result.catch(() => {});
+ return result;
+ }
+ try { return await action(read); }
+ catch (error) { failed = true; throw error; }
+ finally {
+ await pending;
+ child.stdin.end();
+ child.stdout.resume();
+ const result = await finished;
+ if (!failed && (result.error || result.code !== 0)) throw new Refused('NO_POLICY', 'the committed-file reader failed; inspect the project with pullboard resume --diagnostics');
+ }
+}
diff --git a/src/help.js b/src/help.js
index b6dfaee9..586ce261 100644
--- a/src/help.js
+++ b/src/help.js
@@ -56,7 +56,7 @@ Set up
pullboard relay tokens list this board's agent token ids, agents and expiry, never credentials
pullboard relay revoke <token-id> revoke one token from that list; other agents keep working
pullboard 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 hooks reinstall the git hooks (e.g. after a fresh clone)
@@ -363,6 +363,10 @@ const HELP_FLAG_EXPLANATIONS = {
/** Lines a command's own help adds after its example. */
const HELP_NOTES = {
+ resume: [
+ 'Ordinary resume reads the current work card and recorded health without running diagnostics or watches.',
+ 'Use --diagnostics explicitly for setup, hooks, dirty files and stale-work checks.',
+ ],
'sentinel run': [
'Schedule this command with cron on a server or a scheduled CI job that already has ordinary board access.',
'For example: 0 * * * * cd /path/to/project && pullboard sentinel run',
diff --git a/src/next-steps.js b/src/next-steps.js
index 53987649..121e9acd 100644
--- a/src/next-steps.js
+++ b/src/next-steps.js
@@ -145,8 +145,8 @@ export const NEXT_STEPS = Object.freeze({
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',
diff --git a/src/resume-sources.js b/src/resume-sources.js
new file mode 100644
index 00000000..650beca7
--- /dev/null
+++ b/src/resume-sources.js
@@ -0,0 +1,92 @@
+/** Fresh, bounded Git facts for the ordinary resume card; detailed diagnostics stay explicit [N19,D1]. */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
+import { realpathSync } from 'node:fs';
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import * as store from './board.js';
+import { CONFIG_FILE } from './config.js';
+import { DOCTRINE_FILE } from './config.js';
+import { LEGACY_DOCTRINE_FILE } from './config.js';
+import { configFromSource } from './config.js';
+import { withCommittedFiles } from './committed-file-reader.js';
+import { appliedDoctrine } from './doctrine.js';
+import { doctrineFromSource } from './doctrine.js';
+import { agentDoctrine } from './doctrine-rulings.js';
+import { cleanGitEnvironment } from './git.js';
+import { headCommit } from './git.js';
+import { mainCheckout } from './git.js';
+import { tryGit } from './git.js';
+import { Refused } from './refused.js';
+
+/** Compare actual filesystem identities without granting a guessed metadata parent project authority. */
+function samePath(left, right) {
+ try { return Boolean(left && right) && realpathSync.native(left) === realpathSync.native(right); }
+ catch { return false; }
+}
+
+/** Read one NUL-delimited listing, so unusual path characters never become record separators. */
+function worktrees(root) {
+ const result = spawnSync('git', ['--no-replace-objects', '-c', 'core.quotepath=false', 'worktree', 'list', '--porcelain', '-z'], {
+ cwd: root, env: cleanGitEnvironment(), encoding: 'utf8', maxBuffer: 32 * 1024 * 1024,
+ });
+ if (result.status !== 0) throw new Refused('NO_POLICY', 'the worktree facts could not be read; run pullboard resume --diagnostics');
+ return result.stdout.split('\0\0').filter(Boolean).map(block => {
+ const fields = block.split('\0');
+ return { path: fields.find(field => field.startsWith('worktree '))?.slice(9),
+ branch: fields.find(field => field.startsWith('branch '))?.slice(7) };
+ });
+}
+
+/** Validate the primary's normal .git directory; separate metadata retains the established registry/Git fallback. */
+async function primaryPath(info, listed) {
+ const primary = listed[0]?.path;
+ const marker = primary && join(primary, '.git');
+ try {
+ if (marker && statSync(marker).isDirectory() && samePath(marker, info.commonDir)) return primary;
+ } catch { /* A missing or nonstandard primary must use the existing fail-closed resolver. */ }
+ const { primaryCheckoutRoot } = await import('./cli.js');
+ return primaryCheckoutRoot(info);
+}
+
+/** Read shared committed guidance and exact applied decisions through one Git child, not working-file authority. */
+async function sharedDoctrine(ctx, board, primary, main) {
+ if (!main?.commit) return agentDoctrine(ctx, board);
+ const snapshot = await withCommittedFiles(ctx.info.root, async read => {
+ const config = await read(main.commit, CONFIG_FILE);
+ if (config === null) return ctx.doctrine;
+ let name = configFromSource(config).practice;
+ let source = await read(main.commit, name);
+ if (source === null && [DOCTRINE_FILE, LEGACY_DOCTRINE_FILE].includes(name)) {
+ const alias = name === DOCTRINE_FILE ? LEGACY_DOCTRINE_FILE : DOCTRINE_FILE;
+ const other = await read(main.commit, alias);
+ if (other !== null) { name = alias; source = other; }
+ }
+ return doctrineFromSource(source, name);
+ });
+ const file = primary && join(primary, snapshot.name);
+ const current = file && existsSync(file) ? readFileSync(file, 'utf8') : null;
+ return appliedDoctrine(snapshot, store.rowDecisions(board), current);
+}
+
+/** Keep the command's verified trunk/HEAD snapshot, current branch and complete shared doctrine together. */
+export async function readResumeSources(ctx, board) {
+ const root = ctx.info.root;
+ const main = mainCheckout(root);
+ const listed = worktrees(root);
+ const primary = await primaryPath(ctx.info, listed);
+ const current = listed.find(entry => samePath(entry.path, root));
+ const branch = current ? current.branch?.replace(/^refs\/heads\//u, '') ?? 'HEAD'
+ : tryGit(root, ['rev-parse', '--abbrev-ref', 'HEAD']).stdout || 'HEAD';
+ let ahead;
+ let behind;
+ if (main?.commit && !ctx.info.isMain) {
+ const head = headCommit(root);
+ const compared = head && tryGit(root, ['rev-list', '--left-right', '--count', `${main.commit}...${head}`]);
+ const counts = compared?.status === 0 && /^([0-9]+)\s+([0-9]+)$/u.exec(compared.stdout);
+ if (!counts) throw new Refused('NO_POLICY', 'the branch could not be compared with main; run pullboard resume --diagnostics');
+ behind = Number(counts[1]); ahead = Number(counts[2]);
+ }
+ return { doctrine: await sharedDoctrine(ctx, board, primary, main), branch, mainRef: main?.branch, ahead, behind };
+}
diff --git a/test/checked-composition-resume.test.js b/test/checked-composition-resume.test.js
index 5a6c697d..0bbe4c46 100644
--- a/test/checked-composition-resume.test.js
+++ b/test/checked-composition-resume.test.js
@@ -92,7 +92,7 @@ test('coordinator resume guides and groups the checked composition after stale r
const view = await helpers.startView(box, box.repo);
await view.stop();
- const resumed = box.run(box.repo, 'resume', '--json');
+ const resumed = box.run(box.repo, 'resume', '--diagnostics', '--json');
assert.equal(resumed.code, 0, resumed.err || resumed.out);
const document = JSON.parse(resumed.out);
assert.equal(document.setup, null, 'the actual view bind completed setup before merge guidance is judged');
diff --git a/test/coordinator-resume.test.js b/test/coordinator-resume.test.js
index c8670d07..e760d01d 100644
--- a/test/coordinator-resume.test.js
+++ b/test/coordinator-resume.test.js
@@ -241,7 +241,19 @@ test("the coordinator's handoff brief orders current work and leaves agent resum
const currentSpec = readFileSync(join(box.repo, 'SPEC.md'), 'utf8');
writeFileSync(join(box.repo, 'SPEC.md'), currentSpec.replace('The first feature works.', 'The first feature works differently.'));
- const resumed = box.run(box.repo, 'resume');
+ const ordinary = box.run(box.repo, 'resume', '--json');
+ assert.equal(ordinary.code, 0, ordinary.err || ordinary.out);
+ const indexed = JSON.parse(ordinary.out);
+ assert.equal(indexed.openDecisions.length, 5, 'ordinary resume retains current coordinator obligations');
+ assert.ok(indexed.acceptedAwaitingLanding.some(item => item.item_id === conflictId),
+ 'the old receipt remains visible without claiming its verdict is current');
+ for (const name of ['toMerge', 'staleVerdicts', 'verifiedNotMerged']) {
+ assert.equal(Object.hasOwn(indexed, name), false, 'fresh merge eligibility is an explicit diagnostic');
+ }
+ assert.equal(indexed.diagnostics.command, 'pullboard resume --diagnostics');
+ assert.doesNotMatch(indexed.next, /^git merge|^merge #/u, 'ordinary guidance retains guarded landing authority');
+
+ const resumed = box.run(box.repo, 'resume', '--diagnostics');
assert.equal(resumed.code, 0, resumed.err);
assert.ok(resumed.out.length < 4_000, `handoff brief should stay short (${resumed.out.length} characters)`);
assert.equal((resumed.out.match(/^open decision /gmu) ?? []).length, 3, 'text caps each section while JSON keeps all records');
@@ -256,7 +268,7 @@ test("the coordinator's handoff brief orders current work and leaves agent resum
assert.match(resumed.out, new RegExp(`waiting on the person: #${personQuestionId} from coordinator`));
assert.match(resumed.out, /review queue:/u);
assert.match(resumed.out, new RegExp(`review queue:[\\s\\S]*?to verify: #${reviewId} web \\(`));
- assert.match(resumed.out, /4 stale follow-ups; list them with pullboard resume --json/u,
+ assert.match(resumed.out, /4 stale follow-ups; list them with pullboard resume --diagnostics --json/u,
'the three stale row follow-ups and expired evidence collapse into one counted line');
assert.equal((resumed.out.match(/^stale:/gmu) ?? []).length, 0, 'stale details collapse to one line');
const positions = [
@@ -269,7 +281,7 @@ test("the coordinator's handoff brief orders current work and leaves agent resum
assert.ok(positions.every((position) => position >= 0) && positions.every((position, index) => index === 0 || positions[index - 1] < position),
'the handoff sections stay in the requested order');
- const json = box.run(box.repo, 'resume', '--json');
+ const json = box.run(box.repo, 'resume', '--diagnostics', '--json');
assert.equal(json.code, 0, json.err || json.out);
const document = JSON.parse(json.out);
assert.equal(document.version, 1);
@@ -296,12 +308,12 @@ test("the coordinator's handoff brief orders current work and leaves agent resum
assert.equal(document.staleFollowUps.count, 4);
assert.deepEqual(document.staleFollowUps.items.map((item) => item.id).sort((a, b) => a - b), [cleanId, conflictId, activeId]);
assert.deepEqual(document.staleFollowUps.integrations.map((entry) => entry.item.item_id), [expiredId]);
- assert.equal(document.staleFollowUps.list, 'pullboard resume --json');
+ assert.equal(document.staleFollowUps.list, 'pullboard resume --diagnostics --json');
- const agentText = box.run(cleanBuilder, 'resume').out;
+ const agentText = box.run(cleanBuilder, 'resume', '--diagnostics').out;
assert.match(agentText, /^resume: web-1/u);
assert.doesNotMatch(agentText, /open decision |recent decision |verified, not merged|waiting on the person|review queue:/u);
- const agentJson = JSON.parse(box.run(cleanBuilder, 'resume', '--json').out);
+ const agentJson = JSON.parse(box.run(cleanBuilder, 'resume', '--diagnostics', '--json').out);
for (const section of ['openDecisions', 'recentAnswers', 'verifiedNotMerged', 'personQuestions', 'reviewQueue', 'staleFollowUps']) {
assert.equal(Object.hasOwn(agentJson, section), false, `agent resume keeps coordinator-only ${section} fields absent`);
}
diff --git a/test/doctor.test.js b/test/doctor.test.js
index e549a374..13e9f8eb 100644
--- a/test/doctor.test.js
+++ b/test/doctor.test.js
@@ -112,7 +112,7 @@ test('doctor names an unwired hook and resume gives the repair line [L3]', () =>
assert.equal(doctor.status, 1);
assert.equal(doctor.stdout.split('\n').filter((line) => line.includes(expected)).length, 1, doctor.stdout);
assert.ok(doctor.stdout.includes(`${expected}; repair: add this line: pullboard hook pre-commit "$@"`), doctor.stdout);
- const resume = box.run('resume');
+ const resume = box.run('resume', '--diagnostics');
assert.equal(resume.status, 0, resume.stderr);
assert.equal(resume.stdout.split('\n').filter((line) => line.includes(expected)).length, 1, resume.stdout);
assert.ok(resume.stdout.includes(`${expected}; add this line: pullboard hook pre-commit "$@"`), resume.stdout);
@@ -120,7 +120,7 @@ test('doctor names an unwired hook and resume gives the repair line [L3]', () =>
assert.equal(doctorJson.status, 1);
const finding = { code: 'HOOK_UNWIRED', message: expected, next: 'add this line: pullboard hook pre-commit "$@"' };
assert.deepEqual(JSON.parse(doctorJson.stdout).problems, [finding]);
- const resumeJson = box.run('resume', '--json');
+ const resumeJson = box.run('resume', '--diagnostics', '--json');
assert.equal(resumeJson.status, 0, resumeJson.stderr);
assert.deepEqual(JSON.parse(resumeJson.stdout).hookProblems, [finding]);
@@ -128,7 +128,7 @@ test('doctor names an unwired hook and resume gives the repair line [L3]', () =>
chmodSync(join(hooks, 'pre-commit'), 0o755);
box.git('config', 'core.hooksPath', hooks);
assert.doesNotMatch(box.run('doctor').stdout, /HOOK_UNWIRED|active Git hook/u);
- assert.doesNotMatch(box.run('resume').stdout, /HOOK_UNWIRED|active Git hook/u);
+ assert.doesNotMatch(box.run('resume', '--diagnostics').stdout, /HOOK_UNWIRED|active Git hook/u);
});
@@ -166,11 +166,11 @@ test('doctor and resume accept env delegation that real Git executes [L3]', () =
const doctor = box.run('doctor');
assert.equal(doctor.status, 0, 'an executed env delegation is wired');
assert.equal(doctor.stdout, 'board is clean\n');
- const resume = box.run('resume');
+ const resume = box.run('resume', '--diagnostics');
assert.equal(resume.status, 0);
assert.doesNotMatch(resume.stdout, /active Git hook|HOOK_UNWIRED/u);
assert.deepEqual(JSON.parse(box.run('doctor', '--json').stdout).problems, []);
- assert.deepEqual(JSON.parse(box.run('resume', '--json').stdout).hookProblems, []);
+ assert.deepEqual(JSON.parse(box.run('resume', '--diagnostics', '--json').stdout).hookProblems, []);
assert.equal(readFileSync(box.marker, 'utf8'), '', 'diagnosis never executes the hook');
assert.equal(readFileSync(box.hook, 'utf8'), source, 'diagnosis never edits the hook');
}
@@ -192,11 +192,11 @@ test('doctor and resume accept env assignments that real Git executes [L3]', ()
const doctor = box.run('doctor');
assert.equal(doctor.status, 0, 'an executed env delegation is wired');
assert.equal(doctor.stdout, 'board is clean\n');
- const resume = box.run('resume');
+ const resume = box.run('resume', '--diagnostics');
assert.equal(resume.status, 0);
assert.doesNotMatch(resume.stdout, /active Git hook|HOOK_UNWIRED/u);
assert.deepEqual(JSON.parse(box.run('doctor', '--json').stdout).problems, []);
- assert.deepEqual(JSON.parse(box.run('resume', '--json').stdout).hookProblems, []);
+ assert.deepEqual(JSON.parse(box.run('resume', '--diagnostics', '--json').stdout).hookProblems, []);
assert.equal(readFileSync(box.marker, 'utf8'), '', 'diagnosis never executes the hook');
assert.equal(readFileSync(box.hook, 'utf8'), source, 'diagnosis never edits the hook');
}
@@ -220,18 +220,18 @@ test('doctor and resume reject printed heredocs that real Git never executes [L3
const doctor = box.run('doctor');
assert.equal(doctor.status, 1, 'printed heredoc text cannot wire the active hook');
assert.ok(doctor.stdout.includes(message + '; repair: ' + finding.next));
- const resume = box.run('resume');
+ const resume = box.run('resume', '--diagnostics');
assert.equal(resume.status, 0);
assert.ok(resume.stdout.includes(message + '; ' + finding.next));
assert.deepEqual(JSON.parse(box.run('doctor', '--json').stdout).problems, [finding]);
- assert.deepEqual(JSON.parse(box.run('resume', '--json').stdout).hookProblems, [finding]);
+ assert.deepEqual(JSON.parse(box.run('resume', '--diagnostics', '--json').stdout).hookProblems, [finding]);
assert.equal(readFileSync(box.marker, 'utf8'), '', 'diagnosis never executes the printed example');
assert.equal(readFileSync(box.hook, 'utf8'), source, 'diagnosis leaves documentation untouched');
writeFileSync(box.hook, source + delegation + '\n');
box.git('commit', '--allow-empty', '-q', '-m', 'chore: exact repair control');
assert.match(readFileSync(box.marker, 'utf8'), /^hook pre-commit\n$/u, 'the exact repair line really invokes the CLI');
assert.equal(box.run('doctor').stdout, 'board is clean\n');
- assert.doesNotMatch(box.run('resume').stdout, /active Git hook|HOOK_UNWIRED/u);
+ assert.doesNotMatch(box.run('resume', '--diagnostics').stdout, /active Git hook|HOOK_UNWIRED/u);
}
});
diff --git a/test/doctrine-rulings.test.js b/test/doctrine-rulings.test.js
index 0e9fea39..1cf4d358 100644
--- a/test/doctrine-rulings.test.js
+++ b/test/doctrine-rulings.test.js
@@ -108,12 +108,12 @@ test('a ruling the person approves reaches every agent once [D1,D3,B27]', (t) =>
const replacement = 'A builder stops after two failed attempts. Source: chat, 2026-10-16';
json(box.repo, 'spec', 'approve', drafted.id, '--text', replacement);
- assert.deepEqual(json(box.web, 'resume').stale, [], 'an unapplied change does not replace the in-force ruling');
+ assert.deepEqual(json(box.web, 'resume', '--diagnostics').stale, [], 'an unapplied change does not replace the in-force ruling');
json(box.repo, 'spec', 'apply');
- const changed = json(box.web, 'resume');
+ const changed = json(box.web, 'resume', '--diagnostics');
assert.ok(changed.stale.some(entry => entry.id === item.item_id && entry.rows.includes(drafted.id)), 'the old checkout detects the changed frozen row');
assert.equal(changed.doctrineNotes[0].text, replacement);
- const again = json(box.web, 'resume');
+ const again = json(box.web, 'resume', '--diagnostics');
assert.deepEqual(again.doctrineNotes, []);
assert.ok(again.stale.some(entry => entry.id === item.item_id), 'staleness remains after its one-time notice');
@@ -167,19 +167,19 @@ test('local doctrine edits flag their frozen row without hiding shared approved
json(box.web, 'release', String(item.item_id));
}
const frozen = [shared, edited].map(item => json(box.web, 'show', String(item.item_id)).item_frozen);
- const baseline = json(box.web, 'resume');
+ const baseline = json(box.web, 'resume', '--diagnostics');
assert.deepEqual(baseline.stale, [], 'unchanged old-checkout files retain the shared approved rule');
assert.ok(baseline.doctrineNotes.some(note => note.id === drafted.id));
const file = join(box.web, 'DOCTRINE.md');
const original = readFileSync(file, 'utf8');
assert.ok(!original.includes('Keep shared approved guidance visible.'));
writeFileSync(file, original + '\n## Local diagnostic edit\n- PB1 [approved, must] A changed local inherited rule. | gate: true\n');
- const changed = json(box.web, 'resume');
+ const changed = json(box.web, 'resume', '--diagnostics');
assert.deepEqual(changed.stale.map(item => [item.id, item.rows]), [[edited.item_id, ['doctrine:PB1']]],
'only the locally edited rule is stale; shared approved guidance is still available');
assert.deepEqual(changed.doctrineNotes, [], 'an unapproved working-copy edit is not announced as new guidance');
assert.equal(box.git(box.web, 'rev-parse', 'HEAD'), oldHead, 'diagnostics never advance the old checkout');
assert.deepEqual([shared, edited].map(item => json(box.web, 'show', String(item.item_id)).item_frozen), frozen);
writeFileSync(file, original);
- assert.deepEqual(json(box.web, 'resume').stale, [], 'restoring the working file clears only its diagnostic change');
+ assert.deepEqual(json(box.web, 'resume', '--diagnostics').stale, [], 'restoring the working file clears only its diagnostic change');
});
diff --git a/test/e2e.test.js b/test/e2e.test.js
index 8bd65689..8fdcdb88 100644
--- a/test/e2e.test.js
+++ b/test/e2e.test.js
@@ -114,21 +114,21 @@ test("init's spec has its sections and no rows, and the README's example fits un
});
test("the coordinator's resume names its next step from the spec and the board, stage by stage [N32, I9]", async () => {
- const next = (box, cwd) => /^next: (.*)$/m.exec(box.run(cwd, 'resume').out)?.[1] ?? '';
+ const next = (box, cwd) => /^next: (.*)$/m.exec(box.run(cwd, 'resume', '--diagnostics').out)?.[1] ?? '';
const fresh = sandbox();
const repo = join(fresh.dir, 'fresh');
mkdirSync(repo);
fresh.git(repo, 'init', '-q', '-b', 'main');
const initialized = fresh.run(repo, 'init', '--verbose');
assert.match(initialized.out, /^Next: ask your agent to set up Pullboard here; in Claude Code, start a new session first so it loads the Pullboard skills\.$/m, 'init gives one setup instruction and preserves Claude Code skill loading');
- const firstSetup = JSON.parse(fresh.run(repo, 'resume', '--json').out).setup;
+ const firstSetup = JSON.parse(fresh.run(repo, 'resume', '--diagnostics', '--json').out).setup;
assert.equal(firstSetup?.step, 1, 'a new board starts by asking what the person wants');
assert.equal(next(fresh, repo), firstSetup.command);
assert.equal(fresh.run(repo, 'add', 'coordinator', 'Tidy the readme').code, 0);
assert.equal(fresh.run(repo, 'claim', '1').code, 0);
- assert.equal(JSON.parse(fresh.run(repo, 'resume', '--json').out).setup.step, 2, 'a working board with an item and no spec rows treats the spec as optional (#866)');
+ assert.equal(JSON.parse(fresh.run(repo, 'resume', '--diagnostics', '--json').out).setup.step, 2, 'a working board with an item and no spec rows treats the spec as optional (#866)');
writeFileSync(join(repo, 'SPEC.md'), '# Fresh\n\n## G · Goals\n- G1 [draft, must] It works. | gate: test\n');
- assert.equal(JSON.parse(fresh.run(repo, 'resume', '--json').out).setup.step, 1, 'nor the approval');
+ assert.equal(JSON.parse(fresh.run(repo, 'resume', '--diagnostics', '--json').out).setup.step, 1, 'nor the approval');
writeFileSync(join(repo, 'SPEC.md'), '# Fresh\n\n## G · Goals\n- G1 [approved, must] It works. | gate: test\n');
writeFileSync(join(repo, 'pullboard.json'), JSON.stringify(CONFIG));
fresh.env.PULLBOARD_VIEW_FOREGROUND = '1';
@@ -140,7 +140,7 @@ test("the coordinator's resume names its next step from the spec and the board,
box.env.PULLBOARD_VIEW_FOREGROUND = '1';
const view = await startView(box, box.repo);
await view.stop();
- const firstItem = JSON.parse(box.run(box.repo, 'resume', '--json').out).setup;
+ const firstItem = JSON.parse(box.run(box.repo, 'resume', '--diagnostics', '--json').out).setup;
assert.equal(firstItem?.step, 4, 'setup asks for the first small piece before planning the remaining rows');
assert.equal(next(box, box.repo), firstItem.command);
box.run(box.repo, 'add', 'web', 'Page', '--specs', 'G1');
diff --git a/test/git-calls.test.js b/test/git-calls.test.js
index 1a4cd528..938b42e2 100644
--- a/test/git-calls.test.js
+++ b/test/git-calls.test.js
@@ -107,7 +107,7 @@ function readFactScenario(box, root, body) {
return JSON.parse(result.stdout.trim());
}
-test('help starts no Git and linked-worktree status spawns at most four Git processes [C7]', (t) => {
+test('help starts no Git and linked-worktree status and resume use at most four Git processes [C7,N19]', (t) => {
const box = fixture(t);
const version = resetAndCount(box, box.dir, '--version');
assert.equal(version.count, 0, '--version has no repository work to do');
@@ -116,6 +116,16 @@ test('help starts no Git and linked-worktree status spawns at most four Git proc
const 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');
+ 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(card.root, 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(typeof card.next, 'string');
});
test('primary checkout facts reuse one canonical listing and refresh on Git changes [C7,N26]', (t) => {
@@ -362,3 +372,40 @@ console.log(JSON.stringify(facts));
assert.deepEqual({ head: result.head, tree: result.tree }, { head: null, tree: null },
'missing HEAD facts stay null rather than turning into a NOT_A_REPO refusal');
});
+
+/** Exercise real Git batch framing, pinned bytes and refusal cleanup rather than mocking the stream. */
+test('committed resume files use one framed Git child and retain pinned Unicode bytes [N19,D1,C7]', t => {
+ const box = fixture(t);
+ const file = 'rules with spaces.md';
+ const source = '# Rules\n\nλ 🙂 café\n';
+ writeFileSync(join(box.repo, file), source);
+ writeFileSync(join(box.repo, 'empty.md'), '');
+ mkdirSync(join(box.repo, 'nested'));
+ writeFileSync(join(box.repo, 'nested/item.md'), 'nested\n');
+ box.git(box.repo, 'add', file, 'empty.md', 'nested/item.md');
+ box.git(box.repo, 'commit', '-q', '-m', 'test: commit framed doctrine sources');
+ const commit = box.git(box.repo, 'rev-parse', 'HEAD');
+ writeFileSync(join(box.repo, file), 'uncommitted replacement');
+ const moduleUrl = pathToFileURL(resolve(import.meta.dirname, '../src/committed-file-reader.js')).href;
+ const result = readFactScenario(box, box.worker, `
+import assert from 'node:assert/strict';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { withCommittedFiles } from ${JSON.stringify(moduleUrl)};
+const root = process.argv[1];
+const commit = ${JSON.stringify(commit)};
+writeFileSync(process.env.PULLBOARD_GIT_CALLS, '');
+const values = await withCommittedFiles(root, async read => Promise.all([
+ read(commit, ${JSON.stringify(file)}), read(commit, 'missing.md'),
+ read(commit, 'empty.md'), read(commit, 'nested/item.md'), read(commit, ${JSON.stringify(file)}),
+]));
+assert.deepEqual(values, [${JSON.stringify(source)}, null, '', 'nested\\n', ${JSON.stringify(source)}]);
+const count = readFileSync(process.env.PULLBOARD_GIT_CALLS, 'utf8').trim().split('\\n').filter(Boolean).length;
+assert.equal(count, 1, 'dependent and concurrent reads share exactly one Git child');
+await assert.rejects(withCommittedFiles(root, read => read('a'.repeat(41), 'file')), error => error.code === 'NO_POLICY');
+await assert.rejects(withCommittedFiles(root, read => read(commit, 'line\\nprotocol')), error => error.code === 'NO_POLICY');
+await assert.rejects(withCommittedFiles(root, read => read(commit, 'nested')), error => error.code === 'NO_POLICY');
+console.log(JSON.stringify({ count, values }));
+`);
+ assert.equal(result.count, 1);
+ assert.deepEqual(result.values, [source, null, '', 'nested\n', source]);
+});
diff --git a/test/init-gate.test.js b/test/init-gate.test.js
index 3f29d858..c6d11508 100644
--- a/test/init-gate.test.js
+++ b/test/init-gate.test.js
@@ -143,7 +143,7 @@ test('a repo without package.json is told a gate that fits it [C7,B26]', () => {
assert.equal(existsSync(marker), false, 'init does not execute a project command it has not detected');
assert.match(initialized.out, /ask the person which command tests this project/u);
const initializedGate = JSON.parse(readFileSync(join(root, 'pullboard.json'), 'utf8')).gate;
- const pending = box.run(root, 'resume', '--json');
+ const pending = box.run(root, 'resume', '--diagnostics', '--json');
assert.equal(pending.code, 0, pending.err || pending.out);
assert.equal(JSON.parse(pending.out).setup.steps.find(step => step.number === 3).done, false,
'an unknown project keeps its gate choice unanswered');
@@ -193,7 +193,7 @@ test('a repo without package.json is told a gate that fits it [C7,B26]', () => {
writeFileSync(join(root, 'pullboard.json'), JSON.stringify(chosenConfig, null, 2));
box.git(root, 'add', 'pullboard.json');
box.git(root, 'commit', '-q', '-m', 'chore: choose the project test command');
- const chosen = box.run(root, 'resume', '--json');
+ const chosen = box.run(root, 'resume', '--diagnostics', '--json');
assert.equal(chosen.code, 0, chosen.err || chosen.out);
assert.equal(JSON.parse(chosen.out).setup.steps.find(step => step.number === 3).done, true,
'the person choosing an actual project command completes the gate step');
@@ -236,14 +236,14 @@ test('the gate is set with one pullboard command [I1,A1,B26]', () => {
box.git(root, 'add', '-A');
box.git(root, 'commit', '-q', '-m', 'chore: prepare a board without a gate');
- const resumed = box.run(root, 'resume', '--json');
+ const resumed = box.run(root, 'resume', '--diagnostics', '--json');
assert.equal(resumed.code, 0, resumed.err || resumed.out);
assert.equal(JSON.parse(resumed.out).setup.step, 3);
const step = JSON.parse(resumed.out).setup.steps.find(entry => entry.number === 3);
assert.equal(step.done, false);
assert.match(step.command, /^pullboard gate set /u);
assert.doesNotMatch(step.command, /node -e|writeFileSync/u);
- const resumedText = box.run(root, 'resume');
+ const resumedText = box.run(root, 'resume', '--diagnostics');
assert.equal(resumedText.code, 0, resumedText.err || resumedText.out);
assert.ok(resumedText.out.includes(step.command));
assert.doesNotMatch(resumedText.out, /node -e.*pullboard\.json/u);
@@ -264,7 +264,7 @@ test('the gate is set with one pullboard command [I1,A1,B26]', () => {
assert.equal(JSON.parse(configured.out).gate, command);
assert.deepEqual(JSON.parse(readFileSync(configFile, 'utf8')), { ...before, gate: command });
assert.equal(existsSync(marker), false, 'setting the command neither executes it nor stamps it green');
- const answered = box.run(root, 'resume', '--json');
+ const answered = box.run(root, 'resume', '--diagnostics', '--json');
assert.equal(answered.code, 0, answered.err || answered.out);
assert.equal(JSON.parse(answered.out).setup.steps.find(entry => entry.number === 3).done, true);
diff --git a/test/newcomer.test.js b/test/newcomer.test.js
index 4182f356..da095fd0 100644
--- a/test/newcomer.test.js
+++ b/test/newcomer.test.js
@@ -151,7 +151,7 @@ test('setup offers a gate to a board with no build [I1,I2]', (t) => {
const specPath = join(box.root, 'SPEC.md');
writeFileSync(specPath, `${readFileSync(specPath, 'utf8')}- G1 [approved, must] The board can check its own requirements. | gate: pullboard spec check\n`);
- const before = JSON.parse(box.run('resume', '--json').stdout);
+ const before = JSON.parse(box.run('resume', '--diagnostics', '--json').stdout);
assert.equal(before.setup.step, 3);
assert.match(before.setup.question, /if this board has no build.*pullboard spec check.*second agent review checks the actual work/u);
assert.match(before.setup.question, /choose a custom gate command/u);
@@ -159,7 +159,7 @@ test('setup offers a gate to a board with no build [I1,I2]', (t) => {
const answer = runFixtureChild('sh', ['-c', before.setup.command], { cwd: box.root, env: box.env, encoding: 'utf8' });
assert.equal(answer.status, 0, answer.failure ?? answer.stderr);
assert.equal(JSON.parse(readFileSync(configPath, 'utf8')).gate, 'pullboard spec check');
- assert.equal(JSON.parse(box.run('resume', '--json').stdout).setup.step, 4);
+ assert.equal(JSON.parse(box.run('resume', '--diagnostics', '--json').stdout).setup.step, 4);
box.git('add', '-f', '--', 'pullboard.json', 'SPEC.md', 'DOCTRINE.md', 'AGENTS.md', '.gitignore', '.githooks', '.claude');
const stagedPaths = box.git('diff', '--cached', '--name-only').split('\n');
diff --git a/test/resume-flow.test.js b/test/resume-flow.test.js
index d3f3466e..340243fc 100644
--- a/test/resume-flow.test.js
+++ b/test/resume-flow.test.js
@@ -72,7 +72,7 @@ test('a worktree names its main checkout\'s uncommitted init files [I1,I2]', (t)
for (const path of ['pullboard.json', 'SPEC.md', 'DOCTRINE.md']) assert.ok(fromWorktree.stderr.includes(path), fromWorktree.stderr);
assert.doesNotMatch(fromWorktree.stderr, /worktree <lane>/u);
- const fromMain = box.run(box.repo, 'resume');
+ const fromMain = box.run(box.repo, 'resume', '--diagnostics');
assert.equal(fromMain.status, 0, fromMain.failure || fromMain.stderr || fromMain.stdout);
assert.match(fromMain.stdout, /The person must commit Pullboard's setup files before agents can use worktrees/u);
assert.ok(fromMain.stdout.includes(`cd ${box.repo} && git add`), fromMain.stdout);
@@ -90,9 +90,9 @@ test('resume asks the coordinator to commit an applied row file [I1,L3]', t => {
const ROW_LINE = 'The coordinator must commit the row file spec apply changed: ';
/** Resume's text and JSON from the main checkout, both passing, and neither naming an unrelated dirty file. */
const resume = (box) => {
- const text = box.run(box.repo, 'resume');
+ const text = box.run(box.repo, 'resume', '--diagnostics');
assert.equal(text.status, 0, text.failure || text.stderr || text.stdout);
- const json = box.run(box.repo, 'resume', '--json');
+ const json = box.run(box.repo, 'resume', '--diagnostics', '--json');
assert.equal(json.status, 0, json.failure || json.stderr || json.stdout);
const lines = text.stdout.split('\n');
const card = JSON.parse(json.stdout);
@@ -473,7 +473,7 @@ test('resume shows the coordinator its unread shouts through the SessionStart ho
test('spec draft adds draft rows and resume names them [N32]', t => {
const box = releaseFixture(t, { freshSetup: true });
- const initial = JSON.parse(box.run(box.repo, 'resume', '--json').stdout);
+ const initial = JSON.parse(box.run(box.repo, 'resume', '--diagnostics', '--json').stdout);
assert.equal(initial.setup.step, 1);
assert.match(initial.setup.command, /^pullboard spec draft/u);
assert.doesNotMatch(initial.setup.command, /node -e|appendFileSync/u);
@@ -500,7 +500,7 @@ test('spec draft adds draft rows and resume names them [N32]', t => {
assert.equal(JSON.parse(empty.stdout).error.code, 'USAGE');
assert.equal(readFileSync(join(box.repo, 'SPEC.md'), 'utf8'), beforeEmpty, 'an empty draft does not change the spec');
- const next = JSON.parse(box.run(box.repo, 'resume', '--json').stdout);
+ const next = JSON.parse(box.run(box.repo, 'resume', '--diagnostics', '--json').stdout);
assert.equal(next.setup.step, 1);
assert.match(next.setup.question, /waiting.*person.*approv/iu);
assert.deepEqual(next.setup.rowIds, ['G1', 'G2']);
@@ -532,7 +532,7 @@ test('setup lets agents build starter items while rows wait [S1,B26]', t => {
const starters = JSON.parse(box.run(box.repo, 'list', '--all', '--json').stdout).items.sort((a, b) => a.item_id - b.item_id);
const first = starters.find(item => !item.item_after);
assert.ok(first, 'the bundled blueprint files a starter with no dependency');
- const initial = JSON.parse(box.run(box.repo, 'resume', '--json').stdout);
+ const initial = JSON.parse(box.run(box.repo, 'resume', '--diagnostics', '--json').stdout);
assert.equal(initial.setup.waitingOn, 'person-approval');
assert.equal(initial.setup.buildNow?.item, first.item_id, 'setup names the first starter while rows are undecided');
assert.match(initial.setup.meanwhile, /claimed and built now.*person.*parallel/iu);
@@ -542,16 +542,16 @@ test('setup lets agents build starter items while rows wait [S1,B26]', t => {
assert.equal(lane.status, 0, lane.failure || lane.stderr);
box.git(box.repo, 'add', '-A');
box.git(box.repo, 'commit', '-q', '-m', 'chore: commit blueprint setup');
- const coordinator = box.run(box.repo, 'resume');
+ const coordinator = box.run(box.repo, 'resume', '--diagnostics');
assert.match(coordinator.stdout, /claimed and built now.*person.*parallel/iu);
assert.ok(coordinator.stdout.includes(`#${first.item_id}`), 'prose names the same first starter');
- const prepared = JSON.parse(box.run(box.repo, 'resume', '--json').stdout);
+ const prepared = JSON.parse(box.run(box.repo, 'resume', '--diagnostics', '--json').stdout);
assert.equal(prepared.setup.buildNow.command, `pullboard worktree ${first.item_lane} --model "<model name>"`);
box.env.CODEX_THREAD_ID = 'starter-builder-session';
const opened = box.run(box.repo, 'worktree', first.item_lane, '--model', 'Starter fixture', '--json');
assert.equal(opened.status, 0, opened.failure || opened.stderr);
const worktree = JSON.parse(opened.stdout).path;
- const ready = JSON.parse(box.run(worktree, 'resume', '--json').stdout);
+ const ready = JSON.parse(box.run(worktree, 'resume', '--diagnostics', '--json').stdout);
assert.equal(ready.setup.waitingOn, 'person-approval', 'approval remains a separate person decision');
assert.equal(ready.setup.buildNow.item, first.item_id);
assert.equal(ready.setup.buildNow.command, `pullboard claim ${first.item_id}`);
@@ -580,7 +580,7 @@ test("resume says setup waits on the person's approval [I1,I2]", async t => {
const ids = drafted.map(result => JSON.parse(result.stdout).id);
assert.deepEqual(ids, ['G1', 'G2']);
- const waiting = box.run(box.repo, 'resume');
+ const waiting = box.run(box.repo, 'resume', '--diagnostics');
assert.equal(waiting.status, 0, waiting.failure || waiting.stderr || waiting.stdout);
assert.match(waiting.stdout, /waiting.*person.*approv/iu, 'setup waits for the person after the rows are drafted');
for (const id of ids) assert.match(waiting.stdout, new RegExp(`\\b${id}\\b`, 'u'));
@@ -588,7 +588,7 @@ test("resume says setup waits on the person's approval [I1,I2]", async t => {
'resume names permissible independent work while approval is pending');
assert.doesNotMatch(waiting.stdout, /^next: .*spec (?:draft|approve)/mu,
'the agent is not told to draft again or perform the person-only approval');
- const waitingJson = box.run(box.repo, 'resume', '--json');
+ const waitingJson = box.run(box.repo, 'resume', '--diagnostics', '--json');
assert.equal(waitingJson.status, 0, waitingJson.failure || waitingJson.stderr || waitingJson.stdout);
const card = JSON.parse(waitingJson.stdout);
assert.equal(card.setup?.step, 1);
@@ -604,7 +604,7 @@ test("resume says setup waits on the person's approval [I1,I2]", async t => {
assert.equal(approval.status, 0, approval.failure || approval.stderr || approval.stdout);
const applied = box.run(box.repo, 'spec', 'apply');
assert.equal(applied.status, 0, applied.failure || applied.stderr || applied.stdout);
- const partial = box.run(box.repo, 'resume', '--json');
+ const partial = box.run(box.repo, 'resume', '--diagnostics', '--json');
assert.equal(partial.status, 0, partial.failure || partial.stderr || partial.stdout);
const pending = JSON.parse(partial.stdout);
assert.equal(pending.setup?.step, 1, 'one approved row does not stand in for the remaining setup draft');
@@ -614,7 +614,7 @@ test("resume says setup waits on the person's approval [I1,I2]", async t => {
assert.equal(finalApproval.status, 0, finalApproval.failure || finalApproval.stderr || finalApproval.stdout);
const finalApply = box.run(box.repo, 'spec', 'apply');
assert.equal(finalApply.status, 0, finalApply.failure || finalApply.stderr || finalApply.stdout);
- const resumed = box.run(box.repo, 'resume', '--json');
+ const resumed = box.run(box.repo, 'resume', '--diagnostics', '--json');
assert.equal(resumed.status, 0, resumed.failure || resumed.stderr || resumed.stdout);
const next = JSON.parse(resumed.stdout);
assert.equal(next.setup?.step, 2, 'person approval advances setup to its next unanswered step');
@@ -663,7 +663,7 @@ function assertViewReceipt(box) {
{ ...receipt, setupStartedAt: '2000-01-01T00:00:00.000Z' },
{ ...receipt, boundAt: '2000-01-01T00:00:00.000Z' }]) {
writeFileSync(receiptPath, JSON.stringify(invalid));
- assert.equal(JSON.parse(box.run(box.repo, 'resume', '--json').stdout).setup?.step, 5,
+ assert.equal(JSON.parse(box.run(box.repo, 'resume', '--diagnostics', '--json').stdout).setup?.step, 5,
'a receipt for another board or before this setup cannot complete it');
}
writeFileSync(receiptPath, receiptBytes);
@@ -686,7 +686,7 @@ test('a reused authenticated view completes setup for its new board [N26,N32]',
writeFileSync(file, JSON.stringify(config));
const added = box.run(box.repo, 'add', 'app', 'First setup item', '--specs', 'N19', '--criterion', 'The fixture has work.');
assert.equal(added.status, 0, added.failure || added.stderr || added.stdout);
- assert.equal(JSON.parse(box.run(box.repo, 'resume', '--json').stdout).setup?.step, 5);
+ assert.equal(JSON.parse(box.run(box.repo, 'resume', '--diagnostics', '--json').stdout).setup?.step, 5);
}
awaitingView(firstBoard);
const child = spawn(process.execPath, [join(firstBoard.root, 'cli/bin/pullboard.js'), 'view', '--no-open', '--json'],
@@ -707,7 +707,7 @@ test('a reused authenticated view completes setup for its new board [N26,N32]',
});
});
assert.equal(first.port, lease.port);
- assert.equal(JSON.parse(firstBoard.run(firstBoard.repo, 'resume', '--json').stdout).setup, null);
+ assert.equal(JSON.parse(firstBoard.run(firstBoard.repo, 'resume', '--diagnostics', '--json').stdout).setup, null);
const secondBoard = releaseFixture(t);
const refusedBoard = releaseFixture(t);
awaitingView(secondBoard);
@@ -717,7 +717,7 @@ test('a reused authenticated view completes setup for its new board [N26,N32]',
const second = JSON.parse(reused.stdout);
assert.equal(second.reused, true);
assert.equal(second.url, first.url);
- assert.equal(JSON.parse(secondBoard.run(secondBoard.repo, 'resume', '--json').stdout).setup, null,
+ assert.equal(JSON.parse(secondBoard.run(secondBoard.repo, 'resume', '--diagnostics', '--json').stdout).setup, null,
'the exact offered view command completes setup on the second board');
const receiptPath = join(secondBoard.repo, '.git/pullboard/view-reuse.json');
const bytes = readFileSync(receiptPath);
@@ -732,7 +732,7 @@ test('a reused authenticated view completes setup for its new board [N26,N32]',
{ ...receipt, setupStartedAt: '2000-01-01T00:00:00.000Z' },
{ ...receipt, openedAt: '2000-01-01T00:00:00.000Z' }]) {
writeFileSync(receiptPath, JSON.stringify(invalid));
- assert.equal(JSON.parse(secondBoard.run(secondBoard.repo, 'resume', '--json').stdout).setup?.step, 5,
+ assert.equal(JSON.parse(secondBoard.run(secondBoard.repo, 'resume', '--diagnostics', '--json').stdout).setup?.step, 5,
'another board or an observation before this setup cannot complete it');
}
writeFileSync(receiptPath, bytes);
@@ -743,7 +743,7 @@ test('a reused authenticated view completes setup for its new board [N26,N32]',
const refused = refusedBoard.run(refusedBoard.repo, 'view', '--no-open', '--json');
assert.equal(refused.status, 1, refused.failure || refused.stderr || refused.stdout);
assert.equal(JSON.parse(refused.stdout).error.code, 'PORT_BUSY');
- assert.equal(JSON.parse(refusedBoard.run(refusedBoard.repo, 'resume', '--json').stdout).setup?.step, 5,
+ assert.equal(JSON.parse(refusedBoard.run(refusedBoard.repo, 'resume', '--diagnostics', '--json').stdout).setup?.step, 5,
'an unauthenticated listener cannot complete setup');
} finally { writeFileSync(sessionPath, sessionBytes); }
});
@@ -756,10 +756,10 @@ async function finishSetup(box, observe = () => {}) {
writeFileSync(configFile, JSON.stringify({ ...config, gate: '' }));
/** Assert the next setup block in both the actual text and JSON CLI output. */
function step(number) {
- const text = box.run(box.repo, 'resume');
+ const text = box.run(box.repo, 'resume', '--diagnostics');
assert.equal(text.status, 0, text.failure || text.stderr);
assert.match(text.stdout, new RegExp(`Setting up: step ${number} of 5`));
- const json = box.run(box.repo, 'resume', '--json');
+ const json = box.run(box.repo, 'resume', '--diagnostics', '--json');
assert.equal(json.status, 0, json.failure || json.stderr);
const setup = JSON.parse(json.stdout).setup;
assert.equal(setup.step, number);
@@ -794,11 +794,11 @@ async function finishSetup(box, observe = () => {}) {
box.git(box.repo, 'commit', '-q', '-m', 'chore: set up private fixture');
const builder = box.run(box.repo, 'worktree', 'app', '--model', 'Fixture');
assert.equal(builder.status, 0, builder.failure || builder.stderr);
- const stillWaiting = JSON.parse(box.run(box.repo, 'resume', '--json').stdout);
+ const stillWaiting = JSON.parse(box.run(box.repo, 'resume', '--diagnostics', '--json').stdout);
assert.equal(stillWaiting.setup?.step, 5, 'registering a builder does not stand in for the view’s own bind receipt');
const shouted = box.run(box.repo, 'shout', 'all', 'Opened Pullboard view for this board.');
assert.equal(shouted.status, 0, shouted.failure || shouted.stderr);
- assert.equal(JSON.parse(box.run(box.repo, 'resume', '--json').stdout).setup?.step, 5,
+ assert.equal(JSON.parse(box.run(box.repo, 'resume', '--diagnostics', '--json').stdout).setup?.step, 5,
'an ordinary same-text shout cannot impersonate a successful view bind');
await openSetupView(box);
assertViewReceipt(box);
@@ -813,7 +813,7 @@ test('resume walks a new board through setup one step at a time [N32,N19]', asyn
if (number === 2) assert.match(setup.question, /Suggested folders: app/u);
});
assert.deepEqual(seen, [1, 2, 3, 4, 5]);
- const result = box.run(box.repo, 'resume', '--json');
+ const result = box.run(box.repo, 'resume', '--diagnostics', '--json');
assert.equal(result.status, 0, result.failure || result.stderr);
assert.equal(JSON.parse(result.stdout).setup, null, 'actual successful view bind completes the board setup');
});
@@ -830,9 +830,9 @@ test('resume names lane add to make a lane [I1,N32]', t => {
const result = box.run(box.repo, ...args);
assert.equal(result.status, 0, result.failure || result.stderr || result.stdout);
}
- const text = box.run(box.repo, 'resume');
+ const text = box.run(box.repo, 'resume', '--diagnostics');
assert.equal(text.status, 0, text.failure || text.stderr);
- const setup = JSON.parse(box.run(box.repo, 'resume', '--json').stdout).setup;
+ const setup = JSON.parse(box.run(box.repo, 'resume', '--diagnostics', '--json').stdout).setup;
assert.equal(setup.step, 2);
assert.equal(setup.command, 'pullboard lane add app --owns app/');
assert.ok(text.stdout.includes(setup.command), text.stdout);
@@ -843,20 +843,20 @@ test('resume names lane add to make a lane [I1,N32]', t => {
const lanes = box.run(box.repo, 'lanes');
assert.equal(lanes.status, 0, lanes.failure || lanes.stderr);
assert.match(lanes.stdout, /^app\s+app\/(?:\s|$)/mu);
- assert.equal(JSON.parse(box.run(box.repo, 'resume', '--json').stdout).setup?.step, 3);
+ assert.equal(JSON.parse(box.run(box.repo, 'resume', '--diagnostics', '--json').stdout).setup?.step, 3);
});
test("a set-up board's resume prints no setup steps [N32,N19]", async t => {
const box = releaseFixture(t, { freshSetup: true });
await finishSetup(box);
- const result = box.run(box.repo, 'resume');
+ const result = box.run(box.repo, 'resume', '--diagnostics');
assert.equal(result.status, 0, result.failure || result.stderr);
assert.doesNotMatch(result.stdout, /Setting up: step/u);
- const json = box.run(box.repo, 'resume', '--json');
+ const json = box.run(box.repo, 'resume', '--diagnostics', '--json');
assert.equal(JSON.parse(json.stdout).setup, null);
const proposed = box.run(box.repo, 'spec', 'draft', 'A later proposal for the person', '--json');
assert.equal(proposed.status, 0, proposed.failure || proposed.stderr || proposed.stdout);
- const later = box.run(box.repo, 'resume', '--json');
+ const later = box.run(box.repo, 'resume', '--diagnostics', '--json');
assert.equal(later.status, 0, later.failure || later.stderr || later.stdout);
assert.equal(JSON.parse(later.stdout).setup, null, 'a later proposal does not reopen completed setup');
});
@@ -887,7 +887,7 @@ test('a new preconfigured board waits for every initial approval [I1,I2]', async
assert.equal(result.status, 0, result.failure || result.stderr || result.stdout);
}
await openSetupView(box);
- const result = box.run(box.repo, 'resume', '--json');
+ const result = box.run(box.repo, 'resume', '--diagnostics', '--json');
assert.equal(result.status, 0, result.failure || result.stderr || result.stdout);
const setup = JSON.parse(result.stdout).setup;
assert.equal(setup?.step, 1, 'an early view and preconfigured answers cannot bypass the remaining initial approval');
@@ -896,7 +896,7 @@ test('a new preconfigured board waits for every initial approval [I1,I2]', async
for (const invalid of ['{', JSON.stringify({ ...started, boardId: 'another-board' }),
JSON.stringify({ ...started, setupStartedAt: '2000-01-01T00:00:00.000Z' })]) {
writeFileSync(marker, invalid);
- const resumed = box.run(box.repo, 'resume', '--json');
+ const resumed = box.run(box.repo, 'resume', '--diagnostics', '--json');
assert.equal(resumed.status, 0, resumed.failure || resumed.stderr || resumed.stdout);
assert.deepEqual(JSON.parse(resumed.stdout).setup?.rowIds, ['G2'],
'an invalid progress receipt is not evidence of a completed legacy setup');
@@ -916,7 +916,7 @@ test('an upgraded configured board stays set up before its first resume [I1,I2]'
'idempotent init does not classify an existing coordinator as a new enrollment');
const proposed = box.run(box.repo, 'spec', 'draft', 'A proposal drafted before the first upgraded resume', '--json');
assert.equal(proposed.status, 0, proposed.failure || proposed.stderr || proposed.stdout);
- const result = box.run(box.repo, 'resume', '--json');
+ const result = box.run(box.repo, 'resume', '--diagnostics', '--json');
assert.equal(result.status, 0, result.failure || result.stderr || result.stdout);
assert.equal(JSON.parse(result.stdout).setup, null, 'a later draft does not reopen a legacy completed setup');
const complete = JSON.parse(readFileSync(join(stateDirectory, 'setup-complete.json'), 'utf8'));
@@ -946,7 +946,7 @@ test('a board building without spec rows is not told to draft the spec first [I1
assert.equal(added.status, 0, added.failure || added.stderr || added.stdout);
assert.equal(JSON.parse(added.stdout).item.item_spec_ids, '', 'real board items need no spec rows');
for (let repeat = 0; repeat < 2; repeat++) {
- const resumed = box.run(box.repo, 'resume', '--json');
+ const resumed = box.run(box.repo, 'resume', '--diagnostics', '--json');
assert.equal(resumed.status, 0, resumed.failure || resumed.stderr || resumed.stdout);
const card = JSON.parse(resumed.stdout);
assert.notEqual(card.setup?.step, 1, 'an active rowless board skips the required spec step');
@@ -958,7 +958,7 @@ test('a board building without spec rows is not told to draft the spec first [I1
assert.match(specStep.question, /optional/iu);
assert.match(specStep.command, /pullboard spec draft/u);
}
- const text = box.run(box.repo, 'resume');
+ const text = box.run(box.repo, 'resume', '--diagnostics');
assert.equal(text.status, 0, text.failure || text.stderr || text.stdout);
assert.match(text.stdout, /spec rows are optional[^\n]*pullboard spec draft/iu,
'resume offers the way to add rows without making it the work prerequisite');
@@ -966,7 +966,7 @@ test('a board building without spec rows is not told to draft the spec first [I1
}
await openSetupView(box);
for (let repeat = 0; repeat < 2; repeat++) {
- const resumed = box.run(box.repo, 'resume', '--json');
+ const resumed = box.run(box.repo, 'resume', '--diagnostics', '--json');
assert.equal(resumed.status, 0, resumed.failure || resumed.stderr || resumed.stdout);
const card = JSON.parse(resumed.stdout);
assert.equal(card.setup, null, 'the working board can finish setup without adding rows');
diff --git a/test/spec.test.js b/test/spec.test.js
index 0cc95599..d8fa9e80 100644
--- a/test/spec.test.js
+++ b/test/spec.test.js
@@ -983,7 +983,7 @@ test('a joined seat requests answers for pending questions [S1,I1,P6]', t => {
box.git('worktree', 'add', '-q', '-b', 'build/setup', builder);
const joined = runIn(box, builder, ['join', 'build', '--model', 'Fixture']);
assert.equal(joined.status, 0, joined.stderr + joined.stdout);
- const read = runIn(box, builder, ['resume', '--json']);
+ const read = runIn(box, builder, ['resume', '--diagnostics', '--json']);
assert.equal(read.status, 0, read.stderr + read.stdout);
const card = JSON.parse(read.stdout);
assert.match(card.setup.personCommand, /pullboard spec answer Q1 "<choice>"/u);
@@ -1007,7 +1007,7 @@ test('a changed approved draft needs a new decision before apply [S1,I1,P6]', t
const staleApply = box.run('apply');
assert.equal(staleApply.status, 1, staleApply.stdout + staleApply.stderr);
assert.match(staleApply.stderr, /STALE_ROW_DECISION/u);
- const read = runIn(box, box.root, ['resume', '--json']);
+ const read = runIn(box, box.root, ['resume', '--diagnostics', '--json']);
assert.equal(read.status, 0, read.stderr + read.stdout);
const card = JSON.parse(read.stdout);
assert.equal(card.setup.waitingOn, 'person-approval', 'the old decision does not approve the changed text');
@@ -1015,11 +1015,11 @@ test('a changed approved draft needs a new decision before apply [S1,I1,P6]', t
assert.equal(card.setup.personCommand, 'pullboard spec approve A1');
assert.doesNotMatch(card.next, /spec apply/u, 'applying the stale receipt would loop');
assert.equal(box.run('approve', 'A1').status, 0, 'the person can approve the current text');
- const decided = JSON.parse(runIn(box, box.root, ['resume', '--json']).stdout);
+ const decided = JSON.parse(runIn(box, box.root, ['resume', '--diagnostics', '--json']).stdout);
assert.equal(decided.setup.waitingOn, 'coordinator-apply');
assert.equal(box.run('apply').status, 0);
runFixtureGit(['commit', '-q', '-m', 'docs(spec): apply current row decision', '--', box.specName], { cwd: box.root, env: box.env, encoding: 'utf8' });
- const applied = JSON.parse(runIn(box, box.root, ['resume', '--json']).stdout);
+ const applied = JSON.parse(runIn(box, box.root, ['resume', '--diagnostics', '--json']).stdout);
assert.doesNotMatch(applied.next, /spec apply|approve A1/u);
});
diff --git a/test/stale-frozen-items.test.js b/test/stale-frozen-items.test.js
index a565150a..ccf8b76b 100644
--- a/test/stale-frozen-items.test.js
+++ b/test/stale-frozen-items.test.js
@@ -228,7 +228,7 @@ test('[S19,V3] doctor and resume list stale frozen items in every lifecycle stat
requireExit(doctorText, 1);
for (const id of expected) assert.match(doctorText.stdout, new RegExp(`item #${id}\\b`));
const afterResumeBaseline = receiptSnapshot(box);
- const resumeJson = succeeds(box, box.root, 'resume', '--json');
+ const resumeJson = succeeds(box, box.root, 'resume', '--diagnostics', '--json');
const resumeDocument = jsonOf(resumeJson);
assert.deepEqual(resumeDocument.stale.map((item) => item.id).sort((a, b) => a - b), expected);
for (const item of resumeDocument.stale) {
@@ -238,18 +238,18 @@ test('[S19,V3] doctor and resume list stale frozen items in every lifecycle stat
assert.match(item.next, /pullboard add web .*--specs G1/u);
}
}
- const resumeText = succeeds(box, box.root, 'resume');
- assert.match(resumeText.stdout, new RegExp(`${expected.length} stale follow-ups; list them with pullboard resume --json`));
+ const resumeText = succeeds(box, box.root, 'resume', '--diagnostics');
+ assert.match(resumeText.stdout, new RegExp(`${expected.length} stale follow-ups; list them with pullboard resume --diagnostics --json`));
assert.equal((resumeText.stdout.match(/^stale:/gmu) ?? []).length, 0, 'the coordinator sees one counted line, with details in JSON');
assert.equal(resumeDocument.staleFollowUps.count, expected.length);
- assert.equal(resumeDocument.staleFollowUps.list, 'pullboard resume --json');
+ assert.equal(resumeDocument.staleFollowUps.list, 'pullboard resume --diagnostics --json');
assert.deepEqual(resumeDocument.staleFollowUps.items.map((item) => item.id).sort((a, b) => a - b), expected,
'the named listing retains every stale item across every lifecycle state');
assert.deepEqual(receiptSnapshot(box), afterResumeBaseline, 'resume leaves frozen fields, merge receipts and accepted verdicts unchanged');
assert.deepEqual(receiptSnapshot(box), before, 'diagnostics do not alter accepted receipts or frozen bars');
assert.ok(!findings.some((finding) => finding.message.includes(`item #${ids.unaffected} `)), 'the item frozen on G3 remains unaffected');
succeeds(box, box.root, 'refreeze', String(ids.open));
- const afterRefreeze = jsonOf(succeeds(box, box.root, 'resume', '--json'));
+ const afterRefreeze = jsonOf(succeeds(box, box.root, 'resume', '--diagnostics', '--json'));
assert.deepEqual(afterRefreeze.stale.map((item) => item.id).sort((a, b) => a - b), expected.filter((id) => id !== ids.open), 'explicit refreeze clears only the active item repaired against new text');
const historical = (snapshot) => snapshot.items.filter((item) => item.item_status === 'verified');
assert.deepEqual(historical(receiptSnapshot(box)), historical(before), 'refreezing active work preserves every accepted historical receipt');
@@ -265,13 +265,13 @@ test('[A5,S19,V3] doctor and resume distinguish unchanged doctrine citations fro
claim(box, specItem);
succeeds(box, box.web, 'release', String(specItem));
const baseline = receiptSnapshot(box);
- const before = jsonOf(succeeds(box, box.root, 'resume', '--json'));
+ const before = jsonOf(succeeds(box, box.root, 'resume', '--diagnostics', '--json'));
assert.deepEqual(before.stale, [], 'a namespaced citation with unchanged inherited text is current');
const doctorBefore = jsonOf(box.pullboard(box.root, 'doctor', '--json'));
assert.deepEqual(doctorBefore.problems.filter(problem => problem.code === 'STALE_ITEM'), []);
const path = join(box.root, 'DOCTRINE.md');
writeFileSync(path, readFileSync(path, 'utf8') + '\n## Local override\n- PB1 [approved, must] Updated inherited rule. | gate: true\n');
- const after = jsonOf(succeeds(box, box.root, 'resume', '--json'));
+ const after = jsonOf(succeeds(box, box.root, 'resume', '--diagnostics', '--json'));
assert.deepEqual(after.stale.map(item => [item.id, item.rows]), [[doctrineItem, ['doctrine:PB1']]]);
const doctorAfter = jsonOf(box.pullboard(box.root, 'doctor', '--json'));
const findings = doctorAfter.problems.filter(problem => problem.code === 'STALE_ITEM');
diff --git a/test/team.test.js b/test/team.test.js
index 7ecf3246..763db959 100644
--- a/test/team.test.js
+++ b/test/team.test.js
@@ -244,7 +244,7 @@ test('a verdict reads stale when main moves under its files [E8]', { timeout: 12
for (const root of [box.repo, peer]) {
assert.match(run(box, root, 'show', '1'), /STALE_VERDICT/u);
assert.equal(JSON.parse(run(box, root, 'list', '--all', '--json')).items[0].item_verdict_state?.commit, movingCommit);
- const resume = JSON.parse(run(box, root, 'resume', '--json'));
+ const resume = JSON.parse(run(box, root, 'resume', '--diagnostics', '--json'));
assert.equal(resume.all[0].item_verdict_state?.commit, movingCommit);
assert.deepEqual(resume.toMerge, [], 'resume never suggests landing a stale acceptance');
assert.equal(resume.staleVerdicts[0].item_id, 1);
diff --git a/test/worktree-start.test.js b/test/worktree-start.test.js
index 136d63ed..c315eeab 100644
--- a/test/worktree-start.test.js
+++ b/test/worktree-start.test.js
@@ -106,12 +106,12 @@ test('a new worktree is created inside the repository [I1,I2]', () => {
assert.equal(newIdentity.code, 0, newIdentity.err || newIdentity.out);
assert.equal(JSON.parse(newIdentity.out).lane, 'api');
assert.ok(existsSync(join(result.path, '.githooks', 'pre-commit')), 'the new worktree has its commit hook');
- const resumed = box.run(web, 'resume');
+ const resumed = box.run(web, 'resume', '--diagnostics');
assert.equal(resumed.code, 0, resumed.err);
assert.match(resumed.out, mode === 'inside'
? /New agent worktrees: .*\.claude\/worktrees\/<lane>-N/u
: /New agent worktrees: .*repo-<lane>-N/u);
- const resumedJson = box.run(web, 'resume', '--json');
+ const resumedJson = box.run(web, 'resume', '--diagnostics', '--json');
assert.equal(JSON.parse(resumedJson.out).newWorktreeLocation, mode === 'inside'
? join(repo, '.claude', 'worktrees', '<lane>-N')
: join(dirname(repo), `${basename(repo)}-<lane>-N`));