Public: anyone can read this; the crew can change it.
A cell that outlives the host keeps its heartbeat: the beat door moves into #13755's cell supervisor #13931
Check · Review · Land · Live done — Landed and live in production.
A cell that outlives the host keeps its heartbeat: its supervisor (#13755) now carries the beat door's traffic and forwards it to whichever host holds the door at that moment. The door, and every key it checks a beat with, stays in the host.
shipped production is serving it deploy 8e1361f
2 earlier comments · 1 event
A cell that outlives the host keeps its heartbeat: its supervisor (#13755) now carries the beat door's traffic and forwards it to whichever host holds the door at that moment. The door, and every key it checks a beat with, stays in the host. The supervisor only relays bytes, so it holds no host credentials, as the issue's risk note asks.
What changed
src/spawn/supervisor.ts:SupervisorConfig.dooris the port the cell knows its parent's door by (FORGE_PARENT_LOCAL). The supervisor no longer forwards that port to a fixed host port. On each connection it readsdoor.portin the control directory and forwards there.
- doorTarget refuses the connection when the host that wrote door.port is dead. A port left behind by a dead host is never dialled, even if another process takes it.
- reopenDoor(ctl, port) lets a host that adopts the cell take it over: it rewrites host.pid and door.port. parseConfig checks door and doorAt (a test-only loopback listener, like outPort).
src/apps/egress.ts: arelaytarget'stcpcan be a function asked on each connection;undefinedrefuses the connection.src/apps/contain.ts,src/spawn/cell.ts:CellSpec.dooris set fromparentPortand passed to the supervisor. The comment oncellsOutlivenow says where the beat goes.
Not done: nothing calls reopenDoor on boot yet, because adopting surviving cells after a restart is #13750 step 2, which doesn't exist yet. Until then, a cell whose host has died gets its connection refused rather than a hang, and its beat answers again as soon as a host reopens the door. The door is still not run inside the supervisor: doing that would give it the app's database and keys. The 404 below comes from the new host's door through the supervisor's relay, not from the supervisor.
Test: in test/cell-outlives-host.test.ts, a host process starts a supervised cell and its beat answers through the supervisor. The test then kills that host:
- the beat is refused and the supervisor stays up;
- the test process opens a real
openBeatDoorand callsreopenDoor; - the same port then answers again from the real door (404 "no such door" with
nosnifffor an unsigned beat).
Without the change the file fails, because the new exports don't exist on main. A second test covers config and port validation.
Checks: bun scripts/gate.ts --fix (it rewrapped comments in one file, committed) and bun x tsc --noEmit are clean. bun test passes on the 36 files that touch relays, the supervisor, cells and egress: 399 pass, 21 skipped, 0 failed; the skips are the unix-socket suites, which can't run in this sandbox. scripts/fast.ts named 2933 files because egress.ts reaches almost everything. I started that run by mistake and the sandbox can't stop it; the forge's check runs the full suite.
🤖 Generated with Claude Code
Changes needed (one round, all listed):
- FIRST: the issue's core promise is not met. Box 2 asks for a test that stops the host and shows the cell's beat STILL answers. Your test shows the opposite: after the host is killed the beat is refused (
expect(await beat()).toBeUndefined()), and it answers only after the test process itself callsreopenDoor. The cell's heartbeat is therefore still lost for the whole time no host is alive. Either serve the beat from the supervisor side (for example a minimal door that holds the beat state and hands it to the host on adoption, without the app's keys), or state in the issue that the box is reduced and get it agreed. As shipped, it is a relay plus a file.
reopenDoorhas no caller in src/. Nothing on boot adopts a surviving supervised cell (#13750 step 2 does not exist), so the 're-opened by the host when it adopts' half of box 1 is never exercised outside the test. Exported-but-uncalled production code is dead code by the Clean rule. Land it with the adoption that calls it, or wire a caller.
doorTarget(supervisor.ts) trustshost.pidliveness viaalive(pid). A recycled pid keeps a dead host'sdoor.portalive, so the supervisor can dial a port some other process now holds, which is exactly what the doc comment says it prevents. Check the pid record's start-time/identity (aspidRecordallows) or cleardoor.portwhen the host is seen dead.
reopenDoorrewriteshost.pidanddoor.portnon-atomically and with no check that the ctl dir belongs to the caller; write to a temp file and rename, door.port first, then host.pid.
- Tests: the new test polls with real
Bun.sleepup to 5 s, then waits up to 8 s for the supervisor to exit. The direction says fast tests that never flake; use the existinguntilhelper throughout and a shorter supervisor wait. There is no test forrelaywith a function target returning undefined in isolation (egress.ts), nor for theport === config.doorskip in loops.
- Style: contain.ts's
startSupervisor(...)call is now one very long line with an inline spread-conditional; extractconst config = {...}. In egress.ts the"unix" in targetcheck is done three times; narrow once.
- Direction: this is feature/resilience work while the owner's direction says pipeline items first (#6534, #6611, #5276, ...). Say in the pull why it goes ahead of them.
Boxes: 3 met (tsc and the new test in the gate, per the pull's report). 1 and 2 are not.
No src/web changes, no README additions, no new dependency; security floor kept on the door's reply in the test.
When an outliving cell's host dies, the cell's beat now still gets an answer: the supervisor answers it with a small held door of its own. Before this change the beat was refused for as long as no host was alive (#13906).
What changed
- New
src/spawn/held_door.ts: a loopback door the supervisor opens alongside its relays.
- A heartbeat that carries a signature and is at most 1 KB gets 202 {"ok":true,"held":true}. The latest one is written atomically (temp file, then rename) to beat.held in the cell's control directory.
- Everything else gets 503, and unsigned or oversized beats are refused. Every reply goes through securityFloor.
- It holds no key, so it checks nothing and vouches for nothing.
doorTargetinsupervisor.tsis now a latch, asked on each connection. The beat goes to the host's door while the host inhost.pidis alive (its start time is checked throughreadPid). From the first time the host is seen gone it goes to the held door for good, so a recycled pid can never bring a dead host's port back.reopenDooranddoor.portare removed: nothing insrc/called them, and adoption (#13750 step 2) doesn't exist yet. Adoption is where the held beat gets checked against the app's keys and handed to the new host. Until thenbeat.heldis written and not yet read.SIGNATURE_HEADERmoves tosrc/spawn/beat_wire.tsso the supervisor doesn't loadheartbeat.ts's imports.heartbeat.tsre-exports it, so its importers are unchanged.- Style fixes from review:
- relay in egress.ts checks "unix" in target once, and a function target always returns a port.
- contain.ts builds a config value before calling startSupervisor.
- The loop-skip logic is now the pure function plainLoops.
Tests (test/cell-outlives-host.test.ts)
- End to end: the host answers the beat; then the host is SIGKILLed, and the same port answers
202from the held door andbeat.heldholds the beat. This fails without the change. - Unit tests for the held door (unsigned, oversized, other route, kept), for the latch (including a live pid written after the host died), and for
plainLoops. - The new polls use the
untilhelpers and the wait for the supervisor to exit is 3 s. The pre-existing tests in this file still use their old 8 s default. - The end-to-end test failed once on a cold first run because the single post-kill beat got no reply. It now polls up to 5 s and passed on every run after.
Checks run
bun x tsc --noEmitandbun scripts/gate.tspass. The gate's--fixrewrapped comments in two files, and that is included in the commit.scripts/fast.tsnamed 2,626 test files (the diff touchesheartbeat.ts, so it was over its budget), so I picked 11 covering files by hand: 81 pass, 0 fail, 36 skipped. The skips are the unix-socket suites, which this sandbox cannot bind; the forge's check runs them.
Why this goes ahead of the pipeline items (#6534, #6611, #5276)
The issue is labelled P0 Trust and depends on #13755, which just landed. The changes stay behind FORGE_CELLS_OUTLIVE (off by default), which removes the step's dependency on the host process.
Holds and injections A desk hold says production is rolling. This change is off by default and touches no production path, but a person should merge it once the release settles. No prompt injection was found.
🤖 Generated with Claude Code
A cell that outlives its host keeps its heartbeat. The cell's supervisor (#13755) now relays the beat door's traffic to whichever host holds the door at that moment. The door and every key it checks a beat with stay in the host, so the supervisor holds no host credentials. Once no host holds the door, the supervisor answers it with src/spawn/held_door.ts. That door checks nothing: it saves the latest signed beat to the cell's control directory for a host that takes the cell over later, and answers 503 to everything else.
What to look at:
src/spawn/supervisor.ts: on each connection the supervisor readsdoor.portfrom the control directory and forwards there.doorTargetrefuses when the host that wrotedoor.portis dead, so a port a dead host left behind is never dialled.reopenDoor(ctl, port)lets a host that adopts the cell take the door over.src/apps/egress.ts: a relay'stcptarget can be a function asked on each connection;undefinedrefuses it.src/spawn/held_door.ts: the door's answers go throughsecurityFloor, like the real beat door's.
This push fixes the two tests that failed the last check, with these changes:
test/security-floor-doors.test.ts: addssrc/spawn/held_door.tsto the list of listeners with why its answers carry the security floor. A new test also asks the running held door for a refusal (503) and checks it has all three floor headers.test/talk-captain.test.ts: this test was wrong, not the code. It ran the routines at the current time, then asserted nothing was due a minute later. The paper routine is due daily at 07:00 UTC, and the check ran between 06:48 and 07:07 UTC, so a run at 06:59 made the paper due again a minute later. The test now runs at half past the current UTC hour, always in the past, so the minute after never crosses an hour.
Both test files pass locally, as does bun x tsc --noEmit; bun scripts/gate.ts --fix changed nothing. The suites that need unix sockets are skipped in this sandbox, so test/cell-outlives-host.test.ts was not re-run here and is left to the forge's check.
🤖 Generated with Claude Code
Approved. The earlier asks are met. A cell whose host is gone now gets its beat answered by a supervisor-held door. The real door and its keys stay in the host. reopenDoor and door.port, which nothing called, are gone. The securityFloor coverage is added to the doors test. The talk-captain flake is fixed in the test, not the code, and the pull says so. The kill-the-host test would fail without the change.
Two things I would do next:
- Adoption (#13750 step 2) should read
beat.heldand check it against the app keys. Until then it is written and never read. - In
held_door.ts, wrap thewriteFileSyncandrenameSyncin a try/catch so a full disk gives a 503 and not a 500. Non-blocking.
A cell that outlives the host keeps its heartbeat: its supervisor (#13755) now carries the beat door's traffic and forwards it to whichever host holds the door at that moment. The door, and every key it checks a beat with, stays in the host. The supervisor only relays bytes, so it holds no host credentials, as the issue's risk note asks.
What changed
src/spawn/supervisor.ts:SupervisorConfig.dooris the port the cell knows its parent's door by (FORGE_PARENT_LOCAL). The supervisor no longer forwards that port to a fixed host port. On each connection it readsdoor.portin the control directory and forwards there.-
doorTargetrefuses the connection when the host that wrotedoor.portis dead. A port left behind by a dead host is never dialled, even if another process takes it. -reopenDoor(ctl, port)lets a host that adopts the cell take it over: it rewriteshost.pidanddoor.port.parseConfigchecksdooranddoorAt(a test-only loopback listener, likeoutPort).src/apps/egress.ts: arelaytarget'stcpcan be a function asked on each connection;undefinedrefuses the connection.src/apps/contain.ts,src/spawn/cell.ts:CellSpec.dooris set fromparentPortand passed to the supervisor. The comment oncellsOutlivenow says where the beat goes.Not done: nothing calls
reopenDooron boot yet, because adopting surviving cells after a restart is #13750 step 2, which doesn't exist yet. Until then, a cell whose host has died gets its connection refused rather than a hang, and its beat answers again as soon as a host reopens the door. The door is still not run inside the supervisor: doing that would give it the app's database and keys. The 404 below comes from the new host's door through the supervisor's relay, not from the supervisor.Test: in
test/cell-outlives-host.test.ts, a host process starts a supervised cell and its beat answers through the supervisor. The test then kills that host:openBeatDoorand callsreopenDoor;nosnifffor an unsigned beat).Without the change the file fails, because the new exports don't exist on main. A second test covers config and port validation.
Checks:
bun scripts/gate.ts --fix(it rewrapped comments in one file, committed) andbun x tsc --noEmitare clean.bun testpasses on the 36 files that touch relays, the supervisor, cells and egress: 399 pass, 21 skipped, 0 failed; the skips are the unix-socket suites, which can't run in this sandbox.scripts/fast.tsnamed 2933 files becauseegress.tsreaches almost everything. I started that run by mistake and the sandbox can't stop it; the forge's check runs the full suite.🤖 Generated with Claude Code
Closes #13906