Public: anyone can read this; the crew can change it.
An admin takes a heap census on the running forge from /system, and the forge compares it with the first one by object type #15311
Check · Review · Land · Live done — Landed and live in production.
A forge admin can now take a heap census of the running forge from /system, and the page compares it with the first census by object type. The census runs only when the button is pressed, never on a timer. This lets the retainer behind #15286's heap growth be found on production itself, without a copy of its data.
shipped production is serving it deploy b0d7e95
7 earlier comments · 1 event
A forge admin can now take a heap census from /system: one heapStats() count of the main VM's objects by type, compared with the first census. The census runs only when someone presses the button, never on a timer.
This update merges main. The only conflict was in docs/features/memory-growth.md, where main had added "Reading the retainers (#15286)" in the same place as the census section. Both are kept: main's section comes first, with its updated Tests line, and "A heap census on the running forge (#15309)" follows. The census migration (20261121230000) still sorts after the newest migration on main. After the merge, the type check, the gate, the design lint and the tests that cover this change (88) pass.
What the pull adds
src/perf/heap_census.ts:- Takes one census of the main VM's heap, stored as
{at, uptimeMin, heapSize, objectCount, byType}in a newheap_censustable. - Keeps the first census and the last 20, so 21 rows at most.
- Allows one every ten minutes. The limit is read from the last stored row, so a restart does not reset it.
- Ranks the twenty types that grew most from the first census to the last.
- Takes one census of the main VM's heap, stored as
POST /system/heap-census: goes throughreadForm, so it gets the same-origin check, an admin-scope token and a bounded body.- Only a forge admin who is a person can take a census. An agent's token, even an admin agent's, gets a 403 with one sentence.
- A second press within ten minutes gets a 429 with
Retry-Afterand the reason.
/system: a "Heap census" section under "Forge memory" with one line and the button. From the second census on it shows a table of the types that grew, with their first and last counts.GET /api/v1/telemetry/heap-census: the same data as JSON, for the owner or an agent holdingtelemetry:read, through the existing telemetry read gate. Reading it never takes a census. It has an OpenAPI row.- Terminal: the memory screen shows the same comparison (
censusLines). - Docs: the new section in
docs/features/memory-growth.md. - Existing test changed:
test/system-parts.test.tslists every section of/system, so it now includes "Heap census". The test was not wrong; the page gained a section.
Not done
- A census can only be taken from the
/systembutton, not from the terminal or the API. - Only the main VM is counted, not the workers.
- I did not take before/after screenshots. The commit names
/systemfor the forge's look pages instead.
Try it: on /system as the owner, press "Take a heap census" twice, at least ten minutes apart, then GET /api/v1/telemetry/heap-census.
[{"go":"/system#heap-census","look":"the Heap census section under Forge memory","expect":"one line saying no census yet and a 'Take a heap census' button, with a note that it holds the forge a fraction of a second"},
{"go":"/system#heap-census","look":"press Take a heap census","expect":"back on /system with 'Heap census taken: N objects.' and the line now saying one census"},
{"go":"/system#heap-census","look":"press it again at once","expect":"a 429 page saying a census is taken at most every ten minutes and when the next can be"},
{"go":"/system#heap-census","look":"after a second census ten or more minutes later","expect":"a table of up to twenty object types with First and Last counts, the largest growth on top","ask":"Do the type names read clearly enough to point at a retainer?"}]
🤖 Generated with Claude Code
<!-- look-pages 378c2e92e8fc --> Look pages for 378c2e9, from the gate:
look pages (named): this pull changes src/web/pages/system.ts; a commit names /system
An admin can now take a heap census from /system: a count of every object on the forge's heap by type, kept to compare with the first one. After two or more, the section shows the object types that grew most since the first census, with their counts then and now. Taking one holds the forge for a fraction of a second, so it is limited to one every ten minutes. Asking sooner gets a 429 with retry-after. An agent's token is refused with a one-sentence reason, and a person who is not an admin gets a 404.
First-view budget (this push): the section put /system over its first-view budget (299 words against 250). It now follows the pattern of the other /system sections. The heading and one sentence of state ("No heap census yet." on an empty forge) are visible first. The button, what a census costs and the table of types that grew are behind a disclosure. That costs +6 words and +2 blocks. The /system budget in docs/design/attention-budget.json goes up by exactly that, with a note beside it, as earlier sections did.
What to look at: heapCensusSection and heapCensusSubmit in src/web/pages/system.ts; the counting and the rate limit in src/perf/heap_census.ts; the comparison by type in src/perf/heap_diff.ts.
Checks: bun x tsc --noEmit, bun scripts/gate.ts --fix and bun scripts/design-lint.ts are clean. scripts/fast.ts named 3,328 test files, too many to run here. Instead I ran the 60 test files that cover /system and the heap census, including test/attention.test.ts: 586 pass, 0 fail.
Left out: the census section is not on the terminal's system screen.
[
{"go": "/system", "look": "the Heap census section", "expect": "a heading and one line, \"No heap census yet.\", with the button inside the disclosure"},
{"go": "/system", "look": "open the Heap census disclosure and press Take a heap census", "expect": "a flash naming the object count; the line now says one census and its uptime"},
{"go": "/system", "look": "press Take a heap census again straight away", "expect": "a 429 page saying when the next census may be taken, with a link back to System"}
]
🤖 Generated with Claude Code
<!-- look-pages d04b0930cf86 --> Look pages for d04b093, from the gate:
look pages (named): this pull changes src/web/pages/system.ts; a commit names /system
There was nothing to change for this, so I pushed nothing and the branch is still at d04b093. The look-pages note is the gate saying which page it will picture: named means a commit names /system as the page. Nothing in it is a failure or a request (src/checks/look_count.ts, docs/features/look-count.md). I couldn't look at the preview's /system myself, because it redirects my token to sign in.
An admin can now take a heap census from /system: a count of every object on the forge's heap by type, kept to compare with the first one. After two or more, the section shows the object types that grew most since the first census, with their counts then and now. Taking one holds the forge for a fraction of a second, so it is limited to one every ten minutes. Asking sooner gets a 429 with retry-after. An agent's token is refused with a one-sentence reason, and a person who is not an admin gets a 404.
First-view budget: the heap census section stays inside the /system first-view budget by showing only its heading and one sentence of state ("No heap census yet." on an empty forge). The button, what a census costs and the table of types that grew are behind a disclosure, as in the other /system sections. That costs +6 words and +2 blocks. The /system budget in docs/design/attention-budget.json goes up by exactly that, with a note beside it.
What to look at: heapCensusSection and heapCensusSubmit in src/web/pages/system.ts; the counting and the rate limit in src/perf/heap_census.ts; the comparison by type in src/perf/heap_diff.ts.
Checks: bun x tsc --noEmit, bun scripts/gate.ts --fix and bun scripts/design-lint.ts are clean. scripts/fast.ts named 3,328 test files, too many to run here. Instead I ran the 60 test files that cover /system and the heap census, including test/attention.test.ts: 586 pass, 0 fail.
Left out: the census section is not on the terminal's system screen.
[
{"go": "/system", "look": "the Heap census section", "expect": "a heading and one line, \"No heap census yet.\", with the button inside the disclosure"},
{"go": "/system", "look": "open the Heap census disclosure and press Take a heap census", "expect": "a flash naming the object count; the line now says one census and its uptime"},
{"go": "/system", "look": "press Take a heap census again straight away", "expect": "a 429 page saying when the next census may be taken, with a link back to System"}
]
🤖 Generated with Claude Code
Sound core: same-origin POST via readForm, person-admin only, ten-minute limit read from the stored row, bounded 21 rows, escaped output, read-only JSON. Two things to fix: (1) first: both doors. The terminal can only read a census, it cannot take one, so what an admin does on the page is not doable in the terminal; add the take action to the system screen (same canSeeMemory gate, same askCensus and ten-minute limit, same sentence on refusal) and update the docs line that says the terminal cannot. (2) The before/after screenshots box is unmet. Also tidy: the memorySection doc comment is orphaned above heapCensusSection, and the member test accepts 403 or 404 where it should pin one. The PR text also names src/perf/heap_diff.ts and says the terminal has no census section, neither true of this diff.
An admin can now take a heap census of the running forge from /system or from the terminal: a count of every object on the heap by type, kept to compare with the first one. After two or more, both show the 20 object types that grew most since the first census, with their counts then and now.
Limits and who may take one: taking a census holds the forge for a fraction of a second, so it is limited to one every ten minutes. Asking sooner gets a 429 with Retry-After and a sentence saying why. An agent's token is refused with a one-sentence reason (CENSUS_AGENT_REFUSED, now in src/perf/heap_census.ts so the page and the terminal say the same thing). The forge's admin guard refuses a member with a 403 before the route runs.
On /system: the Heap census section shows only its heading and one sentence on first view. The button, what a census costs and the table of types that grew are behind a disclosure. The /system first-view budget in docs/design/attention-budget.json goes up by +6 words and +2 blocks, with a note.
In the terminal: c on the system memory screen takes a census (takeCensus in src/tui/screens/system.ts). It uses the same gate (canSeeMemory), the same ten-minute limit (askCensus) and the same table the page reads. The result or the refusal is shown as a toast, and the key is listed only for an admin who is a person. The memory screen also shows the census count and the types that grew (censusLines).
API: GET /api/v1/telemetry/heap-census returns the censuses and the comparison as JSON, read-only.
From review:
- The
memorySectiondoc comment is back onmemorySection. - The member test now pins the 403, with the guard's sentence. It does not ask for 404, because the admin guard answers before the route runs, so the route can never return 404 to a member.
- The docs line in
docs/features/memory-growth.mdnow says the terminal can take a census. - I took no before/after screenshots: my sandbox has no browser, and the preview's /system redirects my token to sign in. The commit carries
Looks: /systemso the gate pictures the page.
What to look at: heapCensusSection and heapCensusSubmit in src/web/pages/system.ts; takeCensus and censusLines in src/tui/screens/system.ts; src/perf/heap_census.ts and its migration.
Checks: bun x tsc --noEmit, bun scripts/gate.ts --fix and bun scripts/design-lint.ts are clean. I ran the 62 test files that cover /system, the terminal's system screens and the census, including test/attention.test.ts: 604 pass, 0 fail. The full suite was too broad to run here.
[
{"go": "/system", "look": "the Heap census section", "expect": "a heading and one line, \"No heap census yet.\", with the button inside the disclosure"},
{"go": "/system", "look": "open the Heap census disclosure and press Take a heap census", "expect": "a flash naming the object count; the line now says one census and its uptime"},
{"go": "/system", "look": "press Take a heap census again straight away", "expect": "a 429 page saying when the next census may be taken, with a link back to System"}
]
🤖 Generated with Claude Code
<!-- look-pages 0fd9aaee3396 --> Look pages for 0fd9aae, from the gate:
look pages (named): this pull changes src/web/pages/system.ts; a commit names /system
I pushed nothing for this, so the branch is still at 0fd9aae. The note says the gate will picture /system because a commit names it. Like the same note on d04b093, it is the gate's tally of which pages to picture (src/checks/look_count.ts), not a failure or a request for a change.
An admin can now take a heap census of the running forge from /system or from the terminal: a count of every object on the heap by type, kept to compare with the first one. After two or more, both show the 20 object types that grew most since the first census, with their counts then and now.
Limits and who may take one: taking a census holds the forge for a fraction of a second, so it is limited to one every ten minutes. Asking sooner gets a 429 with Retry-After and a sentence saying why. An agent's token is refused with a one-sentence reason (CENSUS_AGENT_REFUSED, in src/perf/heap_census.ts so the page and the terminal say the same thing). The forge's admin guard refuses a member with a 403 before the route runs.
On /system: the Heap census section shows only its heading and one sentence on first view. The button, what a census costs and the table of types that grew are behind a disclosure. The /system first-view budget in docs/design/attention-budget.json goes up by +6 words and +2 blocks, with a note.
In the terminal: c on the system memory screen takes a census (takeCensus in src/tui/screens/system.ts). It uses the same gate (canSeeMemory), the same ten-minute limit (askCensus) and the same table the page reads. The result or the refusal is shown as a toast, and the key is listed only for an admin who is a person. The memory screen also shows the census count and the types that grew (censusLines).
API: GET /api/v1/telemetry/heap-census returns the censuses and the comparison as JSON, read-only.
From review:
- The
memorySectiondoc comment is back onmemorySection. - The member test pins the 403, with the guard's sentence. It does not ask for 404, because the admin guard answers before the route runs, so the route can never return 404 to a member.
docs/features/memory-growth.mdnow says the terminal can take a census.- I took no before/after screenshots: my sandbox has no browser, and the preview's /system redirects my token to sign in. The commit carries
Looks: /systemso the gate pictures the page.
What to look at: heapCensusSection and heapCensusSubmit in src/web/pages/system.ts; takeCensus and censusLines in src/tui/screens/system.ts; src/perf/heap_census.ts and its migration.
Checks: bun x tsc --noEmit, bun scripts/gate.ts --fix and bun scripts/design-lint.ts are clean. I ran the 62 test files that cover /system, the terminal's system screens and the census, including test/attention.test.ts: 604 pass, 0 fail. The full suite was too broad to run here.
[
{"go": "/system", "look": "the Heap census section", "expect": "a heading and one line, \"No heap census yet.\", with the button inside the disclosure"},
{"go": "/system", "look": "open the Heap census disclosure and press Take a heap census", "expect": "a flash naming the object count; the line now says one census and its uptime"},
{"go": "/system", "look": "press Take a heap census again straight away", "expect": "a 429 page saying when the next census may be taken, with a link back to System"}
]
🤖 Generated with Claude Code
Since d04b093: the terminal door (c on the memory screen, takeCensus, censusLines) uses the same canSeeMemory gate, the same ten-minute limit and the same table as the page, and has tests for the person admin, the agent, the member and the guest. The earlier asks are met: the terminal entry, the member test pinned to the 403, and the docs line saying the terminal can take a census. The write path goes through readForm (same-origin, admin scope, capped body), and the migration is pinned. The docs are in docs/features, not the README. The page uses btn, disclosure and a plain table, with no new accent and a budget note. Non-blocking: the pull carries no before/after screenshots of its own. The forge pictured /system at this head.
A forge admin can now take a heap census of the running forge from
/system, and the page compares it with the first census by object type. The census runs only when the button is pressed, never on a timer. This lets the retainer behind #15286's heap growth be found on production itself, without a copy of its data.What changed
src/perf/heap_census.ts(new): each census is oneheapStats()of the main VM, stored as{at, uptimeMin, heapSize, objectCount, byType}in a newheap_censustable (migration20261121230000-heap-census, pinned). It keeps only numeric counts and at most 2,000 types. It keeps the first census and the last 20, so 21 rows at most. The ten-minute limit is read from the last stored row, so it holds across a restart.grewMostranks the types that grew from the first census to the last; a type that is new since the first counts from 0, and a type that shrank is left out.POST /system/heap-census: goes throughreadForm, so it gets the same-origin check, an admin-scope token and a bounded body. It is for a forge admin who is a person (canSeeMemory). An agent's token, even an admin agent's, gets a 403 with one sentence; a non-admin person gets a 404. A second press within ten minutes gets a 429 withRetry-Afterand the reason./system: a new "Heap census" section under "Forge memory", owner only. It has one line, the button and a note that the census holds the forge for a fraction of a second. After two censuses it adds a table of the twenty types that grew most, with the first and last counts. The page is server-rendered and does not poll.GET /api/v1/telemetry/heap-census: the same data as JSON for the owner or an agent holdingtelemetry:read, through the existingtelemetryReadgate. Reading it never takes a census. It has an OpenAPI row.censusLinesinsrc/tui/screens/system.ts).docs/features/memory-growth.mdon how to use it.What to look at
test/system-parts.test.ts. It lists every section on/system, so it now includes "Heap census". The test wasn't wrong; the page gained a section.test/heap-census.test.tsexpects a non-admin member's POST to be refused with 403 or 404 rather than exactly 404. The forge refuses that member with a 403 before the request reaches the census handler. Either way, no census is taken.Not done
/systembutton takes one./systemon aLooks:line, so the forge's look pages should show it.keep_plantool wasn't available in this run.Checks run
bun x tsc --noEmit,bun scripts/gate.tsandbun scripts/design-lint.ts.test/heap-census.test.tsand the tests for the touched areas:/systemsections and timing, page budgets, OpenAPI and contract tests, body caps, doors, feature docs, the terminal system and memory screens, and telemetry grants.bun scripts/fast.tsnamed 3,306 files, too many to run here, so I chose these myself.Try it: open
/systemas the owner and press "Take a heap census". Press it again ten or more minutes later; the comparison table appears. ThenGET /api/v1/telemetry/heap-censuswith an owner token.🤖 Generated with Claude Code
Closes #15309