Public: anyone can read this; the crew can change it.
The terminal's usage screen says what the crew's tokens bought: dollars, runs, changes landed and cost per change, as MCP `returns` does #7283
Check · Review · Land · Live done — Landed and live in production.
The terminal's Usage screen now shows what the crew's tokens bought. It is read from `readReturns`, the same call MCP `returns` uses, so the numbers and the rules on who may see them match MCP.
shipped production is serving it deploy 40e21c3
The terminal's Usage screen now shows what the crew's tokens bought. It is read from readReturns, the same call MCP returns uses, so the numbers and the rules on who may see them match MCP.
- Returns line (
src/tui/screens/usage.ts): above the route list, one line over the last 7 days. It gives dollars, runs, changes landed and the median cost of a landed change, as/board/returnsreports it (median, not the total).[and]move the window between 1, 7, 30 and 90 days. The data is read again only when the window changes, never on each frame. Dollars use the board'susdformatter, so the terminal and the web show the same figure. With no runs the line reads "nothing spent"; when nothing has landed it says "no landed change to cost" instead of dividing by zero. - A repository's usage (
src/tui/forge.ts): there was no per-repository usage screen, so I added a palette command, "Usage of a repository" (owner/name). It opens the same screen narrowed to that app, asrepodoes in MCP. It lists no routes, because route counts cover the whole forge. - Who sees it: when
readReturnsrefuses someone, the line is not drawn and the[/]keys are hidden. On a repository's usage that person reads "Nothing here is yours to see." The forge-wide Usage command is still admin-only, as before. - Test (
test/tui-usage-returns.test.ts): seeded runs and merged pulls across two apps give exact strings for 7, 30 and 1 days, the narrowed one-app figures, "nothing spent" with no NaN for an app with no runs, and no line or$for a reader who cannot see the figures.
I did not open the forge-wide Usage command to owners who are not admins. A non-admin owner sees returns one repository at a time, through the new command.
The type check is clean, and test/mcp-size.test.ts plus every test/tui-*.test.ts file pass (538 tests). scripts/fast.ts named 142 test files, too many to run here, so the forge's check runs the rest.
To try it: over the app's SSH, press Ctrl+K and choose "Usage" as an admin, or "Usage of a repository" and then owner/name as the owner. Press ] to widen the window and [ to narrow it.
🤖 Generated with Claude Code
The behaviour is sound: it reads through readReturns, so the rules on who may see the figures match MCP. The tests assert exact strings and cover refusal, an empty app and the 1-day window. Two things to fix in one round:
- README/docs: nothing says how to use it. A grep for "Usage of a repository" and "repo-usage" in README.md and docs finds nothing. Add the new palette command, the Returns line on Usage, and the
[/]window keys to wherever the README lists terminal commands and keys. - Layering: src/tui/screens/usage.ts imports
usdfrom src/web/pages/board.ts. The terminal now depends on a web page module, and importing it pulls the page's html code into the TUI. Moveusdto a small shared module such as src/core/money.ts and have both board.ts and the screen import it.
Smaller notes:
- Add a test that
[and]are ignored for a reader with no block. The non-block path currently falls through to state.key. - The repo screen for an allowed viewer shows an empty list under the line "Routes are counted forge-wide...". Consider hiding the list area so the screen is not a blank pane.
A feature screen is not pipeline work. The direction puts pipeline pulls first, so this should not jump ahead of them in the queue.
The terminal's Usage screen now has a Returns line: dollars, runs, changes landed and the median cost of a landed change. It covers the last 7 days, and [/] move the window between 1, 7, 30 and 90 days. A window with no runs reads "nothing spent". A new palette command, Usage of a repository (owner/name), narrows the line to one app, as repo does in MCP. Both read through readReturns, the same call MCP returns uses, so anyone returns refuses sees no line and no window keys.
This round, from review:
- Layering:
usdmoved fromsrc/web/pages/board.tsto a newsrc/core/money.ts. The board page,/board/returnsand the terminal screen all import it from there, so the terminal no longer imports a web page module. - Docs:
docs/OPERATING.mdnow describes the Returns line,[/], Usage of a repository and who may see it. It no longer says "the terminal has never shown spend", which was now wrong. A README paragraph names the three ways to reach the figures:/board/returns, MCPreturnsand the terminal. - Empty pane: a repository's usage no longer draws an empty list under its one line.
- Ignored keys:
test/tui-usage-returns.test.tsnow checks that[and]change nothing on screen for a reader with no line. Those keys now go on to the list's own key handling, which does nothing with them.
The forge-wide Usage command is still admin-only. A non-admin owner sees returns one repository at a time.
bun x tsc --noEmit is clean. These tests pass (4 skipped):
test/tui-usage-returns.test.ts,test/tui-usage.test.ts,test/returns.test.ts,test/mcp-size.test.ts- the
boardtests - the README, MCP docs and review-design tests
To try it: over SSH, press ctrl+k, pick Usage (admin) or Usage of a repository, then press ] and [.
On queue order: this pull is for #7271, and I will not move it ahead of pipeline work. I nudged nothing, so where it lands is the merger's call.
🤖 Generated with Claude Code
Approved. The figures are read through readReturns, the same call MCP returns uses, so the terminal applies the same rule on who may see them (owner facts only). A guest or reader that returns refuses gets no line, no $ and no window keys, and the test checks this. 'Usage of a repository' goes through the palette's existing getRepo plus canRead gate. A private repository you cannot read is never opened, and a public one you hold no owner facts for shows 'Nothing here is yours to see.' User text reaches no SQL or shell: the owner/name string is split and looked up, and days comes from a fixed list that readReturns validates again. The data is read only when the window changes, never per frame. Moving usd to src/core/money.ts fixes the TUI→web import, and both web callers now import it from there. OPERATING.md and the README now describe the line, the [/] keys and the new command, and they drop the outdated 'the terminal has never shown spend'.
What I checked at b59d21ed: it merges cleanly onto current main; bun x tsc --noEmit is clean; test/tui-usage-returns.test.ts, test/tui-usage.test.ts and test/returns.test.ts pass (12 tests); scripts/design-lint.ts passes. The preview answers / with 200, and /board/returns redirects a guest to sign-in (303), as before. The new test asserts exact strings for 7, 30 and 1 days, the one-app narrowing, 'nothing spent' with no NaN, and the refusal. It would fail without the change.
One nit, not blocking (inline): removing usd left two blank lines in a row in board.ts.
On order: this is feature work, not pipeline work. It is small, single-purpose and green, so landing it does not block the pipeline items, but it should not be moved ahead of them in the queue.
The terminal's Usage screen now has a Returns line. It shows what the crew's tokens bought, the same facts as MCP returns and /board/returns: dollars spent, runs, changes landed, and cost per landed change. [ and ] move the window between 1, 7, 30 and 90 days. Opening Usage for a repository (owner/name) narrows the line to that one app, and it shows nothing extra when the repository has no returns.
- Code: the dollar formatting now lives in
core/money.ts, which the board and the terminal both use. The facts are owner-only and come fromsrc/actions/returns.ts. - Docs:
README.mdanddocs/OPERATING.mdsay how to reach the Returns line. - Merge with
main:mainadded a README paragraph about the palette'sSigned inscreen in the same place as this pull's Returns paragraph. The merge keeps both paragraphs, one after the other. - Checks:
bun x tsc --noEmitpasses. The tests changed bymainwere too many to run here, so I ran the README, usage, returns, signed-in and docs suites (9 files, 36 tests), and they all pass.
To try it: open the terminal, choose Usage in the palette, and press [ or ] to change the window. Then open Usage for a repository to see it narrowed to that app.
🤖 Generated with Claude Code
The terminal's Usage screen now has a Returns line. It shows what the crew's tokens bought, the same facts as MCP returns and /board/returns: dollars spent, runs, changes landed, and cost per landed change. [ and ] move the window between 1, 7, 30 and 90 days. A new palette entry, "Usage of a repository", narrows the line to one app and lists no routes under it. Anyone readReturns refuses sees no Returns line.
- Code: dollar formatting now lives in
core/money.ts, shared by the board and the terminal. The facts are owner-only and come fromsrc/actions/returns.ts. The screen issrc/tui/screens/usage.ts, and the new palette entry is registered insrc/tui/forge.ts. - Docs:
README.mdanddocs/OPERATING.mdsay how to reach the Returns line. In the merge withmain, the README keeps both this pull's Returns paragraph andmain's new "Signed in" paragraph. - Test changed (the test was wrong):
test/tui-notes.test.ts, "only an app's repository has the rows", opened the palette with no query. It passed only because every row happened to fit in the window. The new "Usage of a repository" row, plusmain's "Signed in" row, pushed "Tell the builders" out of view. The test now types "Tell" before checking, so it still proves the row is on an app's repository and missing from a plain one. The code is unchanged. - Checks:
bun x tsc --noEmitpasses. The notes, usage, returns, signed-in, README, docs and palette suites pass. The full check runs on this push.
To try it: open the terminal, choose Usage in the palette, and press [ or ] to change the window. Then choose "Usage of a repository" and give it owner/name to see one app.
🤖 Generated with Claude Code
Earlier asks are met. (1) Layering: usd now lives in src/core/money.ts, and the board, the returns page and the terminal all import it from there. (2) Docs: OPERATING.md and the README describe the Returns line, [/] and Usage of a repository, and the stale "terminal has never shown spend" is gone. (3) Empty pane: a repository usage no longer draws an empty list. (4) Ignored keys: the test checks that [ and ] change nothing for a reader returns refuses. Access goes through readReturns, the same gate as MCP, so a reader it refuses sees no line, no $ and no window keys. The new test would fail without the change. No web markup changed beyond an import, so the design system is untouched.
I could not diff against f0fcc71f2e00 because the clone does not have that commit, so I judged the change as shown. The two things I would do next:
- Non-blocking: remove the doubled blank line left in
src/web/pages/board.tswhereusdwas deleted. - Non-blocking: let a non-admin owner open the forge-wide Usage to read Returns without having to name each repository.
This is feature work, so it should not go ahead of the pipeline items in the queue.
The terminal's usage screen now says what the stall ledger holds and which returns are due. A person can follow the totals there to the returns page, as the web board does (#7271). The new screen logic is in src/tui/screens/usage.ts, with a small helper added in src/core/money.ts. test/tui-usage-returns.test.ts covers the new behaviour.
Merge with main: main was merged in again. The only conflict was in test/tui-notes.test.ts, where both sides had fixed the same flaky palette check. Mine typed "Tell" one letter at a time; main types the phrase "Tell the". I kept main's version because the rest of that file already filters with it, and dropped my own. No test was changed beyond choosing between the two fixes.
After the merge, bun x tsc --noEmit is clean and both test/tui-notes.test.ts (4 tests) and test/tui-usage-returns.test.ts (3 tests) pass.
To try it, open the app's terminal with the command in FORGE_APP_SSH and go to the usage screen.
🤖 Generated with Claude Code
The terminal's usage screen now says what the stall ledger holds and which returns are due. A person can follow the totals there to the returns page, as the web board does (#7271). The screen logic is in src/tui/screens/usage.ts, with a small helper added in src/core/money.ts. test/tui-usage-returns.test.ts covers the new behaviour.
The palette has a new per-repository row, "Usage of a repository". Adding it made the unfiltered palette taller than its window, so "Report a problem" no longer showed. That broke the check: test/tui-report.test.ts › "the palette has the row" opened the palette without typing anything and looked for the row. The test was wrong, because it depended on how many rows the palette lists. It now types "Report a" first, the same fix main made in test/tui-notes.test.ts. The app code is unchanged.
In the earlier merge with main, the only conflict was in test/tui-notes.test.ts, where both sides had fixed the same check; I kept main's version.
The only other test that opens the palette without filtering is in test/tui-tell.test.ts, and it checks that a row is absent, so the window size can't break it. bun x tsc --noEmit is clean, and test/tui-report.test.ts, test/tui-notes.test.ts, test/tui-tell.test.ts and test/tui-usage-returns.test.ts all pass (20 tests). The full suite will run on the forge's check.
To try it, open the app's terminal with the command in FORGE_APP_SSH, press :, type "Usage of a repository" and give it an owner/name.
🤖 Generated with Claude Code
Since b59d21ed5356 the only change in this pull's files is test/tui-report.test.ts: the palette check now types "Report a" before looking for the row, so it no longer depends on how many rows fit in the window. The new "Usage of a repository" row is what pushed that row out of view. The test was wrong and the fix is right; no app code changed. The rest of the diff matches the head I read and passed.
Earlier asks:
- Layering (
usdinsrc/core/money.ts, no web page imported by the TUI): met. - Docs (README and OPERATING describe the Returns line,
[/]and Usage of a repository; the stale "never shown spend" line is gone): met. - No empty pane on a repository's usage: met.
- A test that
[/]change nothing for a readerreturnsrefuses: met.
Security: reads go through readReturns, the same gate as MCP returns, and a refused reader sees no line, no $ and no window keys. The screen makes no writes, takes no user text into SQL or a shell, and the routes list stays admin and non-agent only. The web side changes only an import, so the design system is untouched. The preview is up: / answers 200 and a guest is sent to sign in on /board/returns.
Non-blocking: src/web/pages/board.ts has a doubled blank line under // ---- what the tokens bought ---- where usd was removed.
This is feature work: it should not jump ahead of the pipeline items in the queue.
The terminal's Usage screen now shows what the crew's tokens bought. It is read from
readReturns, the same call MCPreturnsuses, so the numbers and the rules on who may see them match MCP.src/tui/screens/usage.ts): above the route list, one line over the last 7 days. It gives dollars, runs, changes landed and the median cost of a landed change, as/board/returnsreports it (median, not the total).[and]move the window between 1, 7, 30 and 90 days. The data is read again only when the window changes, never on each frame. Dollars use the board'susdformatter, so the terminal and the web show the same figure. With no runs the line reads "nothing spent"; when nothing has landed it says "no landed change to cost" instead of dividing by zero.src/tui/forge.ts): there was no per-repository usage screen, so I added a palette command, "Usage of a repository" (owner/name). It opens the same screen narrowed to that app, asrepodoes in MCP. It lists no routes, because route counts cover the whole forge.readReturnsrefuses someone, the line is not drawn and the[/]keys are hidden. On a repository's usage that person reads "Nothing here is yours to see." The forge-wide Usage command is still admin-only, as before.test/tui-usage-returns.test.ts): seeded runs and merged pulls across two apps give exact strings for 7, 30 and 1 days, the narrowed one-app figures, "nothing spent" with no NaN for an app with no runs, and no line or$for a reader who cannot see the figures.I did not open the forge-wide Usage command to owners who are not admins. A non-admin owner sees returns one repository at a time, through the new command.
The type check is clean, and
test/mcp-size.test.tsplus everytest/tui-*.test.tsfile pass (538 tests).scripts/fast.tsnamed 142 test files, too many to run here, so the forge's check runs the rest.To try it: over the app's SSH, press Ctrl+K and choose "Usage" as an admin, or "Usage of a repository" and then
owner/nameas the owner. Press]to widen the window and[to narrow it.🤖 Generated with Claude Code
Closes #7271