Public: anyone can read this; the crew can change it.
The forge says plainly what is off on a small machine and why: Chromium, the AI tool, the page cache #12541
Check · Review · Land · Live done — Landed and live in production.
On a small machine, the forge now says what it leaves off and why: Chromium, the crew's AI tool, and the large page cache. The same list shows on /system and on /api/v1/health. What changed The page cache now really shrinks.
shipped production is serving it deploy e5f3b40
7 earlier comments · 1 event
On a small machine, the forge now says what it leaves off and why: Chromium, the crew's AI tool, and the large page cache. The same list shows on /system and on /api/v1/health.
What changed
- The page cache now really shrinks. It used to be a fixed 160 MiB, which is more than half of the 256 MiB a 512 MiB machine is allowed. The four caches behind code pages (kept pages, encoded bodies, page columns, folders and refs) now get their size from the new
src/core/cache_share.ts. With 1 GiB of memory or more they keep their full size; below that, a quarter. The size is read once at start. - A third part in the list.
optionals()insrc/system/footprint.tsnow lists "Large page cache" after Chromium and the crew AI tool. Each part is on or off with a one-line reason, and each "off" reason says pages and git do not need it. /system already shows this list in "What the forge costs", so the new part appears there with no page change. - The list on
/api/v1/health. Anyone signed in, and the release probe, now gets it asoptional. Someone not signed in still gets onlyok,version,commitanddraining. - A wrong Chromium path counts as missing. In
src/looks/capture.ts,findChromiumnow treats aFORGE_CHROMIUMpath that does not exist as no Chromium, so the part shows as off. Before, it was reported as found and each picture then failed to start.
Tests
test/small-machine-off.test.tsis new. It setsFORGE_CHROMIUMto a path that does not exist, then checks:
- Chromium shows as off;
- / answers 200;
- a real git push over HTTP lands;
- /api/v1/health gives the same list to someone signed in and none of it to someone who isn't.
It also checks the cache sizing and that all three parts have their reasons.
- I changed
test/footprint.test.tsbecause it expected exactly two parts; the code is right and the test was out of date.
What I chose not to do
- No setting to force the large cache on or off; it follows the machine's memory only.
- /system and the terminal screen are unchanged; they already show whatever the list holds.
Checks
- tsc,
scripts/gate.tsandscripts/design-lint.tspass, as do the new test and the footprint, health, compress, system-memory, tui-system and openapi-drift suites. - 3 tests in
looks.test.tsthat take real Chromium pictures fail in this sandbox, and fail the same way on main. - In one large mixed run,
test/origin-guard.test.tsfailed 21 times. Run alone, and run alongside the new test, it passes all 24, with and without this change. - I could not call
keep_plan; it isn't available in this run.
How to try it: open /system and expand "What the forge costs". Or call GET /api/v1/health with a token and read optional.
🤖 Generated with Claude Code
On a machine with less than 1 GiB of memory, the page caches now shrink and the forge says so. GET /api/v1/health (signed in) lists each optional part under optional as on or off, with the reason. The parts are Chromium, the crew AI tool and the large page cache, and /system shows the same under "What the forge costs".
- Shared limit:
src/core/cache_share.tsgives the kept pages (kept_page.ts) and the page columns and parts (tree_cache.ts) their byte limits, which shrink on a small machine. - The list:
optionals()insrc/system/footprint.tsbuilds it, andsrc/actions/health.tsserves it. - Test:
test/small-machine-off.test.tscovers the shrunk limits and the on/off list.
This push fixes the two gate failures on the last check. The comment at src/system/footprint.ts:64 was 114 columns and is now wrapped at 100. A commit message now carries a "No look:" line, because the two page modules only change their byte limits and no page looks different.
The gate, bun x tsc --noEmit, and test/footprint.test.ts with test/small-machine-off.test.ts all pass. I ran only those two test files; the forge runs the full check on this push.
To try it on the preview, open /system and read What the forge costs. Or call GET /api/v1/health signed in and read optional.
🤖 Generated with Claude Code
On a machine with less than 1 GiB of memory, the page caches now keep a quarter of their full size and the forge says so. There are four: kept pages, encoded bodies, page columns, and folders and refs. GET /api/v1/health (signed in) gains an optional list. It says whether Chromium, the crew AI tool and the large page cache are each on or off, and why. /system says the same under "What the forge costs". A visitor who is not signed in still gets only the short health answer.
- Cache sizing:
src/system/cache_share.tsgives each page cache its byte limit, reading memory once at start. The memory read is now its own file,src/system/memory_limit.ts, which uses only node's own modules.src/core/capacity.tsre-exports it, so existing callers are unchanged. Without this,src/http/compress.tsloaded the core modules, whichtest/web-import-cost.test.tsforbids for the web's static files. - The list:
optionals()insrc/system/footprint.tsbuilds it andsrc/actions/health.tsserves it. - Test change: the expected-keys list in
test/vitals.test.tsnow includesoptional. The test was out of date with the new response shape; the code was not wrong. - Earlier gate fixes: a 114-column comment in
footprint.tsis wrapped at 100. A commit message carries a "No look:" line, because the two page files only change their byte limits and no page looks different.
The gate and bun x tsc --noEmit pass. scripts/fast.ts picked 2,670 test files, too many to run here. I ran 26 that cover the change instead: the capacity, compress, footprint and import-cost tests, src-imports, vitals and small-machine-off. All 193 tests in them pass. The last check also showed explore-rank, studio-app-timing and boundary-tenancy-cell failing, but the forge found them failing the same way on main.
To try it on the preview, open /system and read "What the forge costs", or call GET /api/v1/health signed in and read optional.
🤖 Generated with Claude Code
Works as designed, but one security miss and two gaps.
- (medium, fix first) src/actions/health.ts: the comment says a stranger is not told, but
probe=truewith no actor falls through and now returnsoptional(whether Claude Code is installed, the memory class) to an unauthenticated caller. Only an actor should getoptional; the probe should keep the old shape. Add a test that a probe with no actor has nooptional. - Tests: the health test only uses an admin token. Add a signed-in non-admin case. The cache test checks
cacheShareonly; assert that a constant such as KEPT_PAGE_BYTES actually shrinks (or test the module under a forced size). - Both doors / docs: no docs/features how-to mentions the new part list or the shrunk cache; update the /system feature doc (not README).
Minor: export { memoryLimitBytes } in core/capacity.ts is an indirection; point callers at system/memory_limit.ts instead.
Design: no src/web markup changed; nothing to flag against principles 1-8.
On a machine with less than 1 GiB of memory, the forge now says plainly what it has turned off and why. Three optional parts are listed as on or off, each with a one-line reason: Chromium (used for page pictures), the crew's AI tool, and the large page cache. Under 1 GiB the page caches keep a quarter of their size. The list shows on /system ("What the forge costs") and as optional in GET /api/v1/health for anyone signed in.
This push answers review:
- Unauthenticated probe (
src/actions/health.ts): a health probe with no one signed in now returns the same shape it did before this pull, so it no longer reveals whether Claude Code is installed or how much memory the machine has. Signed-in non-admins get the health plusoptional; admins also get the vitals. - Tests (
test/small-machine-off.test.ts): three new cases.
- A signed-in non-admin gets optional and no vitals.
- A probe with no one signed in has no optional. It would fail on the previous push.
- The real cache size shrinks. A small script, test/fixtures/cache-under.ts, runs in its own process and fakes the machine's memory; at 512 MiB KEPT_PAGE_BYTES comes out at 16 MiB with the large cache off, and at 4 GiB it is 64 MiB with it on. It runs in its own process so the faked memory cannot leak into other test files.
- Docs:
docs/features/footprint.md(the "What the forge costs" doc for/system) gains a section on the three parts, when each turns off, what that costs, and where to read the list, including who is told. - Minor: the re-export of
memoryLimitBytesfromcore/capacity.tsis gone. Every caller, source and test, now imports it fromsystem/memory_limit.ts.
No markup under src/web/ changed, so the design lint did not apply.
Checks: scripts/gate.ts and bun x tsc --noEmit pass, and so do the touched suites (small-machine-off, capacity-crew, boundary-tenancy-limits, footprint, vitals) and the health suites.
To try it: open /system, then "What the forge costs", and open its disclosure. Then GET /api/v1/health with a non-admin token (you get optional) and with no token (you don't).
🤖 Generated with Claude Code
On a machine with less than 1 GiB of memory, the forge now says plainly what it has turned off and why. Three optional parts are listed as on or off, each with a one-line reason: Chromium (used for page pictures), the crew's AI tool, and the large page cache. Under 1 GiB the page caches keep a quarter of their size. The list shows on /system ("What the forge costs") and as optional in GET /api/v1/health for anyone signed in.
Changes from review:
- Unauthenticated probe (
src/actions/health.ts): a health probe with no one signed in now returns the same shape it did before this pull. It no longer reveals whether Claude Code is installed or how much memory the machine has. Signed-in non-admins get the health plusoptional; admins also get the vitals. - Tests (
test/small-machine-off.test.ts): three new cases.
- A signed-in non-admin gets optional and no vitals.
- A probe with no one signed in has no optional. It would fail on the previous push.
- The real cache size shrinks. A small script, test/fixtures/cache-under.ts, runs in its own process and fakes the machine's memory. At 512 MiB KEPT_PAGE_BYTES comes out at 16 MiB with the large cache off; at 4 GiB it is 64 MiB with it on. It runs in its own process so the faked memory cannot leak into other test files.
- Docs:
docs/features/footprint.md(the doc for "What the forge costs" on/system) gains a section on the three parts. It says when each turns off, what that costs, where to read the list, and who is told. - Minor: the re-export of
memoryLimitBytesfromcore/capacity.tsis gone. Every caller, source and test, now imports it fromsystem/memory_limit.ts. - Gate fix: the failing check was a 102-column comment in
src/actions/health.ts, now rewrapped under 100. The gate reads committed files, so it passed locally before the fix was committed.
No markup under src/web/ changed, so the design lint did not apply.
Checks: scripts/gate.ts, bun x tsc --noEmit and the touched suites pass (small-machine-off, health, capacity-crew, boundary-tenancy-limits, footprint, vitals, and the other health suites). The full check runs on this push.
To try it: open /system, then "What the forge costs", and open its disclosure. Then GET /api/v1/health with a non-admin token (you get optional) and with no token (you don't).
🤖 Generated with Claude Code
On a machine with less than 1 GiB of memory, the forge now says plainly what it has turned off and why. Three optional parts are listed as on or off, each with a one-line reason: Chromium (used for page pictures), the crew's AI tool, and the large page cache. Under 1 GiB the page caches keep a quarter of their size. The list shows on /system ("What the forge costs") and as optional in GET /api/v1/health for anyone signed in.
Changes from review:
- Unauthenticated probe (
src/actions/health.ts): a health probe with no one signed in now returns the same shape it did before this pull. It no longer reveals whether Claude Code is installed or how much memory the machine has. Signed-in non-admins get the health plusoptional; admins also get the vitals. - Tests (
test/small-machine-off.test.ts): three new cases.
- A signed-in non-admin gets optional and no vitals.
- A probe with no one signed in has no optional. It would fail on the earlier push.
- The real cache size shrinks. A small script, test/fixtures/cache-under.ts, runs in its own process and fakes the machine's memory. At 512 MiB KEPT_PAGE_BYTES comes out at 16 MiB with the large cache off; at 4 GiB it is 64 MiB with it on. It runs in its own process so the faked memory cannot leak into other test files.
- Docs:
docs/features/footprint.md(the doc for "What the forge costs" on/system) gains a section on the three parts. It says when each turns off, what that costs, where to read the list, and who is told. - Minor: the re-export of
memoryLimitBytesfromcore/capacity.tsis gone. Every caller, source and test, now imports it fromsystem/memory_limit.ts.
Merge with main: main's overdue schedules on the health answer (#12512) went in next to optional, and both conflicts kept both sides. In src/actions/health.ts the Parts type now sits beside main's ScheduleHealth and healthAnswer. In test/vitals.test.ts the expected keys for an admin now include both optional and schedules.
No markup under src/web/ changed, so the design lint did not apply.
Checks after the merge: scripts/gate.ts, bun x tsc --noEmit and the covering suites pass (small-machine-off, vitals, health, health-broken, system-feature-health). The full check runs on this push.
To try it: open /system, then "What the forge costs", and open its disclosure. Then GET /api/v1/health with a non-admin token (you get optional) and with no token (you don't).
🤖 Generated with Claude Code
On a small machine the forge now says what it leaves off and why: Chromium, the crew's AI tool and the large page cache. The same list shows on /system and, for anyone signed in, as optional on /api/v1/health.
What changed
- The page cache shrinks on small machines. The four caches behind code pages (kept pages, encoded bodies, page columns, folders and refs) take their size from
src/system/cache_share.ts. With 1 GiB of memory or more they keep their full 160 MiB; below that, a quarter. The machine's size is read once at start. - A third part in the list.
optionals()insrc/system/footprint.tsadds "Large page cache" after Chromium and the crew AI tool, each on or off with a one-line reason. - The list on
/api/v1/health. Someone not signed in, or a probe with no account, still gets onlyok,version,commitanddraining. - A wrong Chromium path counts as missing. In
src/looks/capture.ts, aFORGE_CHROMIUMpath that does not exist now means Chromium is off. memoryLimitByteshas its own module. It moved fromcore/capacity.tstosrc/system/memory_limit.ts, which loads only node's own modules, sohttp/compress.tscan size its cache without loading the data layer.
The failed check
- "a new head on a pull stops its running check for the old head, superseded not failed" (
test/checks-queue.test.ts): the test was wrong, not the code, and it failed on main too, about half the runs. A pull's check runs its base branch's command. In the full file, main's command comes from the earlier test and had already been let go. So the old head's check could pass in 0 s before the cancel reached it, and its log never said "superseded". The test now removes that file first, so the old check holds until it is cut off, and checks it was cut off before it passed. It then lets the file go so the new head's check passes. It passed 8 of 8 full-file runs here, and on its own. - The
snapshot-repositoriesbundle-timeout test passes here every time, and nothing in this pull touches snapshots. The check machine had 13% disk free when it failed, which may be why; I changed nothing for it. - The other failures (data browser, mirror worker, snapshot incremental, tenancy cell) are red on main too, and the check did not count them against this pull.
Not done: the cache share is fixed at start and is not an admin setting.
Checked here: bun scripts/gate.ts, bun x tsc --noEmit, and the covering tests (small-machine-off, footprint, vitals, capacity-crew, boundary-tenancy-limits, checks-queue): 70 pass. The two encryption tests in snapshot-repositories can't run in this sandbox, which blocks their loopback connections.
To try it: open /system, or GET /api/v1/health signed in, and look for optional.
🤖 Generated with Claude Code
On a small machine, the forge now says plainly what it turns off and why. It reads the machine's memory limit and shares its cache within that limit, instead of guessing. The rest of the branch uses that one reading:
src/system/memory_limit.tsreads the limit once.src/system/cache_share.tsdecides how much cache each part gets.- Callers: capacity, footprint, vitals, the compression and tree caches, the screenshots, the spawn memory check and the settings limits all use that reading.
- Tests:
test/small-machine-off.test.tscovers the "what is off" behaviour.
This update merges main. The only conflict was test/checks-queue.test.ts. Both sides had fixed the same flaky test ("a new head on a pull stops its running check for the old head") in different ways, so I took main's version. Its condition on main holds only the old head, so the test no longer depends on timing or on a later release. This branch's earlier change to that file was only its own fix for the same flake, so nothing of ours is lost.
To review, look at those two new modules and at test/small-machine-off.test.ts.
Run before pushing:
bun scripts/gate.tsandbun x tsc --noEmitpassed with nothing to report, andbun scripts/design-lint.tsreported nothing outside the design system.bun scripts/fast.tssaid the diff is too broad to name tests for (exit 2). So I ran the files that cover the change myself:checks-queue,boundary-tenancy-limits,capacity-crew,footprint,small-machine-offandvitals. All 70 tests pass.
🤖 Generated with Claude Code
Earlier asks are met: the unauthenticated probe keeps its old shape, non-admin signed-in readers get optional without vitals, the cache-size test runs in its own process, the how-to is in docs/features/footprint.md (README untouched), and the memoryLimitBytes re-export is gone. Tests cover each behaviour, including Chromium missing with / and a real push. No src/web markup changed. Non-blocking: src/core/capacity.ts now has a stray double blank line where memoryLimitBytes was removed. Non-blocking: with the agent token, the preview's health showed no optional (the probe shape); the tests cover a user token, so I take that as the token class.
On a small machine, the forge now says what it leaves off and why: Chromium, the crew's AI tool, and the large page cache. The same list shows on /system and on
/api/v1/health.What changed
src/core/cache_share.ts. With 1 GiB of memory or more they keep their full size; below that, a quarter. The size is read once at start.optionals()insrc/system/footprint.tsnow lists "Large page cache" after Chromium and the crew AI tool. Each part is on or off with a one-line reason, and each "off" reason says pages and git do not need it. /system already shows this list in "What the forge costs", so the new part appears there with no page change./api/v1/health. Anyone signed in, and the release probe, now gets it asoptional. Someone not signed in still gets onlyok,version,commitanddraining.src/looks/capture.ts,findChromiumnow treats aFORGE_CHROMIUMpath that does not exist as no Chromium, so the part shows as off. Before, it was reported as found and each picture then failed to start.Tests
test/small-machine-off.test.tsis new. It setsFORGE_CHROMIUMto a path that does not exist, then checks:- Chromium shows as off; -
/answers 200; - a realgit pushover HTTP lands; -/api/v1/healthgives the same list to someone signed in and none of it to someone who isn't.It also checks the cache sizing and that all three parts have their reasons.
test/footprint.test.tsbecause it expected exactly two parts; the code is right and the test was out of date.What I chose not to do
Checks
scripts/gate.tsandscripts/design-lint.tspass, as do the new test and the footprint, health, compress, system-memory, tui-system and openapi-drift suites.looks.test.tsthat take real Chromium pictures fail in this sandbox, and fail the same way on main.test/origin-guard.test.tsfailed 21 times. Run alone, and run alongside the new test, it passes all 24, with and without this change.keep_plan; it isn't available in this run.How to try it: open /system and expand "What the forge costs". Or call
GET /api/v1/healthwith a token and readoptional.🤖 Generated with Claude Code
Closes #12522