One function names why builders are idle: ceiling reached, flow only, no subscription with headroom, or nothing ready #7695

idleReason(db, now) now exists in src/crew/idle_reason.ts and returns { word, href } | null as plain data. It has no page, tile or terminal line yet. I ran tsc and the new test file, plus flow-only-dispatch, the autonomy tests and 14 test files that mention the ceiling. All passed. I did not run the full suite, so the forge's check is the first full run.

How it decides

• It acts on one repository: the first autonomous one that has a crew, someone to act as, and is not archived. If there is none, it returns null.
• It returns null when slotted runs reach the repo's slots. It counts them with slottedRuns, the loop's own rule, so reviews and planner runs take no slot.
• Otherwise it returns the first reason that holds, with the links from the issue:

- ceiling reached → /meter - flow only → /map - no subscription with headroom → /subscriptions - nothing ready → /map

• If a builder has a free slot, nothing blocks it and work is ready, it also returns null, since there is no reason to give.

Extractions

• atCeiling(repo, spentUsd) in dispatch.ts is now what queueAgentRun asks and what idleReason asks.
• spentTodaySql in autonomy.ts is the spend SQL that spentToday now uses. idleReason reads the same SQL inside its repo statement, which keeps it to 6 statements without copying the query.
• slottedRuns now takes any crew entry with agent.user.id, so idleReason can pass bare ids instead of loading full agents. This is a type widening in autonomy.ts, which the issue didn't list.
• The subscription check calls grantedAccounts, standings and pace, as repoPace does, with the run cost set to 1. Whether a window has room doesn't depend on that cost.

Where it differs from the dispatcher

• "Ready" and "flow only" are read with one lean SQL query: open issues nothing open blocks, with the FLOW_LABEL check and the direction-issue exception. They are not read through readyNow and flowOnlyHolds. repoGraph alone costs more than 6 statements, and flowOnlyHolds would cost one per issue. The result doesn't see the per-issue holds in held.ts. This is the one spot where the issue's "call the same predicate" is not met. I left it in the file header as well.
• I didn't merge the flow_only rule into the lean query as a shared function, to keep to the files listed. If you want it shared, the next step is extracting a heldByFlowOnly-style helper in flow_only.ts.

Tests test/idle-reason.test.ts has one test per reason, plus:

• all slots busy returns null
• reviews take no slot
• the reasons come in order
• a statement count of at most 6 on the longest path, measured with helpers/statements.ts

The test file joins the gate list automatically.

To try it bun test test/idle-reason.test.ts

Closes #7663

idleReason(db, now) now exists in src/crew/idle_reason.ts and returns { word, href } | null as plain data. It has no page, tile or terminal line yet. I ran tsc and the new test file, plus flow-only-dispatch, the autonomy tests and 14 test files that mention the ceiling. All passed. I did not run the full suite, so the forge's check is the first full run.

How it decides

• It acts on one repository: the first autonomous one that has a crew, someone to act as, and is not archived. If there is none, it returns null.
• It returns null when slotted runs reach the repo's slots. It counts them with slottedRuns, the loop's own rule, so reviews and planner runs take no slot.
• Otherwise it returns the first reason that holds, with the links from the issue:

- ceiling reached → /meter - flow only → /map - no subscription with headroom → /subscriptions - nothing ready → /map

• If a builder has a free slot, nothing blocks it and work is ready, it also returns null, since there is no reason to give.

Extractions

• atCeiling(repo, spentUsd) in dispatch.ts is now what queueAgentRun asks and what idleReason asks.
• spentTodaySql in autonomy.ts is the spend SQL that spentToday now uses. idleReason reads the same SQL inside its repo statement, which keeps it to 6 statements without copying the query.
• slottedRuns now takes any crew entry with agent.user.id, so idleReason can pass bare ids instead of loading full agents. This is a type widening in autonomy.ts, which the issue didn't list.
• The subscription check calls grantedAccounts, standings and pace, as repoPace does, with the run cost set to 1. Whether a window has room doesn't depend on that cost.

Where it differs from the dispatcher

• "Ready" and "flow only" are read with one lean SQL query: open issues nothing open blocks, with the FLOW_LABEL check and the direction-issue exception. They are not read through readyNow and flowOnlyHolds. repoGraph alone costs more than 6 statements, and flowOnlyHolds would cost one per issue. The result doesn't see the per-issue holds in held.ts. This is the one spot where the issue's "call the same predicate" is not met. I left it in the file header as well.
• I didn't merge the flow_only rule into the lean query as a shared function, to keep to the files listed. If you want it shared, the next step is extracting a heldByFlowOnly-style helper in flow_only.ts.

Tests test/idle-reason.test.ts has one test per reason, plus:

• all slots busy returns null
• reviews take no slot
• the reasons come in order
• a statement count of at most 6 on the longest path, measured with helpers/statements.ts

The test file joins the gate list automatically.

To try it bun test test/idle-reason.test.ts

I fixed the failing check and pushed it, but I haven't seen the forge's full check run on the new push yet.

The four failures all came from the same two lines in test/idle-reason.test.ts. The forge's lint treats expect(await …).toBeLessThanOrEqual(6) as a wall-clock time bound. That line was actually counting database statements, which has nothing to do with timing. I rewrote both lines as expect((await statements(…)) <= 6).toBe(true). The test still checks that idleReason makes at most six statements per call, and no src code changed.

Locally, test/idle-reason.test.ts and test/flake.test.ts now pass (36 tests). The fix is in commit b1ff4956.

Builders' idle reason now has one door: the admin's terminal home prints it. Pushed as 43266a02. I ran tsc and the three affected test files (14 tests pass). The full suite is left to the forge's check, and I did not run design-lint against my own change.

What changed

• Door (point 1). An admin's terminal home now ends its forge strip with Builders idle: <word> (<link>), for example Builders idle: ceiling reached (/meter). The line comes from idleLine, which is the single place the wording is built, so the web tile can print the same text later. Nobody but an admin sees it, and nothing prints while a builder slot is busy or something can start.
• Tests and README (point 1). test/tui-dashboard-idle.test.ts seeds a repository at its ceiling, checks the admin's screen carries the line and a non-admin's does not. The README has a paragraph for it in the Crew section.
• Same predicate as the dispatcher (point 2). The private ready query and the private flow-only rule are gone. idleReason(app, now) now uses heldNow from held.ts:

- flow only means nothing is startable and at least one ready issue is held by the flow_only hold. - nothing ready means startable is empty, so running, open-pull, planner, stalled, run-cap, hot-file and other holds count as the dispatcher counts them. - The ceiling is atCeiling(spentToday) and the slot check is slottedRuns over listCrewRoles, both as the loop calls them. - A new test makes the only ready issue held by a run in flight and expects nothing ready.

• Cleanliness (point 4). autonomy.ts is back to main: spentTodaySql and the widened slottedRuns type are gone, and so are the fake planner entries. The ceiling test now uses the real clock. I removed the slot check and confirmed the "every slot busy → null" test fails, because the spend then reads as ceiling reached.

Where I disagree or chose not to act

• Signature. idleReason now takes app, not db, because heldNow needs it. Issue #7663 specified (db, now).
• Statement cap. The six-statement cap from #7663 no longer holds, since heldNow does per-issue reads. I dropped that test, as you suggested accepting more statements. It costs more per call on a large map, and the dashboard calls it once per reload.
• Web tile (point 1). I did not add it. #7663 puts the tile and the terminal in the next two issues, and a tile risks the home's budget test. You asked for one door, so I did the terminal.
• Pipeline direction (point 3). I have not mapped this to a pipeline issue (#6534, #6611, #5276 or #3316). It serves #5799, the crew-dashboard ask, as the issue says. If the owner's pipeline-first order should hold it, it can wait behind those; that is a call for a person.

To try it: ssh into the app as an admin while an autonomous repository is at its ceiling, or run bun test test/tui-dashboard-idle.test.ts.

idleReason(app, now) names the single reason the builders are idle, in this order:

• the forge's spend ceiling is reached
• only flow work (the forge's own background jobs) is allowed
• no subscription has room left
• nothing is ready to build

It gets its answer from the same checks the dispatcher uses to hold back work (heldNow, atCeiling, slottedRuns), so the line and the dispatcher can't disagree. idleLine turns the reason into one sentence. An admin's terminal home prints it; non-admins and a busy crew see nothing. The README has a paragraph on it, and src/crew/autonomy.ts matches main.

This push only addresses the review on src/tui/screens/dashboard.ts; behaviour is unchanged:

• idleLines now sits above repoMark's doc comment, so each comment is on its own function again.
• The App type import moved up with the other ../../ imports.

bun x tsc --noEmit passes, and so do test/idle-reason.test.ts and test/tui-dashboard-idle.test.ts (10 tests).

Not done here: idleReason reads each held issue on every reload of an admin's home. That's fine at today's size; if the map gets large, cache it or count the holds in one query.

To try it: on the preview, open the terminal as an admin with a full ceiling, or with no ready issues. The home shows the reason above the KPI lines.

🤖 Generated with Claude Code