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.

fix(needs): relay blocks reach the person via API and relay [C6,N26]

Corey Olson7a196fc4d559
diff --git a/src/api.js b/src/api.js
index 900af9ea..851264b5 100644
--- a/src/api.js
+++ b/src/api.js
@@ -66,6 +66,10 @@ import {
projectFit,
} from './blueprint-fit.js';
import { Refused } from './refused.js';
+import {
+ BLOCKS_FILE,
+ personBlockWords,
+} from './blocks.js';
import { verdictProjector } from './verdict-freshness.js';
import { trunkRevisionReader } from './trunk-revision.js';
import {
@@ -99,6 +103,8 @@ function stateFileInputs(root, config) {
{ name: 'builtin:standard-doctrine.md', path: new URL('./standard-doctrine.md', import.meta.url) },
...['signoffs.jsonl', 'signers', 'first-commit', 'signers.initial'].map(name => ({ name: `approval:${name}`, path: join(root, '.pullboard', name) })),
{ name: 'fit:blueprint-fit.json', path: fitFile(repoInfo(root).commonDir) },
+ // A new block changes Needs you without a board move, so the ledger is a state input [C6].
+ { name: 'blocks:blocks.jsonl', path: join(repoInfo(root).commonDir, BLOCKS_FILE) },
];
}
@@ -484,6 +490,7 @@ function buildLocalBoardState(root, boardId, board, codeIsMain, { previous = nul
state.requests = projectData.requests;
state.personRequests = projectData.personRequests;
state.milestones = projectData.milestones;
+ state.blocks = personBlockWords(repoInfo(root).commonDir, board.clock.now()); // Needs you below is recomputed with them [C6].
const decorated = projectSpecApprovals(projectFit(pendingFit(repoInfo(root).commonDir), projectRowDecisions(projectData.rowDecisions, state)), specApprovalState(root, { board, config }));
const bases = new Map(decorated.items.map((item) => [item.id, item]));
for (const id of dirtyIds) {
diff --git a/src/blocks.js b/src/blocks.js
index 63775fc0..d12402da 100644
--- a/src/blocks.js
+++ b/src/blocks.js
@@ -45,3 +45,16 @@ export function readBlocks(commonDir, { since } = {}) {
}
return blocks;
}
+
+/**
+ * The last day's blocks only the person can clear, carrying only their plain words, never a local
+ * path, for every Needs you projection: the CLI, the local API and the sealed relay page [C6].
+ *
+ * @param {string} commonDir
+ * @param {Date} now
+ */
+export function personBlockWords(commonDir, now) {
+ return readBlocks(commonDir, { since: new Date(now.getTime() - 86_400_000) })
+ .filter(block => block.audience === 'person')
+ .map(({ at, code, command, audience, reason, step }) => ({ at, code, command, audience, reason, step }));
+}
diff --git a/src/commands/health.js b/src/commands/health.js
index 1cac784d..fb6da0ce 100644
--- a/src/commands/health.js
+++ b/src/commands/health.js
@@ -9,14 +9,14 @@ import {
} from '../cli.js';
import { openBoardReadOnly } from '../board.js';
import { HEALTH_SENTINEL_ENGINE } from '../health-receipts.js';
-import { recentBlocks } from '../needs-state.js';
+import { readBlocks } from '../blocks.js';
import { rigorReport } from '../rigor.js';
/** Run `pullboard health` and return its exit code. */
export function run(io) {
const ctx = context(io);
const report = boardHealth(ctx.file, { root: ctx.info.root, config: ctx.config, now: ctx.clock.now() });
- report.blocks = blockReport(recentBlocks(ctx.info.commonDir, { clock: ctx.clock }), seatsByPath(ctx.file));
+ report.blocks = blockReport(readBlocks(ctx.info.commonDir, { since: new Date(ctx.clock.now().getTime() - 86_400_000) }), seatsByPath(ctx.file));
io.result?.(report);
for (const line of healthLines(report)) io.say(line);
for (const line of blockLines(report.blocks)) io.say(line);
diff --git a/src/needs-state.js b/src/needs-state.js
index 52b4e470..da50a011 100644
--- a/src/needs-state.js
+++ b/src/needs-state.js
@@ -16,7 +16,7 @@ import {
undraftedRigor,
} from './rigor-notices.js';
import { personNeeds } from './needs.js';
-import { readBlocks } from './blocks.js';
+import { personBlockWords } from './blocks.js';
import { displayAgentName } from './agent-names.js';
import {
projectSpecApprovals,
@@ -58,8 +58,7 @@ export function personNeedsSummary(root, { board, config }) {
return projected;
}
-/** The blocks recorded in the last day, by the board's clock, for Needs you and health [C6]. */
+/** The person's blocks from the last day, by the board's clock, for Needs you [C6]. */
export function recentBlocks(commonDir, board) {
- const now = (board?.clock ?? store.systemClock).now();
- return readBlocks(commonDir, { since: new Date(now.getTime() - 86_400_000) });
+ return personBlockWords(commonDir, (board?.clock ?? store.systemClock).now());
}
diff --git a/src/next-steps.js b/src/next-steps.js
index a94e67d0..c32b699f 100644
--- a/src/next-steps.js
+++ b/src/next-steps.js
@@ -660,9 +660,15 @@ const NOT_BLOCKS = new Set(['USAGE', 'UNKNOWN_COMMAND']);
* @returns {'person'|'coordinator'|'agent'}
*/
export function blockAudience(code, message, step) {
- const words = `${message}\n${step}`;
- if (/_PERSON_ONLY$|^B26_PERSON_CHANNEL$/u.test(code) || /\bonly the person\b|\blet the person act\b|\bbring it to the person\b/iu.test(words)) return 'person';
- if (/^(?:ask (?:the|your) coordinator|the coordinator\b)/iu.test(step) || /^COORDINATOR_ONLY$|_COORDINATOR_ONLY$/u.test(code)) return 'coordinator';
+ const person = /\bonly the person\b|\blet the person act\b|\bbring it to the person\b|\bthe person (?:reissues|runs|sends|approves)\b|\bfrom the paired phone\b|\bthe person['’]s terminal\b/iu;
+ const coordinator = /\bask (?:the|your) coordinator\b|^the coordinator\b/iu;
+ if (/_PERSON_ONLY$|^B26_PERSON_CHANNEL$|^HUMAN_REQUIRED$/u.test(code)) return 'person';
+ // The raise site's own words name who acts before the catalog's general step does: an expired
+ // coordinator token says the person reissues it, while a seat's says to ask the coordinator.
+ if (person.test(message)) return 'person';
+ if (coordinator.test(message) || /(?:^|_)COORDINATOR_ONLY$/u.test(code)) return 'coordinator';
+ if (person.test(step)) return 'person';
+ if (/^(?:ask (?:the|your) coordinator|the coordinator)\b/iu.test(step)) return 'coordinator';
return 'agent';
}
@@ -686,8 +692,10 @@ export function blockNotice(error, { command, by, path, at, caller }) {
const first = plain(message);
const cut = first.indexOf(step.slice(0, 24));
const reason = (cut > 0 ? first.slice(0, cut) : first).replace(/[\s;:,.]+$/u, '') || first;
- return { at: at.toISOString(), code, command: `pullboard ${command}`.trim(), by, path,
- audience: blockAudience(code, message, step), reason, step };
+ const audience = blockAudience(code, message, step);
+ // The person never needs to know how the relay works: a relay token is their sign-in [C6].
+ const said = audience === 'person' ? reason.replace(/\b(?:the )?coordinator relay token\b/giu, 'your sign-in for the coordinator').replace(/\brelay token\b/giu, 'sign-in') : reason;
+ return { at: at.toISOString(), code, command: `pullboard ${command}`.trim(), by, path, audience, reason: said, step };
}
/**
diff --git a/src/relay-presentation.js b/src/relay-presentation.js
index edbc7ad2..01f83f8b 100644
--- a/src/relay-presentation.js
+++ b/src/relay-presentation.js
@@ -11,6 +11,8 @@ import {
import { Refused } from './refused.js';
import { loadConfig } from './config.js';
import { projectState } from './serve.js';
+import { personNeeds } from './needs.js';
+import { personBlockWords } from './blocks.js';
import { personRequestStatuses } from './relay-requests.js';
import {
cachedVerdictStates,
@@ -28,7 +30,10 @@ function readRelayPresentation(root, providedBoard) {
const info = repoInfo(root);
const board = providedBoard ?? store.openBoard(join(info.commonDir, 'pullboard', 'board.sqlite'), undefined, { isMain: codeIsFromMain() });
try {
- const state = projectState(root, { board });
+ const projected = projectState(root, { board });
+ // The sealed page's Needs you carries the person's blocks, in plain words with no local path [C6].
+ const blocks = personBlockWords(info.commonDir, (board.clock ?? store.systemClock).now());
+ const state = { ...projected, blocks, needs: personNeeds({ ...projected, blocks }) };
const freshness = providedBoard
? verdictProjector(root, board, { main: trunkRevisionReader(info)() }).state
: cachedVerdictStates(root, board, info);
diff --git a/test/blocks.test.js b/test/blocks.test.js
index 2f1af186..d72a0fbb 100644
--- a/test/blocks.test.js
+++ b/test/blocks.test.js
@@ -1,13 +1,27 @@
/** A refusal that stops someone reaches whoever can clear it, is recorded, and repeats are counted [C6,N26]. */
import assert from 'node:assert/strict';
import { after, test } from 'node:test';
+import { serveApi } from '../src/api.js';
+import { repoInfo } from '../src/git.js';
import { personNeedsState } from '../src/needs-state.js';
+import { reportBlock } from '../src/next-steps.js';
+import { Refused } from '../src/refused.js';
+import { relayPresentation } from '../src/relay-presentation.js';
import { createE2eHelpers } from './e2e-helpers.js';
const e2e = createE2eHelpers();
after(e2e.cleanup);
-test('a Pullboard block reaches whoever can clear it and repeats are counted [C6,N26]', () => {
+/** Needs you as the local API serves it, read in full so every person call is present. */
+async function apiNeeds(api, root) {
+ const headers = { 'x-pullboard-key': 'blocks-test' };
+ const listing = await (await fetch(api.url)).json();
+ const id = listing.boards.find(board => board.root === root).id;
+ const { state } = await (await fetch(`http://127.0.0.1:${api.port}/api/v1/boards/${id}/state?detail=full`, { headers })).json();
+ return { needs: state.needs.filter(row => row.kind === 'block'), blocks: state.blocks };
+}
+
+test('a Pullboard block reaches whoever can clear it and repeats are counted [C6,N26]', async (t) => {
const box = e2e.project();
// A person-only move from an agent's terminal: the person, not the agent, can clear it.
@@ -22,6 +36,37 @@ test('a Pullboard block reaches whoever can clear it and repeats are counted [C6
assert.match(needs[0].what, /^run pullboard view\b/u);
assert.doesNotMatch(`${needs[0].text} ${needs[0].what}`, /\[[A-Z][A-Z0-9_]*\]|B26|relay|--/u);
+ // The local API and the sealed relay page build Needs you from the same ledger, without local paths.
+ const api = await serveApi({ secret: 'blocks-test', runCommand: async () => 0, isMain: true,
+ projects: () => [{ root: box.repo, name: 'blocks', project: '', added: '2026-10-22T00:00:00.000Z' }] });
+ t.after(() => api.close());
+ assert.deepEqual((await apiNeeds(api, box.repo)).needs.map(row => row.text), [needs[0].text]);
+
+ // The relay's person-only refusals, as relay.js and relay-seats.js raise them, are the person's too;
+ // a seat's own expired token is the coordinator's.
+ const said = [];
+ const io = { callerRole: () => 'coordinator', err: line => said.push(line) };
+ const info = repoInfo(box.repo);
+ const raise = (error, command) => reportBlock(io, error, { command, info, now: new Date() });
+ assert.equal(raise(new Refused('HUMAN_REQUIRED', 'send this person action from the paired phone'), 'answer').audience, 'person');
+ assert.equal(raise(new Refused('TOKEN_EXPIRED', 'the coordinator relay token expired; the person reissues it: run pullboard relay on in the main checkout'), 'shout').audience, 'person');
+ assert.equal(raise(new Refused('TOKEN_EXPIRED', 'the relay token of web-1 expired, and only a seat\'s own current token or its creator renews it; ask the coordinator for a fresh worktree: pullboard worktree <lane> --model "<model name>"'), 'claim').audience, 'coordinator');
+ assert.equal(said.filter(line => /only the person can clear this/u.test(line)).length, 2);
+ const personRows = personNeedsState(box.repo).needs.filter(row => row.kind === 'block');
+ assert.deepEqual(personRows.map(row => row.text).sort(), [
+ 'Pullboard stopped a request that only you can clear: send this person action from the paired phone',
+ 'Pullboard stopped a request that only you can clear: this terminal belongs to an agent',
+ 'Pullboard stopped a request that only you can clear: your sign-in for the coordinator expired; the person reissues it',
+ ]);
+ for (const row of personRows) assert.doesNotMatch(row.text, /\[[A-Z][A-Z0-9_]*\]|relay|_/u);
+ // The API sees the new blocks at once (the ledger invalidates its cached state), and so does the relay page.
+ const served = await apiNeeds(api, box.repo);
+ assert.deepEqual(served.needs.map(row => row.text).sort(), personRows.map(row => row.text).sort());
+ assert.ok(served.blocks.every(block => block.audience === 'person' && !('path' in block)), JSON.stringify(served.blocks));
+ const sealed = relayPresentation(box.repo).state;
+ assert.deepEqual(sealed.needs.filter(row => row.kind === 'block').map(row => row.text).sort(), personRows.map(row => row.text).sort());
+ assert.ok(sealed.blocks.every(block => !('path' in block)), JSON.stringify(sealed.blocks));
+
// An agent's coordinator-only move: the agent is told to take it to the coordinator.
for (let attempt = 0; attempt < 3; attempt += 1) {
const held = box.run(box.web, 'hold', 'api', '--reason', 'the api lane waits');
@@ -30,7 +75,7 @@ test('a Pullboard block reaches whoever can clear it and repeats are counted [C6
assert.match(held.err, /^pullboard: only the coordinator can clear this; tell them: pullboard shout coordinator "blocked by COORDINATOR_ONLY on pullboard hold: only the coordinator holds a lane"$/mu);
}
// An agent's block is not the person's call.
- assert.equal(personNeedsState(box.repo).needs.filter(row => row.kind === 'block').length, 1);
+ assert.equal(personNeedsState(box.repo).needs.filter(row => row.kind === 'block').length, 3);
// Health counts the day's blocks by code and drafts an item for the one that repeated.
const report = JSON.parse(box.run(box.repo, 'health', '--json').out);
@@ -41,7 +86,9 @@ test('a Pullboard block reaches whoever can clear it and repeats are counted [C6
assert.equal(byCode.COORDINATOR_ONLY.audience, 'coordinator');
assert.equal(byCode.B26_PERSON_CHANNEL.count, 1);
assert.deepEqual(byCode.B26_PERSON_CHANNEL.who, ['coordinator']);
- assert.deepEqual(report.blocks.drafts.map(draft => draft.cause), ['refusal:COORDINATOR_ONLY']);
+ assert.equal(byCode.HUMAN_REQUIRED.count, 1);
+ assert.equal(byCode.TOKEN_EXPIRED.count, 2);
+ assert.deepEqual(report.blocks.drafts.map(draft => draft.cause), ['refusal:COORDINATOR_ONLY', 'refusal:TOKEN_EXPIRED']);
const [draft] = report.blocks.drafts;
assert.equal(draft.title, 'Pullboard blocked 3 requests in a day with COORDINATOR_ONLY');
const text = box.run(box.repo, 'health').out;