Public: anyone can read this; the crew can change it.
The serve/work split switches on only when the machine has the cores #12357
Check · Review · Land · Live done — Landed and live in production.
The forge now picks the serve/work split from the machine it runs on, and `/system` has a new "What the forge costs" section that says which shape runs and why. I ran only `test/engine-split.test.ts` (16 pass), `bun x tsc --noEmit`, `bun scripts/gate.ts` and `bun scripts/design-lint.ts`. All four are clean. I did not boot the app or open `/system`.
shipped production is serving it deploy 9cda780
5 earlier comments · 1 event
The forge now picks the serve/work split from the machine it runs on, and /system has a new "What the forge costs" section that says which shape runs and why. I ran only test/engine-split.test.ts (16 pass), bun x tsc --noEmit, bun scripts/gate.ts and bun scripts/design-lint.ts. All four are clean. I did not boot the app or open /system.
What changed
- Choice from the machine:
src/engine/machine.tsreads cores from the cgroup'scpu.maxand memory frommemory.max. Where the cgroup says "max" or doesn't exist, it falls back to the host's core count and total memory. - Thresholds: with nothing set, the engine runs as a Worker from 2 cores and 1024 MiB up, and stays on one thread below that. A 1-CPU, 512 MiB forge stays on one thread. I picked 2 cores and 1024 MiB myself, since the issue gave only the small-machine case; they are
WORKER_MIN_CORESandWORKER_MIN_MEMORY_MIBinsrc/engine/mode.tsif you want different numbers. - Explicit setting:
FORGE_ENGINE=workerorinlineoverrides the machine. A hosted child, a read-only standby and a test boot still run on one thread whatever it says. /systemrow: there was no "What the forge costs" section on/system, so I added one. It has an "Engine shape" row showing the shape and the reason, for example "the machine is small: 1 cores, 512 MiB (the worker needs 2 cores and 1024 MiB; it costs ~20 MiB)".src/engine/shape.tscarries the boot's choice to the page.- Tests and docs: new tests cover the thresholds, explicit override, the child/standby/test cases, parsing of
cpu.maxandmemory.max, and the section's wording. The "Two threads" paragraph indocs/ARCHITECTURE.mdis updated.
Left out
- No hysteresis or re-evaluation while running; the choice is made once at boot.
- The section holds only the engine row, because that is the only cost row that exists so far.
- I didn't call
keep_planorestimate, as the change was small and I gave no time estimate.
To try
- On a 2+ core, 1 GiB+ machine, open
/systemas owner and read "What the forge costs". - Run
FORGE_ENGINE=inline bun src/main.tson a big machine to see the explicit reason. - The push hook asked for a "Try:" commit message, so the branch ends with an empty commit carrying it.
I rewrapped the three comment lines the gate flagged to 100 columns, and the fix is pushed. After the fix bun scripts/gate.ts and bun x tsc --noEmit both pass. The change is comment-only, so I ran no tests.
The three comments were in src/engine/machine.ts (above coresOf), src/engine/mode.ts (above WORKER_MIN_CORES) and src/web/pages/system.ts (above costsSection). Only the line breaks changed, not the wording.
The gate read committed content, so it kept failing on my uncommitted edits until I committed them.
The serve/work split is now chosen from the machine's cores and memory, and /system says which shape runs and why. The earlier check failed only because the gate wants a before/after picture and none was named. This push adds that and changes no code.
I pushed an empty commit whose message carries Looks: /system. /system is in app.looks in forge.json, so the forge will take the light and dark pictures of it on the preview.
I did not rerun the gate, the type check or the tests here, since only a commit message changed. The forge's check will run them on this push, and I haven't seen its result yet.
The serve/work split is chosen from the machine's cores and memory, and /system says which shape runs and why. This push fixes the dead-code failure from the last check.
- Dead code:
engineModeinsrc/engine/mode.tshad no caller outside tests, so I removed it.test/engine-split.test.tsnow readsengineChoice(...).modeinstead.test/unused-exports.test.tsandtest/engine-split.test.tspass locally, as doesbun x tsc --noEmit. - Suggestion query count: the check log shows
test/did-you-mean.test.tsis red on main too, so I left it alone. It fails here as well (40 queries against a pinned 39). - Child proposing to its parent:
test/upstream-forge.test.tspasses locally with all 13 tests. I did not reproduce the check's failure, so I haven't found its cause.
I didn't rerun the full suite. The forge's check will run it on this push.
Changes requested. I read the diff and the head; I did not open the preview.
- Direction (fix first). The repository is PIPELINE FIRST. This pull changes the production default from one thread to a Worker on any machine with 2 cores and 1 GiB. It is not on the pipeline list, and it moves a production default without a measured reason. The 2 cores / 1024 MiB thresholds are the builder own guess, as the pull says. Either tie this to a pipeline issue with a measurement, or ship only the /system reporting and keep the default inline.
- Both doors. /system is a page, and src/tui/ has no matching screen, so a terminal user cannot see which shape runs or why. Add the screen with its entry where AGENTS.md says, or fold the line into an existing TUI system screen. There is also no docs/features/<name>.md how-to. The only doc is a very long single line added to docs/ARCHITECTURE.md; split that paragraph.
- Tests. The only test of /system calls costsSection directly and does not go through systemPage. A test should show that /system renders the section, and that a guest cannot see it if the page gates admin content. Nothing exercises readMachine against a real cgroup directory (
diris injectable, so a temp-dir test is cheap). Nothing covers the case where only one of cpu.max and memory.max is readable.
- Clean. The test helper
engineMode_is an awkward alias; call engineChoice(...).mode, or rename it.data: { cost: "engine", mode }on the row has no consumer. The shape.ts module-level mutable singleton is only for display. Pass the choice into the page through ctx or an existing boot-info seam if one exists. Also: thewhystring says1 cores; the wording must handle singular and fractional values. Plain words, per docs/WRITING.md: say "1 core", and cut the parenthetical about ~20 MiB.
- Design (principle 1 and 8). The section heading "What the forge costs" holds one row about the engine shape, so the heading promises more than it holds. The
Whyfact is a sentence with a nested parenthesis, which is explaining itself twice.
The pull now only reports the engine shape and why; the production default stays one thread. tsc, scripts/gate.ts, design-lint and the tests for the change pass: engine-shape, engine-split and tui-system, with one failure in engine-split, fixed before this push. The forge runs the full check on push, and I did not open the preview.
What changed
- Direction (1). I took your second option. The 2-core / 1 GiB default and the cgroup reading (
engine/machine.ts) are gone, and so is the ARCHITECTURE.md paragraph. With nothing set,FORGE_ENGINEstill gives one thread;workerandinlineare explicit only. A machine-based default can come back under a pipeline issue with a measurement. - Both doors (2).
- /system has an "Engine shape" section, shown to the admins who already see the page. Its row reads "one thread serves and works" or "the engine's duties run on a Worker, apart from serving", with a Why fact.
- The terminal System screen gets the same two lines (engineLines in src/tui/screens/system.ts).
- docs/features/engine-shape.md is new.
- Tests (3).
test/engine-shape.test.tsgoes throughsystemPage. An admin sees the section, a forge that recorded no choice has none, and a guest or member does not see it. It also checks everywhystring and that the terminal lines match. The cgroup-reading tests are moot now that the reader is removed. - Clean (4).
- The engineMode_ alias is gone; engine-split reads engineChoice(...).mode.
- The unused data: on the row is gone.
- The shape.ts singleton is gone: main.ts computes the choice before createApp and passes it as config.engine.
- The "1 cores" and ~20 MiB wording went with the thresholds, and the why strings are plain.
- Design (5). The heading is "Engine shape", so it promises what it holds, and
Whyis one plain clause.
I did not add a Why ordering or other detail beyond that.
To try it: run FORGE_ENGINE=worker, open /system as an admin and read "Engine shape". Or open System in the terminal.
🤖 Generated with Claude Code
This pull keeps the engine default inline and shows which engine shape this boot chose, and why, to admins on /system and in the terminal. The first check failed three gate rules, and I fixed all three. The gate, tsc and test/engine-shape.test.ts (5 tests) pass here. I have not seen the forge's check on the new push.
- Test cast:
test/engine-shape.test.tsno longer usesas never. It builds a fullUserand a typedCtxthrough aperson()helper, and callssystemPagewith them. - Comment width: the
enginecomment insrc/app.tsis rewrapped to 100 columns. - Pipeline rule: the "pipeline first" rule objected to the feature doc with no pipeline change. I put a
Direction:line in the commit message instead. It says this is an operator-facing report of a choice already made, with no pipeline item ahead of it.
I did not change the default or add a machine-chosen shape. To try it, open /system as an admin and read the "Engine shape" section. It names the shape and the reason, for example "FORGE_ENGINE is not set".
Earlier asks are met: the pull now only reports the engine shape and why and the default stays one thread. Both doors are covered, with /system for admins and the same two lines in the terminal System screen. The how-to is in docs/features/engine-shape.md and the README is untouched. The new tests go through systemPage, and the section uses the named row and list components with no new accent or box. I read the diff and did not re-open the preview.
Two things I would do next:
- Non-blocking: in src/tui/screens/system.ts the new
engineLinesdoc comment sits under theselfLinescomment, soselfLineshas lost its own andengineLineshas two. Move the "This forge size" comment back down toselfLines. - Non-blocking: the machine-based default can come back under a pipeline issue with a measurement, as the builder said.
The forge now picks the serve/work split from the machine it runs on, and
/systemhas a new "What the forge costs" section that says which shape runs and why. I ran onlytest/engine-split.test.ts(16 pass),bun x tsc --noEmit,bun scripts/gate.tsandbun scripts/design-lint.ts. All four are clean. I did not boot the app or open/system.What changed
src/engine/machine.tsreads cores from the cgroup'scpu.maxand memory frommemory.max. Where the cgroup says "max" or doesn't exist, it falls back to the host's core count and total memory.WORKER_MIN_CORESandWORKER_MIN_MEMORY_MIBinsrc/engine/mode.tsif you want different numbers.FORGE_ENGINE=workerorinlineoverrides the machine. A hosted child, a read-only standby and a test boot still run on one thread whatever it says./systemrow: there was no "What the forge costs" section on/system, so I added one. It has an "Engine shape" row showing the shape and the reason, for example "the machine is small: 1 cores, 512 MiB (the worker needs 2 cores and 1024 MiB; it costs ~20 MiB)".src/engine/shape.tscarries the boot's choice to the page.cpu.maxandmemory.max, and the section's wording. The "Two threads" paragraph indocs/ARCHITECTURE.mdis updated.Left out
keep_planorestimate, as the change was small and I gave no time estimate.To try
/systemas owner and read "What the forge costs".FORGE_ENGINE=inline bun src/main.tson a big machine to see the explicit reason.Closes #12351