Skip to content

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

feat(health): queue faults name a route, an item or an agent [N2,B13]

Corey Olson8bd9e13a4a98
diff --git a/docs/api.md b/docs/api.md
index 92ecace8..9e3bc7f8 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -222,6 +222,12 @@ The causes, each with its owner:
| `DECISION_UNANSWERED` | a decision to the coordinator or the person is unanswered past `health.stuck` | the coordinator or the person |
| `REQUEST_UNANSWERED` | a person's request is not done or declined past `health.stuck` | the coordinator |
| `RELEASE_OVERDUE` | landed work waits and the newest version tag is older than `health.release` | the coordinator |
+| `ROUTE_UNSERVED` | open current work on a route that no active agent can take; `detail.items` names them | the coordinator, who starts an agent on the route |
+| `ITEM_UNTAKEABLE` | an open item that no active agent in its lane can take on its route | the coordinator |
+| `IDLE_AGENT` | an agent with no claim, review or event for 30 minutes while open work in its lane is one it could take | the agent itself |
+| `RANK_INVERSION` | a claim whose holder could take an earlier-ranked item that sits free; `detail.ahead` names it | the holder |
+
+An agent is active while it holds a claim or review, has submitted work still awaiting review, or had an event or shout in the last 30 minutes. Queue faults read the queue's own order, so `pullboard queue` and health agree.
The current release is the roadmap's first milestone with unverified local work; an unplanned item counts as current. A release is the newest tag named like `v1.2.3` or `1.2.3`, dated by its creation, and its landed work is every item first recorded merged after it. A repository with no such tag has no release deadline. The trunk is the primary checkout's branch, or the retained trunk when that checkout is detached.
diff --git a/src/health.js b/src/health.js
index fbdb2c7c..70dcc10d 100644
--- a/src/health.js
+++ b/src/health.js
@@ -17,14 +17,19 @@ import {
} from './git.js';
import {
boardBusyError,
+ buildOrder,
+ canTake,
+ listItems,
openBoardReadOnly,
PERSON,
+ ROUTES,
roadmap,
rowDecisions,
unverifiedSubmissions,
} from './board.js';
import { staleRowDecisions } from './row-decision-state.js';
import { localReleaseRank } from './release-queue.js';
+import { workQueue } from './queue.js';
import { trunkRef } from './trusted-policy.js';
/** Each threshold's pullboard.json key under "health" and its default. */
@@ -234,11 +239,110 @@ export function healthReport({ db, root, config, now }) {
}));
}
+ for (const fault of queueFaults(board, { items, at })) report.stuck.push(fault);
+
const overdue = releaseOverdue(db, root, at, limits.ms.release, history);
if (overdue) found(report.stuck, overdue);
return report;
}
+/** An agent with no claim, review or event for this long is idle, not active; its own submitted work awaits review, so it is not idle (N2). */
+const QUEUE_ACTIVE_MS = 30 * 60_000;
+
+/**
+ * The queue faults the board can see: a route with open current work that no active agent can take,
+ * an open item no active agent in its lane can take, an idle agent beside work it could take, and a
+ * claim that ranks behind a free item its holder could take (N2, B13). The queue (workQueue) and the
+ * board's buildOrder supply the order, so health and pullboard queue cannot disagree. Each finding
+ * names the item and the next step; an agent that is idle is named as its own owner.
+ *
+ * @param {{ db: any, clock: { now: () => Date } }} board
+ * @param {{ items: any[], at: number }} context - the board's items and the clock in epoch milliseconds
+ * @returns {Finding[]}
+ */
+function queueFaults(board, { items, at }) {
+ const queue = workQueue(board);
+ const current = (queue.releases.find((release) => release.landed < release.total)?.items ?? queue.unreleased)
+ .filter((entry) => entry.status === 'open' && !entry.waits.length);
+ const waiting = [...queue.releases.flatMap((release) => release.items), ...queue.unreleased]
+ .filter((entry) => entry.status === 'open' && !entry.waits.length);
+ const rows = board.db.prepare(`SELECT agent_id AS id, agent_lane AS lane, agent_route AS route, agent_path AS path, agent_created_at AS created,
+ (SELECT MAX(event_at) FROM event WHERE event_by = agent.agent_id) AS event_at,
+ (SELECT MAX(shout_at) FROM shout WHERE shout_from = agent.agent_id) AS shout_at
+ FROM agent ORDER BY agent_id`).all();
+ const agents = rows.filter((row) => row.lane !== 'coordinator').map((row) => {
+ const last = Math.max(...[row.created, row.event_at, row.shout_at].filter(Boolean).map((value) => Date.parse(value)));
+ const holds = items.some((item) => (item.item_status === 'claimed' && item.item_owner === row.id)
+ || (item.item_status === 'submitted' && item.item_built_by === row.id)
+ || (item.item_review_by === row.id && Date.parse(item.item_review_until ?? '') > at));
+ return { ...row, last, active: holds || at - last < QUEUE_ACTIVE_MS };
+ });
+ const active = agents.filter((agent) => agent.active);
+ const raw = new Map(items.map((item) => [item.item_id, item]));
+ const since = (id) => raw.get(id)?.item_updated_at ?? new Date(at).toISOString();
+ const now = at;
+ const findings = [];
+
+ for (const route of ROUTES) {
+ const open = current.filter((entry) => entry.route === route);
+ if (!open.length || active.some((agent) => canTake(agent.route, route))) continue;
+ const first = open[0];
+ findings.push(finding('ROUTE_UNSERVED', null, {
+ subject: `${route} route`, key: `ROUTE_UNSERVED:route:${route}`, since: since(first.id), now,
+ title: 'route has no active agent',
+ why: `${open.length} open ${route} ${open.length === 1 ? 'item waits' : 'items wait'}, starting with #${first.id}, and no active agent can take ${route} work`,
+ next: `start an agent on the ${route} route: pullboard join ${first.lane} --route ${route}`,
+ command: `pullboard join ${first.lane} --route ${route}`,
+ owner: { role: 'coordinator', who: COORDINATOR }, detail: { route, items: open.map((entry) => entry.id) },
+ }));
+ }
+
+ for (const entry of waiting) {
+ if (active.some((agent) => agent.lane === entry.lane && canTake(agent.route, entry.route))) continue;
+ findings.push(finding('ITEM_UNTAKEABLE', raw.get(entry.id) ?? null, {
+ subject: `#${entry.id}`, key: `ITEM_UNTAKEABLE:item:${entry.id}`, since: since(entry.id), now,
+ title: 'nobody can take it',
+ why: `no active agent in the ${entry.lane} lane can take a ${entry.route} item, so #${entry.id} waits: ${entry.title}`,
+ next: `start an agent in the ${entry.lane} lane on the ${entry.route} route: pullboard join ${entry.lane} --route ${entry.route}`,
+ command: `pullboard join ${entry.lane} --route ${entry.route}`,
+ owner: { role: 'coordinator', who: COORDINATOR }, detail: { lane: entry.lane, route: entry.route },
+ }));
+ }
+
+ for (const agent of agents.filter((candidate) => !candidate.active)) {
+ const work = waiting.find((entry) => entry.lane === agent.lane && canTake(agent.route, entry.route));
+ if (!work) continue;
+ findings.push(finding('IDLE_AGENT', null, {
+ subject: agent.id, key: `IDLE_AGENT:agent:${agent.id}`, since: new Date(agent.last).toISOString(), now,
+ title: 'idle beside work it could take',
+ why: `${agent.id} has held no claim or review and pulled nothing for 30 minutes, while #${work.id} waits in ${agent.lane} and it could take it`,
+ next: `run pullboard next in ${agent.path}`, command: 'pullboard next',
+ owner: { role: 'builder', who: agent.id }, detail: { lane: agent.lane, route: agent.route, item: work.id },
+ }));
+ }
+
+ const compare = buildOrder(board);
+ for (const claim of items.filter((item) => item.item_status === 'claimed')) {
+ const holder = agents.find((agent) => agent.id === claim.item_owner);
+ if (!holder) continue;
+ const ahead = waiting.filter((entry) => entry.lane === holder.lane && canTake(holder.route, entry.route))
+ .map((entry) => raw.get(entry.id))
+ .filter((item) => item && compare(item, claim) < 0)
+ .sort(compare);
+ if (!ahead.length) continue;
+ const first = ahead[0];
+ findings.push(finding('RANK_INVERSION', claim, {
+ subject: `#${claim.item_id}`, key: `RANK_INVERSION:item:${claim.item_id}`, since: since(claim.item_id), now,
+ title: 'a free item ranks ahead',
+ why: `${holder.id} claimed #${claim.item_id} while #${first.item_id} ranks ahead in the ${holder.lane} lane and sits free`,
+ next: `release #${claim.item_id} with pullboard release ${claim.item_id}, then claim #${first.item_id}`,
+ command: `pullboard release ${claim.item_id}`,
+ owner: { role: 'builder', who: holder.id }, detail: { holder: holder.id, ahead: first.item_id },
+ }));
+ }
+ return findings;
+}
+
/**
* @typedef {{ key: string, cause: string, item: number|null, subject: string, title: string, since: string,
* ageMinutes: number, why: string, next: string, command: string|null,
diff --git a/test/health.test.js b/test/health.test.js
index 8ddaa685..b657ba01 100644
--- a/test/health.test.js
+++ b/test/health.test.js
@@ -299,3 +299,42 @@ test('item history survives garbage collection mid-read [A6]', () => {
assert.equal(child.status, 0, `reading item history must not lose its statement to garbage collection: ${child.stderr}`);
assert.equal(child.stdout, '50', 'every item with events has a history entry');
});
+
+test('health names a route with open work and no agent [N2,B13]', async (t) => {
+ const box = repo(t);
+ const { board, at } = boardAt(box);
+ at(HOUR / 12);
+ store.register(board, { lane: 'coordinator', path: box.root });
+ const light = store.register(board, { lane: 'core', route: 'light', path: join(box.dir, 'core-light') });
+ const waiting = store.addItem(board, { by: 'coordinator', lane: 'core', title: 'Mid work', route: 'mid',
+ criterion: 'The mid work is done when its test passes.', check: 'true', brief: 'Files:\n- src/mid.js\nTest:\n- the mid work runs' });
+ store.closeBoard(board);
+ const result = await cli(box.root, ['health', '--json']);
+ assert.equal(result.code, 1, `a queue fault is stuck work: ${result.stderr}`);
+ const report = JSON.parse(result.stdout);
+ const route = report.stuck.find((entry) => entry.key === 'ROUTE_UNSERVED:route:mid');
+ assert.ok(route, `health names the route nobody serves: ${result.stdout}`);
+ assert.deepEqual(route.owner, { role: 'coordinator', who: 'coordinator' }, 'the coordinator starts an agent on the route');
+ assert.ok(route.why.includes(`#${waiting}`), `the finding names the waiting item: ${route.why}`);
+ assert.ok(route.next.includes('--route mid'), `the next step joins the route: ${route.next}`);
+ assert.ok(!report.stuck.some((entry) => entry.owner?.who === light && entry.key.startsWith('ROUTE_UNSERVED')), 'the light agent is not named for a mid route');
+});
+
+test('health names a rank inversion [N2,B13]', async (t) => {
+ const box = repo(t);
+ const { board, at } = boardAt(box);
+ at(HOUR / 12);
+ store.register(board, { lane: 'coordinator', path: box.root });
+ const builder = store.register(board, { lane: 'core', path: join(box.dir, 'core-1') });
+ const earlier = store.addItem(board, { by: 'coordinator', lane: 'core', title: 'Earlier work' });
+ const later = store.addItem(board, { by: 'coordinator', lane: 'core', title: 'Later work' });
+ store.claim(board, later, { agentId: builder, lane: 'core', leaseMs: 2 * HOUR, freeze });
+ store.closeBoard(board);
+ const result = await cli(box.root, ['health', '--json']);
+ const report = JSON.parse(result.stdout);
+ const inversion = report.stuck.find((entry) => entry.key === `RANK_INVERSION:item:${later}`);
+ assert.ok(inversion, `health names the claim that ranks behind a free item: ${result.stdout}`);
+ assert.deepEqual(inversion.owner, { role: 'builder', who: builder }, 'the holder owns its own rank inversion');
+ assert.ok(inversion.why.includes(`#${earlier}`), `the finding names the free item ahead: ${inversion.why}`);
+ assert.ok(inversion.next.includes(`claim #${earlier}`), `the next step claims it: ${inversion.next}`);
+});