Repository navigation
T3 — Stop a box and keep its record - #2733
Conversation
The request names the box and whether the stop is forced. The response carries the exit code or the signal that ended the entrypoint, as the record stores it. Refs BOX-013.
The actor's StopBox message signals every process in the box's PID namespace, waits the grace period, and kills what is left. A forced stop kills at once. The record is set to stopped with the signal or exit code that ended the entrypoint, and an exited event records it. One box.stop span covers the stop. Refs BOX-013.
The manager refuses to stop a box that is not running and hands the stop to the box's actor with a 10 s grace. The StopBox RPC answers the exit code or signal that ended the entrypoint. A stopped record, its spec, events and parent stay readable until the box is reaped. stop_orphaned_running_records sets a running record with no process left to stopped with no signal. It is not called at daemon start yet: no actor hosts a stopped box until #2393. Refs BOX-013, BOX-018, BOX-154.
|
Important Review skippedBot user detected. To trigger a single review, invoke the
|
|
Reviewed: 1 finding, none blocking at Address the comments on the diff. Clobber: none seen. |
There was a problem hiding this comment.
arch-review: CONDITIONS · 1 condition · the full ruling
The stop conforms in its order, its grace period and its record fields. One stored ending is wrong. stop_box_processes() reads the portable code 125 as a signal. An entrypoint that exits 125 by itself then gets a signal and no exit code. Line 495 of architecture.md says the record stores the entrypoint's exit_code where one exists. C1 makes the stop use hakoniwa's ExitReason::exit_code and adds a test for it. The BOX-154 call at daemon start stays open as residual #2393.
Ruled at 62c29d8 against gominimal/arch@109541a48c31 by claude-opus-5-5.
|
Round 1 of 10 on the runtime's review findings: the coder changed nothing. Revise round 1. The one review thread is invalid, so this round changes no code and runs no tests. The test: lines passed at the earlier round, and the branch head is unchanged by this round. Review threads the coder judged:
|
|
/revise Arch-review C1 on 62c29d8: tell an exit from a signal by the reaped reason, not by exit code 125. hakoniwa reports 125 both for a container ended by a signal and for an entrypoint that exits 125 itself, so
Leave the PR body's Run the plan's test lines plus |
…-and-keep-its-record
hakoniwa reports 125 both for a signalled container and for an entrypoint that exits 125 itself. The host loop now returns the reaped ExitReason beside its code, and a stop records ExitedFirst when the reason carries an exit status of its own.
There was a problem hiding this comment.
arch-review: PASS_WITH_CONDITIONS · 1 condition · the full ruling
The stop now takes the entrypoint's exit status from the reaped reason, not from the code 125. An entrypoint that exits 125 itself keeps its exit code, as line 495 requires. The stop signals every process in the box's PID namespace, with a 10 s grace and a force path. The stopped record and its events stay readable until reaped. One item stays open: nothing calls the BOX-154 restart flip at daemon start. C1 tracks it under #2393, and the PR can merge with C1 open.
Ruled at 443090e against gominimal/arch@109541a48c31 by claude-opus-5-5.
|
Round 2 of 10 on a /revise note, pushed as
Verify Outside the task's
Converted to a draft: something above needs a person before review. Review threads the coder judged:
A stopped session keeps its record and its ending. An entrypoint that exits 125 inside the grace period now has exit_code 125 and no signal on its record, and its exited event carries no signal key. A box that a signal ended still records that signal. Notes from the agent: C1: the host loop now ends in Host::run, which returns HostExit { code, reason: Option }. Host::spawn and its JoinHandle type use it. Host::mainloop is now a #[cfg(test)] wrapper that returns only the code, so crates/minimald/src/box_runtime/tests.rs did not change. HostExit lives in box_runtime.rs (the accepted out-of-layer file), not in backend.rs. stop_box_processes decides on ExitReason::exit_code: Some(status) gives ExitedFirst, None gives Signalled. code_means_signalled is removed. For the Signalled signal, I kept the signal that the entrypoint ended after. This is the last signal the stop sent before the entrypoint ended. In both existing tests it is equal to the last signal sent. It differs only when the entrypoint ended on SIGTERM and stray processes needed SIGKILL. Then the record keeps SIGTERM. The new test checks the record and the event through the same calls that stop_box_inner makes: Record::set_state(Stopped(ending)) on a record that the daemon created, and stopped_event_data(ending). It does not go through a full daemon stop, because the mock launcher's script (mock.rs, out of layers) cannot trap TERM and exit 125. The PR body's Residuals section is not mine to edit, and I did not touch it. |
|
/revise One fix on 443090e, from minimal-review (crates/minimald/src/box_runtime/enforcement.rs:834, If the container supervisor has already exited and been reaped, reading Leave the PR body's |
…-and-keep-its-record
A supervisor whose pid namespace cannot be read already exited and was reaped. Its pid can belong to an unrelated process, so the stop now treats the box as having no processes instead of walking from that pid.
|
Round 3 of 10 on a /revise note, pushed as
Verify Outside the task's
Converted to a draft: something above needs a person before review. Review threads the coder judged:
A stopped session keeps its record and ending signal. A stop of a box whose container supervisor was already reaped now signals no process, so a reused pid is never hit. Notes from the agent: Revise round 3: BoxProcesses now has three scopes (Namespace, Tree, Gone). A namespace read that fails for the supervisor or for the daemon itself gives Gone: pids() is empty, signal() reaches nothing, and a debug log line says the supervisor was already reaped. New test of_container_on_a_reaped_supervisor_signals_nothing covers a reaped child pid and a pid that cannot exist. The PR body Residuals section is untouched (the runner owns the body). just clippy-strict was not run. |
The stop tests slept 200 ms and assumed /bin/sh had set its trap by then. On a loaded runner a SIGTERM can reach the shell first, and the box ends on SIGTERM. The stand-in box now prints a ready line after it sets the trap and starts its first child.
|
Round 4 of 10 on a failed check suite, pushed as
Verify Outside the task's
Converted to a draft: something above needs a person before review. A stopped session keeps its record and its ending signal: after a stop, the record reads stopped with the signal that ended the entrypoint, and the exited event carries reason stopped and that signal. Notes from the agent: The directive's CI excerpts do not name the failing test: the tests job excerpt shows only passing lines and cleanup, and ci-linux-native-success only aggregates it. Before the change, the whole minimald suite (1178 tests), minimald-rpc (76), and minimal, minimal-client and minvmd (1556) all passed on this box, and 15 stress iterations of the stop tests under CPU load passed. I found one real race in this task's tests and fixed it: three stop tests slept 200 ms and assumed /bin/sh had installed its trap. On a loaded runner, SIGTERM can reach the shell before the trap, and the box ends on SIGTERM instead of SIGKILL or exit 125. A new helper spawn_stand_in_box now waits for a ready line that the shell prints after it sets the trap and starts its first child. After the fix, 20 stress iterations under CPU load passed. If CI still fails, the failing test name from the full job log is necessary, because this box does not reproduce it. |
There was a problem hiding this comment.
arch-review: PASS_WITH_CONDITIONS · 1 condition · the full ruling
The compare since 443090e conforms. The stop now signals nothing when it cannot read the supervisor's PID namespace. Before, it could signal a reused pid. That is fail-closed, and the host kill still ends the box (architecture.md line 495). The test changes keep every assertion. C1 is the open item from the baseline: BoxManager::init does not call the BOX-154 restart flip yet. It is filed as #2393.
Ruled at ea5bad3 against gominimal/arch@109541a48c31 by claude-opus-5-5.
…-and-keep-its-record
|
/revise Two fixes on 08c6b46. The first is a regression this branch introduced. 1. 2. minimal-review MEDIUM, crates/minimald/src/box_actor/host.rs:1654 Leave the PR body's |
A stop now sets the record to stopped before anything else can fail. A failed record write keeps the ending on the actor and returns the error, and the actor keeps hosting the box, so a retried stop can write the record. A failed exited-event write is logged, and the stop still answers with its ending.
|
Revise round 4 ran against |
|
Round 6 of 10 on a /revise note, pushed as
Verify Outside the task's
Converted to a draft: something above needs a person before review. Review threads the coder judged:
A stopped session keeps its record and ending signal. A stop now writes the stopped record first. If the exited event write fails, the record still reads stopped, and the stop still answers with its ending. If the record write fails, the actor stays, so the box keeps an actor and a retried stop writes the record. Notes from the agent: Item 1 (a_trickle_reader_fed_one_byte_chunks_is_still_ended): the guess about the guard in BoxProcesses::of_container is wrong, so I did not change the guard. Only the stop path in box_actor/host.rs and the stop tests call of_container. The trickle test is pure tokio: it spawns no process and sends no signal. The exec sources on this branch are identical to origin/main. The test is timing-sensitive. Its stall window counts only the time the pump waits at the bound, so the time it takes depends on how the feeder's and the reader's 50 ms sleeps line up. It passed in the full local minimald run (2.3 s of its 5 s window). In a 30-run stress loop (cargo nextest run -p minimald a_trickle_reader_fed --stress-count 30 --no-fail-fast, exit codes not captured) it failed 2 of 30 on this branch and also 2 of 30 on origin/main, with no extra load. With 4 busy loops on 4 cores it failed sooner (1 of 3). So this is a flake in main's test from #2625. It is not a regression from d461c0e or 08c6b46. A fix belongs in crates/minimald/src/exec.rs or exec/tests.rs, which are outside this task's layers, and the directive forbids a change to the window. I recommend a separate issue for it. Item 2: done in bc304a8. The stopped record is written first, and a failed write returns its error. The ending stays on the actor (new field unrecorded_stop), and the StopBox arm then continues and does not end the actor. A retried stop passes the manager's running check, finds that ending, and writes it. A failed exited-event write or object open is logged as a warning, and the stop returns Ok. The new test stop_with_a_failing_event_write_still_records_stop…[truncated] |
There was a problem hiding this comment.
arch-review: CONDITIONS · 1 condition · the full ruling
The new retry path in stop_box_inner can skip the stop sequence. After a failed stopped write, the record still reads running, so an exec can launch a new host. The retried stop then drops that host without SIGTERM, grace or SIGKILL, and records the earlier ending. architecture.md line 495 says a stop signals every process in the box and stores the signal that ended it. Apply C1. Then the change conforms again, as it did on 08c6b46f.
Ruled at 787e34d against gominimal/arch@109541a48c31 by claude-opus-5-5.
A stop that ends the processes and cannot set the record to stopped keeps the box hosted. launch_host now refuses until a retried stop writes the record, and a retried stop signals any host it finds. A stop queued behind another answers with the record's ending. Document that SIGTERM reaches a PID namespace init only through a handler.
…-and-keep-its-record
There was a problem hiding this comment.
arch-review: PASS_WITH_CONDITIONS · 1 condition · the full ruling
The compare fixes the points of the last ruling. A launch is now refused while a stop's record is unwritten, and a queued stop answers with the recorded ending. One gap remains. A --force stop that arrives during a graceful stop waits up to the grace period, and the new comment in box_actor.rs states that as intended. Design line 495 says --force kills at once. Make the change in C1, or file it as a residual before the merge.
Ruled at 0eecd2c against gominimal/arch@109541a48c31 by claude-opus-5-5.
|
Round 7 of 10 on the runtime's review findings, pushed as
Verify Outside the task's
Converted to a draft: something above needs a person before review. Review threads the coder judged:
A stopped session keeps its record, set to stopped, with the signal that ended it. When the record cannot be written, the session starts no new processes until a retried stop writes that record. Notes from the agent: Revise round 7. The launch refusal reuses AttachError::LaunchRecordUnwritable, because attach.rs is outside the layers. It prints: "starting the session failed: the session's saved state could not be updated: a stop ended this session's processes, and its stopped state is not saved yet". No CLI command stops a box yet, so the message names no next step. Thread 3 was not checked on a real box. This box runs only the mock launcher. The kernel rule in pid_namespaces(7) confirms the premise, so the change documents the behaviour. BOX-013 asks for exactly that order (SIGTERM, grace, SIGKILL). The fix also restores a doc comment that an earlier round left on the wrong test in box_actor/tests.rs. |
|
/revise Two fixes on 0eecd2c. 1. arch-review C1, crates/minimald/src/box_actor.rs:1183: 2. minimal-review MEDIUM, crates/minimald/src/box_actor.rs:1193: mark the name stopped even when the stop fails after the kill. When Leave the PR body's |
…-and-keep-its-record
BoxHandle::stop_box(force: true) sets a shared force flag before it queues its message. A graceful stop in its grace period reads the flag and sends SIGKILL at once. The StopBox arm also marks the name stopped when the record write fails after the kill (NET-128 fail-closed).
|
Round 8 of 10 on a /revise note, pushed as
Verify Outside the task's
Converted to a draft: something above needs a person before review. Review threads the coder judged:
A stopped session keeps its record and ending signal. A forced stop now ends a graceful stop's grace period at once with SIGKILL. A stop whose record write fails no longer leaves the box's name answering. Notes from the agent: Out of layers: crates/minimald/src/box_actor/handle.rs. The force flag must live on BoxHandle and WeakBoxHandle, because the handle sets it while the actor is busy in the grace loop. It is a new fourth tuple field, StopForce = Arc, and the actor reads it through weak_self. The actor clears the flag after a stop has signalled the box, so a later stop starts without it. The new test stop_forced_during_a_graceful_stop_kills_at_once drives stop_box_processes with the shared flag directly. It does not go through the daemon, because the mock shell ends on SIGTERM and so never waits out a grace period. The new test stop_box_with_an_unwritable_record_still_marks_name_stopped fails when the fix is removed (checked). I did not run just clippy-strict. The PR body's Residuals section is not changed. |
There was a problem hiding this comment.
arch-review: PASS_WITH_CONDITIONS · 1 condition · the full ruling
The new commit makes --force end a graceful stop's grace period at once, as architecture.md line 495 requires. A failed record write now also marks the box name stopped, so the name fails closed. BOX-013 and BOX-018 conform. BOX-154 is still not called at daemon start. That work is filed as #2393, and C1 records it. You can merge with C1 open.
Ruled at b4f415e against gominimal/arch@109541a48c31 by claude-opus-5-5.
|
Round 9 of 10 on the runtime's review findings: the coder changed nothing. every commit this round put on the branch above b4f415e is a merge of the base branch, so it carries no work of its own Review threads the coder judged:
|
mitodrummer
left a comment
There was a problem hiding this comment.
Approved at b4f415e. A stop sends SIGTERM, waits the grace period, then SIGKILL, and --force cuts the grace short through the shared flag. It tells an exit from a signal by the reaped ExitReason, not by code 125. It signals only a supervisor whose parent is the daemon, so a reused pid is never signalled. The stopped record is written first, and a failed write keeps the actor, refuses launches and still marks the name stopped. A cleanup destroy keeps ended records. BOX-154's switch-on at daemon start is residual #2393 (T6).
T3 — Stop a box and keep its record
slice: S0
kind: task
covers: BOX-013, BOX-018, BOX-154
size: L
est: 420 code, 360 tests
executor: agent
difficulty: needs care
model: strongest
diagnostics: daemon log names each stop step
observability: one span per stop, with ending signal
layers:
- actor:
- crates/minimald/src/box_actor.rs: stop message
- crates/minimald/src/box_actor/host.rs: TERM, grace, KILL
- crates/minimald/src/box_runtime/enforcement.rs: signals the whole cgroup
- crates/minimald/src/box_actor/tests.rs: tests
test: cargo nextest run -p minimald stop_sends_term_then_kill_and_records_exited_stopped_with_signal
test: cargo nextest run -p minimald stop_force_kills_at_once
- manager:
- crates/minimald/src/box_manager.rs: stop dispatch; orphan to stopped
- crates/minimald/src/box_manager/tests.rs: tests
- crates/minimald/src/rpc.rs: stop handler
test: cargo nextest run -p minimald restart_sets_orphaned_running_record_stopped_without_signal
test: cargo nextest run -p minimald stopped_box_record_readable_until_reaped
- wire:
- crates/minimald-rpc/src/lib.rs: stop request
test: cargo nextest run -p minimald-rpc stop_box_request_round_trips
produces: none
consumes:
- crates/boxes/src/core/record.rs
- crates/boxes/src/events.rs
proof: A stopped session keeps its record and ending signal.
depends on:
- blocked by #2387
- blocked by #2389
- blocked by #2634
Proof
A client can now send the StopBox RPC for a running session. The daemon sends SIGTERM to every process in the box, waits 10 s, and sends SIGKILL to what is left. With force it sends SIGKILL at once. The record then reads stopped, with the signal or exit code that ended the entrypoint, and an exited event with reason stopped carries the same value. The record, its spec, events and parent stay readable through GetSessionRecord and the events read until the session is destroyed. The proof does not cover a daemon restart: the restart flip of BOX-154 exists and is tested, but nothing calls it at daemon start yet (see notes).
Notes from the agent: 1) BOX-154 is not wired at daemon start. stop_orphaned_running_records (box_manager.rs) sets each running record to stopped with no signal and writes the exited event. The test calls it over a restarted store. I did not call it from BoxManager::init. Box processes die with the daemon (PR_SET_PDEATHSIG), so at start the flip would match every running record. BoxActor::run refuses a stopped record until #2393 (T6, BOX-025). Every session would then fail to attach after a daemon restart, and the restart-resume NET tests (NET-129, NET-138, resume_* in box_manager and box_actor tests) would break. The function has an expect(dead_code) that names #2393. A person must decide whether this flip ships with T6 or here. It skips ends_with_run records, which the resume still destroys (inbox#731).
2) enforcement.rs does not signal a cgroup. Only host-address boxes have a classifier leaf, and the UDP 443 cohort can move several boxes into one shared blocked leaf, so a cgroup signal could kill another box. BoxProcesses signals every live process in the PID namespace that the container supervisor creates for its children. That covers the entrypoint, its descendants, setsid processes and execs. When that namespace is the daemon's own (the test mock launcher), it signals the supervisor's process tree. A process in a nested PID namespa…[truncated]
Tests
cargo nextest run -p minimald stop_sends_term_then_kill_and_records_exited_stopped_with_signalcargo nextest run -p minimald stop_force_kills_at_oncecargo nextest run -p minimald restart_sets_orphaned_running_record_stopped_without_signalcargo nextest run -p minimald stopped_box_record_readable_until_reapedcargo nextest run -p minimald-rpc stop_box_request_round_tripsVerify
min task run agent-verifypassed ([tasks.verify]).Out of scope
These files are outside the task's
layers:, so this PR is a draft:crates/minimald/src/box_actor/kind.rscrates/minimald/src/box_runtime.rscrates/minimald/src/box_runtime/handle.rsResiduals
stop_orphaned_running_recordsat daemon start (BOX-154). It waits until resume can host a stopped box, or every session would fail to attach after a restart. The maintainer deferred it to T6.Closes #2390
Maintainer accepted the out-of-layer edits to
box_actor/kind.rs,box_runtime.rsandbox_runtime/handle.rs(theStopBoxname and the container pid a stop signals from), 2026-10-28. Undrafted.Maintainer also accepted
box_actor/handle.rs(theStopForceflag for--force), 2026-10-29.