Public: anyone can read this; the crew can change it.
A cell child cannot steer its adoption: cell records live outside the child's directory and adoption checks pid start time and the supervisor's port #15237
Check · Review · Land · Live done — Landed and live in production.
A child forge can no longer choose which port its parent probes or which pid it kills at boot. The parent used to adopt cells from a cell.json in the child's own directory, which the child's cell can write.
shipped production is serving it deploy cfe12e4
A child forge can no longer choose which port its parent probes or which pid it kills at boot. The parent used to adopt cells from a cell.json in the child's own directory, which the child's cell can write. Records now live in a directory the parent owns, and adoption takes the pid and the port only from the cell's supervisor.
Carried over, not copied. Pull #14938's head (3c866cdb6) lives in a fork this token cannot read either: git fetch says "not our ref" and the API has no diff route. So I rebuilt it on today's main from that pull's own description, using its names (readRecord, dropLegacyRecords, readStartedPid, readListen) and the files this issue lists. Each commit has Co-authored-by for mason.
What moved where
- Where records live (
src/spawn/cell_record.ts): records moved fromchildren/<body>/cell.jsonto<data>/cell-records/<body>.json, a directory bound into no cell.recordPath(dataDir, bodyId)throws for any body id thatvalidBodyId(disk_mount.ts) refuses.readRecordandclearRecordignore an id that is not safe.readRecords(dataDir)returns the records themselves, and drops any filed under another body's name.
- Old records: at boot,
dropLegacyRecordsdeletes eachchildren/<body>/cell.jsonwithout reading it and logs a warning for each one.src/kernel/destroy_reach.tslists it as an allowed remover, and theclearRecordentry now names the new path. - New readers (
src/spawn/supervisor.ts):readStartedPidaccepts only apid:startfile whose start time matches the running process. A bare pid is refused.readListen(ctl)reads thelistenport from the supervisor'sconfig.json.
- Adoption (
src/spawn/cell.ts):adoptuses both new readers. A record whose port is not the supervisor's is dropped beforeanswers()asks that port anything. Record writes and clears now take(dataDir, bodyId). - Reach (
src/spawn/reach.ts):startedOfreads the start time throughreadRecord.
Tests
- Three new tests in
test/cell-adopted-on-start.test.ts. I put each check back the old way and confirmed its test fails:- Forged record: a forged
cell.jsonin the child's directory points at a victim server. The file is removed and the victim gets 0 requests. - Mismatched port: a record whose port differs from the supervisor's is dropped, and the victim port gets 0 requests.
- Bare pid: a
cell.pidwith no start time names a victim. The victim's child later exits 143 from the test's own SIGTERM; under the old checkkillTreehad already removed it.
- Forged record: a forged
- One more test checks that a record path refuses
..,/and other unsafe ids. - Existing fixtures changed only for the new format: pid files carry a start time,
config.jsonholds the listen port, andtest/spawn-reach.test.tswrites its record throughwriteRecord.
Risk on the first boot after this lands: cells the old host left running are neither adopted nor signalled. Their records are in the old location, which is now deleted unread. Each child cold-starts when next asked, and its old cell ends with its supervisor. A clean restart after that still adopts: openCell writes listen into the supervisor's config and adopt writes cell.pid with its start time. docs/features/cells-outlive.md describes the new location, the checks and this upgrade step.
Not in this pull: the x-plat-* header stripping from #14938 (that is #15234), and the docs/threats/compromised-vendor.md rows, which are not among this issue's files.
Checks run: bun scripts/gate.ts --fix and bun x tsc --noEmit both pass. I ran these test files: cell-adopted-on-start, spawn-reach, cell-outlives-host, billing-never-deletes, spawn-cell, spawn-reach-door, first-ten-minutes, spawn-stopped-restart, stop-while-starting and timers-named. All pass, with 2 skipped: unix-socket suites this sandbox cannot run, which the forge's check runs. The keep_plan and estimate tools were not available in this session, so no plan was kept on the issue and no estimate was recorded.
To try it: bun test test/cell-adopted-on-start.test.ts test/spawn-reach.test.ts
🤖 Generated with Claude Code
Approved. Records move to <data>/cell-records/<body>.json behind validBodyId; legacy cell.json files are removed unread and logged; adoption takes pid and start time and the port only from the supervisor, and a mismatched port is dropped before it is asked. The three attack tests (forged record, wrong port, bare pid) assert the victim is never touched, and docs/features/cells-outlive.md says where records live and what the first boot after upgrade does. No web or terminal surface changes, README untouched, no dependency added. I did not run the suite; I read the diff. Next, two things: (1) add a test that a real startSupervisor/openCell leaves a cell.pid with a start time and a config.json listen, because the fixtures here hand-write both and a drift in the real writer would silently stop all adoption; (2) have dropLegacyRecords count what it removed and log that once, so an operator can see the upgrade boot in one line.
A child forge can no longer choose which port its parent probes or which pid it kills at boot. The parent used to adopt cells from a
cell.jsonin the child's own directory, which the child's cell can write. Records now live in a directory the parent owns, and adoption takes the pid and the port only from the cell's supervisor.Carried over, not copied. Pull #14938's head (3c866cdb6) lives in a fork this token cannot read either: git fetch says "not our ref" and the API has no diff route. So I rebuilt it on today's main from that pull's own description, using its names (
readRecord,dropLegacyRecords,readStartedPid,readListen) and the files this issue lists. Each commit hasCo-authored-byfor mason.What moved where
src/spawn/cell_record.ts): records moved fromchildren/<body>/cell.jsonto<data>/cell-records/<body>.json, a directory bound into no cell.recordPath(dataDir, bodyId)throws for any body id thatvalidBodyId(disk_mount.ts) refuses.readRecordandclearRecordignore an id that is not safe.readRecords(dataDir)returns the records themselves, and drops any filed under another body's name.dropLegacyRecordsdeletes eachchildren/<body>/cell.jsonwithout reading it and logs a warning for each one.src/kernel/destroy_reach.tslists it as an allowed remover, and theclearRecordentry now names the new path.src/spawn/supervisor.ts):readStartedPidaccepts only apid:startfile whose start time matches the running process. A bare pid is refused.readListen(ctl)reads thelistenport from the supervisor'sconfig.json.src/spawn/cell.ts):adoptuses both new readers. A record whose port is not the supervisor's is dropped beforeanswers()asks that port anything. Record writes and clears now take(dataDir, bodyId).src/spawn/reach.ts):startedOfreads the start time throughreadRecord.Tests
test/cell-adopted-on-start.test.ts. I put each check back the old way and confirmed its test fails:cell.jsonin the child's directory points at a victim server. The file is removed and the victim gets 0 requests.cell.pidwith no start time names a victim. The victim's child later exits 143 from the test's own SIGTERM; under the old checkkillTreehad already removed it...,/and other unsafe ids.config.jsonholds the listen port, andtest/spawn-reach.test.tswrites its record throughwriteRecord.Risk on the first boot after this lands: cells the old host left running are neither adopted nor signalled. Their records are in the old location, which is now deleted unread. Each child cold-starts when next asked, and its old cell ends with its supervisor. A clean restart after that still adopts:
openCellwriteslisteninto the supervisor's config andadoptwritescell.pidwith its start time.docs/features/cells-outlive.mddescribes the new location, the checks and this upgrade step.Not in this pull: the
x-plat-*header stripping from #14938 (that is #15234), and thedocs/threats/compromised-vendor.mdrows, which are not among this issue's files.Checks run:
bun scripts/gate.ts --fixandbun x tsc --noEmitboth pass. I ran these test files: cell-adopted-on-start, spawn-reach, cell-outlives-host, billing-never-deletes, spawn-cell, spawn-reach-door, first-ten-minutes, spawn-stopped-restart, stop-while-starting and timers-named. All pass, with 2 skipped: unix-socket suites this sandbox cannot run, which the forge's check runs. Thekeep_planandestimatetools were not available in this session, so no plan was kept on the issue and no estimate was recorded.To try it:
bun test test/cell-adopted-on-start.test.ts test/spawn-reach.test.ts🤖 Generated with Claude Code
Closes #15235