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

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

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.

Notes

shipped production is serving it deploy e5f3b40

opened this

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() in src/system/footprint.ts now 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 as optional. Someone not signed in still gets only ok, version, commit and draining.
  • A wrong Chromium path counts as missing. In src/looks/capture.ts, findChromium now treats a FORGE_CHROMIUM path 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.ts is new. It sets FORGE_CHROMIUM to 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.ts because 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.ts and scripts/design-lint.ts pass, as do the new test and the footprint, health, compress, system-memory, tui-system and openapi-drift suites.
  • 3 tests in looks.test.ts that take real Chromium pictures fail in this sandbox, and fail the same way on main.
  • In one large mixed run, test/origin-guard.test.ts failed 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

Closes #12522

7 earlier comments · 1 event
commented

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() in src/system/footprint.ts now 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 as optional. Someone not signed in still gets only ok, version, commit and draining.
  • A wrong Chromium path counts as missing. In src/looks/capture.ts, findChromium now treats a FORGE_CHROMIUM path 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.ts is new. It sets FORGE_CHROMIUM to 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.ts because 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.ts and scripts/design-lint.ts pass, as do the new test and the footprint, health, compress, system-memory, tui-system and openapi-drift suites.
  • 3 tests in looks.test.ts that take real Chromium pictures fail in this sandbox, and fail the same way on main.
  • In one large mixed run, test/origin-guard.test.ts failed 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

commented

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.ts gives 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() in src/system/footprint.ts builds it, and src/actions/health.ts serves it.
  • Test: test/small-machine-off.test.ts covers 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

commented

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.ts gives 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.ts re-exports it, so existing callers are unchanged. Without this, src/http/compress.ts loaded the core modules, which test/web-import-cost.test.ts forbids for the web's static files.
  • The list: optionals() in src/system/footprint.ts builds it and src/actions/health.ts serves it.
  • Test change: the expected-keys list in test/vitals.test.ts now includes optional. 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.ts is 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

Changes requested — before the latest push

Works as designed, but one security miss and two gaps.

  1. (medium, fix first) src/actions/health.ts: the comment says a stranger is not told, but probe=true with no actor falls through and now returns optional (whether Claude Code is installed, the memory class) to an unauthenticated caller. Only an actor should get optional; the probe should keep the old shape. Add a test that a probe with no actor has no optional.
  2. Tests: the health test only uses an admin token. Add a signed-in non-admin case. The cache test checks cacheShare only; assert that a constant such as KEPT_PAGE_BYTES actually shrinks (or test the module under a forced size).
  3. 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.

commented

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 plus optional; 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 memoryLimitBytes from core/capacity.ts is gone. Every caller, source and test, now imports it from system/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

commented

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 plus optional; 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 memoryLimitBytes from core/capacity.ts is gone. Every caller, source and test, now imports it from system/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

commented

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 plus optional; 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 memoryLimitBytes from core/capacity.ts is gone. Every caller, source and test, now imports it from system/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

commented

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() in src/system/footprint.ts adds "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 only ok, version, commit and draining.
  • A wrong Chromium path counts as missing. In src/looks/capture.ts, a FORGE_CHROMIUM path that does not exist now means Chromium is off.
  • memoryLimitBytes has its own module. It moved from core/capacity.ts to src/system/memory_limit.ts, which loads only node's own modules, so http/compress.ts can 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-repositories bundle-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

commented

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.ts reads the limit once.
  • src/system/cache_share.ts decides 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.ts covers 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.ts and bun x tsc --noEmit passed with nothing to report, and bun scripts/design-lint.ts reported nothing outside the design system.
  • bun scripts/fast.ts said 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-off and vitals. All 70 tests pass.

🤖 Generated with Claude Code

Approved

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.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs