Repository navigation
T8 — Wait on a box and return its exit code - #3195
Conversation
`min box wait <box>` reads the box's record until it ends. It returns the stored exit code, 128 plus the stored signal, or 137 for a stopped record with neither. A box that its own timeout ended, and a wait whose --timeout runs out, end with 124 and the machine-mode `timeout` error. The --timeout wait leaves the box running.
|
Important Review skippedBot user detected. To trigger a single review, invoke the
|
|
Approved: every review thread resolved at @agent-137 resolved the last thread, which releases the approval this review had withheld. Nothing to do. |
There was a problem hiding this comment.
arch-review: CONDITIONS · 5 conditions · the full ruling
The wait's own --timeout answers machine-mode code = "timeout". Since arch #166, architecture.md lines 370 and 506 give it wait_timeout, naming the box by its id. Make the change in C1 and C2, and amend BCLI-013 in the spec to match in C3. The PR body states the run-verb half of BCLI-014 as undone but names no issue. File it in C4, and file the design's success machine output for min box wait in C5. The exit-code reading conforms to the design.
Ruled at ce37cd1 against gominimal/arch@949521619eea by claude-opus-5-5.
|
/revise Head C1: the wait's own timeout carries
C2: the C3: the spec 28 amendment is in #3194. Do not edit the spec here. C4 and C5: residuals. Add to the PR body's gaps:
Reply on each arch thread with the commit, or with the issue that answers it. |
…box-and-return-its-exit-code
A box that its own timeout ended keeps code timeout. A min box wait --timeout that runs out now answers wait_timeout, and its message and hint name the box by the id the wait resolved. Both keep exit 124.
…box-and-return-its-exit-code
|
Round 1 of 10 on a /revise note, pushed as
Verify Converted to a draft: something above needs a person before review. Review threads the coder judged:
Notes from the agent: Revise round 1, commit 7343639. C1: BoxTimedOut has a |
There was a problem hiding this comment.
APPROVE withheld: 5 unresolved threads — minimal-arch[bot] crates/minimal/src/cmd/boxes/wait.rs, minimal-arch[bot] crates/minimal/src/cmd/boxes/wait.rs, minimal-arch[bot] crates/minimal/src/main.rs, minimal-arch[bot] crates/minimal/src/tests.rs:11434, minimal-arch[bot] crates/minimal/src/tests.rs:11494.
minimal-review — advisory review
Verdict COMMENT — No findings.
Panel: 1 of 3 personas ran (security); did not complete: correctness, supply-chain.
agent-137
left a comment
There was a problem hiding this comment.
Review on Karl's behalf, at 1f683ec42. This is a comment, not an approval. Nothing was built for it: every point comes from reading the code, and each finding says how it was checked.
- Head:
1f683ec4. This is revise commit73436396(C1/C2 from the agent-137 /revise) plus a main merge. All reviews so far are on the older headce37cd1d. - CI at head: still running when fetched.
tests,unit,clippy,artifacts,native-daemon-e2e,minimald-root-integration,zonedanddogfoodwere IN_PROGRESS. fmt, commitlint, cargo-deny and minimal-check were green. arch-review and minimal-review had not run on this head yet. - Existing reviews:
- minimal-arch: CHANGES_REQUESTED at ce37cd1 with 5 conditions.
- minimal-review: "no findings", with only 2 of 3 personas run (correctness missing).
- CodeRabbit: skipped ("Bot user detected"). There is no CodeRabbit review.
- agent-137: /revise for C1–C5.
Plan task: covers BCLI-013 and BCLI-014.
Requirement check
| Req | Implemented | Test | Notes |
|---|---|---|---|
| BCLI-013 main: stored exit_code, or 128+signal | yes. wait.rs:83-104 reads exit_code/signal/reason from the record via ShowBox, not from the exited event (the body says so) |
box_wait_returns_retained_exit_code_or_128_plus_signal (tests.rs) |
ok |
| BCLI-013 sub: orphaned stop gives 137 | yes | box_wait_orphaned_stopped_record_returns_137 |
ok |
BCLI-013 sub: --timeout gives 124 and the box keeps running |
yes, with code = "wait_timeout" and the box id (C1/C2 done in 7343639) |
box_wait_timeout_flag_returns_124_box_runs_on, against a harness daemon |
the code follows arch. The spec is stale (see below) |
BCLI-014: a box timeout gives 124 / timeout from task run, box run and wait |
wait half only. The run verbs are not done (task.rs is outside the layers) | run_verbs_and_wait_timeout_return_124_with_code_timeout, in two places (main.rs and tests.rs). Both test the mapping only |
No minimald code sets EndReason::Timeout yet (BOX-037), so no real box reaches this path. The residual is #3198 |
Arch #166 vs spec vs PR
- Arch L370/L506 say a wait that hits its own
--timeoutreturnscode = "wait_timeout"and names each box that has not ended. The PR follows this. Spec 28 is out of date: - Spec gap against arch: arch L485/L506 give
min box wait <box>…with several boxes, an all mode (the first non-zero exit by end time) and--any. Machine output lists how each box ended. Spec 28 has only a single<box>, and its non-goals cover only--parent. Running several boxes without--parentis not nesting, so spec 28 has no requirement for it. #3199 covers only the machine output. This is a spec gap, not a PR defect.
Should-fix
- PR body: residuals C3–C5 are missing. The body as fetched does not mention #3194, #3198 or #3199, and its notes section ends in "…[truncated]". Without them, BCLI-014's partial delivery has no linked issue. Verified: checked the fetched body for each issue number. Still open from agent-137 /revise (C3–C5), and the runner says it cannot edit the body.
wait.rs:50: the message joins two facts with a semicolon. "Stopped waiting after 30s; web (0190…) is still running." AGENTS.md says "Give each fact its own sentence". The agent flagged this in the PR notes and shipped it as written because the plan'sdiagnostics:line dictates the text. Fix the plan text and the code together, for example "Stopped waiting after 30s. The box web () has not ended." The test that pins the text isbox_wait_timeout_flag_returns_124_box_runs_on, and both string asserts in it would need updating. Verified: read the code and the pinned test.
Nit
wait.rs:94and:50: "is still running" can be false.wait_exitreturnsNonefor every state that is not stopped or exited, includingpendingandmaterializing(BoxState, boxes/src/lib.rs:958). A wait on a box still composing prints "is still running". Arch L506 says "naming each box that has not ended, whatever its state". "Has not ended" is what the code can prove. Also, the test passes the states"created"and"starting", whichBoxStatedoes not have. Verified: read the code.wait.rs:50: the id prints twice when the user typed it.min box wait 0190…prints "0190… (0190…)". Verified: read the code.- main.rs:224: the hint never shows in text mode. Text mode prints only
error: {e:#}. A person at a terminal never sees "Runmin box wait <id>… ormin box stop <id>". Only machine mode carries the hint. This matches whatBoxExecTimedOutalready does, so it may be intended. Verified: readanswer_failure. - attach.rs:679 (existing text): the hint names a flag that does not exist yet. It says "or its exit code with min box wait {address} --exec {exec_id}." Once this PR lands,
min box waitexists but has no--exec, which belongs to BCLI-057, a different task. Clap will reject the command that hint names. This is outside this PR's diff, but this PR is what makes the verb real. Verified:git grep "box wait"at the head.
Verdict: needs changes, all minor: the body residuals and one message's wording. The code conforms to arch #166 at the new head. arch-review needs to re-rule on 1f683ec, and CI must go green.
|
/revise Head 1. One fact per sentence in the timeout message. 2. The PR body links its residuals.
Reply on any open thread that these answer. |
There was a problem hiding this comment.
arch-review: CONDITIONS · 2 conditions · the full ruling
min box wait conforms to the design. It returns the stored code, 128 plus the signal, 137 for an orphaned stop, and 124 with wait_timeout (architecture.md lines 370 and 506). Spec 28 BCLI-013 line 123 still says code = "timeout" for a wait timeout. Amend the spec, not the code (C1). The run-verb half of BCLI-014 is not done. min task run and min box run emit no machine-mode timeout error, and no issue owns that work. File the issue and name it in the PR body, or make the edit in task.rs (C2). Also correct the PR body: since #3154, the run path returns 124.
Ruled at e217577 against gominimal/arch@9e2ff817adba by claude-opus-5-5.
|
Round 2 of 10 on a /revise note, pushed as
Verify Converted to a draft: something above needs a person before review.
Notes from the agent: ## Residuals
Revise round 2. Item 1: the timeout message in |
|
Undrafted by the BCLI babysitter. The draft comes only from the runtime's own test lines, which fail with |
There was a problem hiding this comment.
arch-review: CONDITIONS · 3 conditions · the full ruling
min box wait conforms to the design. The exit codes, the wait_timeout error and the running box after --timeout match line 370 and line 506. BCLI-014 is not complete. min task run and min box run exit 124 on a box timeout, but they do not emit the machine-mode code = "timeout" that line 370 requires. The run path already reads the timeout reason through ended_at_timeout, so C1 is a small edit in task.rs. C2 makes the run-verb test exercise a run verb. C3 amends the spec, which still says timeout for a wait timeout where the design says wait_timeout.
Ruled at fa60462 against gominimal/arch@9e2ff817adba by claude-opus-5-5.
|
/revise Head 1. C1: a run that ends at the box's own timeout answers 2. C2: the test drives the run verbs.
3. C3 is the spec, in #3194. Change no spec text here. 4. PR body. Reply on the arch threads with the commit. Change nothing else. |
…box-and-return-its-exit-code
min task run and min box run now return BoxTimedOut when the box's own timeout ended it, so they exit 124 and machine mode answers code = "timeout" (BCLI-014). Human mode prints the timeout line once. An entrypoint that exits 124 by itself keeps TaskExit(124).
|
Round 4 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:
Notes from the agent: Revise round 4. The directive asked for a change in crates/minimal/src/task.rs, which is outside layers:. The new pub fn task::run_outcome(exit, timed_out, entry) holds the decision, and run_entry's box-run path calls it in place of exit_outcome. BoxTimedOut gains a printed flag, set by already_printed(). answer_failure in main.rs relays 124 with no |
There was a problem hiding this comment.
minimal-review — approval withheld
Verdict COMMENT — APPROVE withheld: 14 unresolved threads — minimal-arch[bot] crates/minimal/src/cmd/boxes/wait.rs, minimal-arch[bot] crates/minimal/src/cmd/boxes/wait.rs, minimal-arch[bot] crates/minimal/src/main.rs, minimal-arch[bot] crates/minimal/src/tests.rs:11435, minimal-arch[bot] crates/minimal/src/tests.rs, …. No findings.
Panel: 3 of 3 personas ran (correctness, security, supply-chain).
bryan-minimal
left a comment
There was a problem hiding this comment.
Read at 2fb0db8. The verb does what BCLI-013 asks: wait_exit reads the record the daemon stored, an exit code is that code, a signal is 128 plus it, a stopped record with neither is 137 (BOX-154), and a timeout reason is the shared BoxTimedOut with 124. The --timeout leg returns 124 with code = "wait_timeout" and the resolved box id in the message and the hint, which is what the architecture's lines 370 and 506 want. 2fb0db8 closes the run-verb half of BCLI-014 too: run_outcome turns a 124 that ended_at_timeout confirmed into BoxTimedOut::ended, marked as already printed, so min task run and min box run exit 124 with the timeout object in machine mode and no second line in human mode, while an entrypoint's own 124 stays TaskExit(124). The Remove arm cannot hide a timeout: it fires only when the entrypoint never started (a pending or materializing record), so a box that ran past its timeout is always in the Keep arm where the record is read.
Findings
-
Medium: the PR body contradicts the newest commit. The Proof says "the run verbs do not return 124 for a box timeout yet" and the notes say
task.rswas not changed; 2fb0db8 changes it and the test's second half drivesrun_outcomethroughended_at_timeoutfor both thetimeoutand theexitrecord. Please rewrite the Proof and drop the notes, and namewait_timeoutbesidetimeoutthere. Most of minimal-arch's C1 and C2 threads were written against the earlier heads and are answered by the code now; a reply on each saying which commit answers it would let the next reader stop re-deriving that. -
Low: the wait-timeout message claims the box is running.
BoxTimedOut::waitedsays "{target} ({id}) is still running", butwait_exitreturnsNonefor every state that is notstoppedorexited, so apendingormaterializingbox gets the same message. #3194's BCLI-013 wording is "names each box that has not ended, whatever its state". "has not ended" is both true and the spec's phrase. minimal-foundry's open thread says the same. -
Low: spec 28 on main still says the wait timeout is
code = "timeout". BCLI-013's sub-bullet at line 122 and the NEEDS CLARIFICATION at line 604 are amended in #3194 towait_timeoutand the two-code split. This PR implements #3194's text, not main's, which is right, but the body should say it depends on #3194 for the spec line so that the linter's verify entries and the code agree once both land.
Checked and fine
ended_at_timeoutreads the record only for a 124, and the test pins both halves: atimeoutrecord givesBoxTimedOutwithis_printed, anexitrecord with code 124 givesTaskExit(124).answer_failureskips theerror:line only for a printedBoxTimedOut; the machine-mode path still answers the object, andfailure_exit_codekeeps 124 for both codes.--timeoutgoes throughmfile::duration::parse_timeout_secs, which refuses zero, so the deadline arithmetic never sees an empty duration; the poll shortens to the remaining time so the deadline is honoured to within the poll.- A box removed between the address resolving and the first
ShowBoxis aNotFoundrefusal with its exit code, not a hang. - The harness tests stop a real box and compare the wait's code with the record the daemon wrote, so the two readings cannot drift apart silently.
Verdict
Approve with nits. Nothing blocks the code; the body needs the rewrite in finding 1 before merge so the Proof matches what ships, and finding 2 is a one-word change. With this in, #3185's min box wait hint names a verb that exists.
|
Undrafted by the BCLI babysitter after round 4. The draft comes only from |
|
/revise Head The wait-timeout message says "has not ended", not "is still running".
Reply on the thread with the commit. |
…box-and-return-its-exit-code
The wait also stops on a pending or materializing box, which is not running yet. The message now says the box has not ended.
…box-and-return-its-exit-code
There was a problem hiding this comment.
APPROVE withheld: 1 unresolved thread — minimal-foundry[bot] crates/minimal/src/cmd/boxes/wait.rs.
minimal-review — advisory review
Verdict COMMENT — No findings.
Panel: 2 of 3 personas ran (correctness, supply-chain); did not complete: security.
|
Round 5 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:
Notes from the agent: Revise round 5: commit c6a6437 changes the wait-timeout message in BoxTimedOut::waited from "is still running" to "has not ended", as the /revise note and thread PRRT_kwDOPdfcxM61ePfZ (comment 4518772598) ask. The verdict on that thread changes from invalid to valid. The doc comment on the same function now says "before the box ended". Both pins in box_wait_timeout_flag_returns_124_box_runs_on are updated. No other file pins the text. cargo-nextest is not installed on this box, so I ran each test line with cargo test -p minimal --lib and the same test name. The task's diagnostics line still quotes the old wording (" is still running"). The plan text needs the same update. |
There was a problem hiding this comment.
arch-review: PASS_WITH_CONDITIONS · 2 conditions · the full ruling
The compare closes the code gaps. min task run and min box run now return 124 with code = "timeout" when the box's own timeout ends it (lines 370 and 494). The wait-timeout message now says the box has not ended (line 506). Spec 28 BCLI-013 still says that a wait timeout answers code = "timeout". The design says wait_timeout, so amend the spec as C1 says. The PR body still says that the run verbs do not return 124 yet. Remove that claim as C2 says.
Outside the diff
docs/specs/28-spec-box-cli/28-spec-box-cli.md:123: C1 · This bullet sayscode = "timeout"for a wait timeout. The design 124 row (line 370) andmin box wait(line 506) saycode = "wait_timeout". The code follows the design. Change the spec towait_timeout, and remove the arch#160 clarification at line 604.
Ruled at 99bc266 against gominimal/arch@15b603e6afb8 by claude-opus-5-5.
|
Undrafted by the BCLI babysitter after round 5, under the owner's standing rules: |
There was a problem hiding this comment.
minimal-review — approved
Verdict APPROVE — every review thread is resolved; @agent-137 closed the last one. The review of 99bc2661c8a9 withheld this approval on the threads open then. Posted as a comment, as the review itself was; the check and the label carry it.
* feat(minimal): add min box start and min session start Both verbs create a box from an entry of the project. With no entry, min box start picks the default entry of any type, else the only one, and min session start picks the default session entry, else the only one. The implicit default entry counts. A session box attaches this terminal unless --detach is given. Off a terminal, without --detach, the start exits 2 before it creates anything. A task entry starts detached, with its stdin closed, and one hint names min box run, min box logs and min box wait. --name sets the box's [box] name, and --new asks for a fresh instance. A held name exits 2, names the holder and names --new and --name. * test(minimal): list the start name test's requests in the create inventory * fix(minimal): refuse --name for a task entry in min box start The run path names a task box itself and takes no name, so the start dropped --name without a word. It now refuses the flag with exit 2 before it creates anything. --new already holds for a task box: its generated name is never held. * docs(minimal): link the start interims to gominimal#3196 and gominimal#3197 Name the issues that track the task-entry --name refusal and the unsupported-type refusal, and correct the run-path comment: a task-entry start is always a fresh instance named <entry>-<n>. * fix(minimal): read the typed session entry's egress on start min session start <entry> reads the egress of that entry, not of default. A typed entry needs no default to start. Link the entry body residual of stamp_session_spec_as to gominimal#3204. * fix(minimal): print a port in use the same on min box start Both start verbs share start_refusal, so the port-in-use rewrite moves there. min box start now names the port and its holder, as min session start does. * docs(minimal): name the --name run gap and the logs/wait merge order BCLI-069 gives --name to min box run and min task run too. Say where that waits: RunEntry takes no box name yet. The unattached start hint names min box logs and min box wait, which gominimal#3184 and gominimal#3195 add, so this change merges after both. * fix(minimal): refuse unresolved types and [boxes] tasks on start start_candidates refuses an entry whose type has no built-in root (gominimal#3140) before the session filter, so a project Box Type never gets the implicit default. plan_start refuses a [boxes] task entry (gominimal#3213). StartEntryRefusal::exit_code gives 4 for an entry the start does not find. run_entry returns the box id, so the detached start names it in its hint and records it on the span. * docs(minimal): document min session start Give its arguments, how it picks the entry, and its refusals with their exit codes: 4 for an entry it does not find, 2 for the others. * fix(minimal): refuse unresolved types only when start counts entries Move the TypeUnresolved refusal after the explicit-entry lookups in pick_box_start_entry and pick_session_start_entry, in the order that pick_session_entry uses. A typed project entry or an explicit default entry now starts beside an entry of a project Box Type. * fix(minimal): escape entry names in every start refusal NotSession, UnsupportedType, StartNeedsTerminal and the entry lists in Several and Unknown printed names from minimal.toml raw. Pass each name through printable, as the sibling arms do, and pin it in a test. * fix(minimal): refuse a typed session entry other than default The box of a typed session entry gets the entry's name in its spec, but its body still comes from the [session] table. Until gominimal#3204 applies the entry's own body, both start verbs refuse such a start with exit 2, before anything is created. A typed default and a bare start of the only session entry still start. The tests now plan the two starts that 43b4a42 broke: a bare start beside an unresolved project type, and min box start build. * test(minimal): start the only session entry bare in the off-tty test A typed dev is now refused until gominimal#3204, so the off-terminal test reaches the terminal refusal through a bare start of the sole entry. * fix(minimal): escape the names in the held-name start refusal StartNameHeld printed the entry, the held name and the holder's name raw. A name with control characters can no longer move the cursor. * chore(minimal): drop the start hint's merge-order comment min box wait is on main now, so the comment's claim that this branch lacks it is false. * fix(minimal): set run network fields in box start of a task The merge of main added network and egress to RunEntry. The task start of min box start takes no network flags, so it passes none. --------- Co-authored-by: minimal-foundry[bot] <327719912+minimal-foundry[bot]@users.noreply.github.com>
T8 — Wait on a box and return its exit code
slice: S2
kind: task
covers: BCLI-013, BCLI-014
size: M
est: 200 code, 240 tests
executor: agent
difficulty: routine
model: standard
diagnostics: when
min box wait --timeoutruns out, it prints "Stopped waiting after ; is still running." on stderr and exits 124, pinned by box_wait_timeout_flag_returns_124_box_runs_onobservability: the command's existing tracing span records the verb, the box id it resolved and the outcome
layers:
- client:
- crates/minimal/src/cli.rs: the verb's arguments and help in the one command model
- crates/minimal/src/cmd/mod.rs: dispatches the verb
- crates/minimal/src/cmd/boxes/wait.rs (new):
min box waitreads the stored exit, 128 plus the signal, 137 for an orphaned stop, and 124 at a timeout- crates/minimal/src/cmd/boxes.rs: declares the wait module
- crates/minimal/src/main.rs:
failure_exit_codemaps this verb's refusals to their exit codes- crates/minimal/src/tests.rs: the in-process minimald test harness gains this layer's tests
test: cargo nextest run -p minimal box_wait_returns_retained_exit_code_or_128_plus_signal
test: cargo nextest run -p minimal box_wait_orphaned_stopped_record_returns_137
test: cargo nextest run -p minimal box_wait_timeout_flag_returns_124_box_runs_on
test: cargo nextest run -p minimal run_verbs_and_wait_timeout_return_124_with_code_timeout
produces:
- crates/minimal/src/cmd/boxes/wait.rs
consumes: none
proof:
min box waitreturns a box's exit code, and a box ended by its own timeout returns 124 from the run and wait commands.depends on:
- blocked by #2892
arch#160 closed 2026-11-09 when gominimal/arch#166 merged (9495216). The runtime treats an arch edge as open, so the owner had it removed on 2026-11-09.
Residuals
code = "wait_timeout"naming each box that has not ended, and drops the arch#160 NEEDS CLARIFICATION (arch ruling 1095 C1).min box wait -o json.Proof
min box wait <box>now waits until the box ends and exits with the box's stored exit code. It exits with 128 plus the signal for a box that a signal stopped, and with 137 for a stopped record that has neither. A box that its own timeout ended makesmin box waitexit 124 with the machine-modetimeouterror.--timeout <d>stops the wait with 124 and the machine-modewait_timeouterror naming the box id, and leaves the box running.min task runandmin box runalso exit 124 with the machine-modetimeouterror when the box's own timeout ends it (task::run_outcome). A run whose entrypoint itself exits 124 keepsTaskExit(124).Notes (rewritten by the BCLI babysitter for arch ruling 1095 C2, owner rule 2026-11-10; the round-0 notes predated rounds 2–5): BCLI-013 and both halves of BCLI-014 are delivered. The run verbs live in
crates/minimal/src/task.rs, outside the task's layers; arch condition C1 of ruling 1088 required the edit. #3154 addedExitEnding::Timeoutin minimald, andended_at_timeoutreads it. Printed text: the wait-timeout message is "Stopped waiting after . () has not ended.", and the hint is "Runmin box wait <id>to wait again, ormin box stop <id>to stop it.". prints as30sfor whole seconds and in milliseconds otherwise. The wait re-reads the record every 250 ms through ShowBox, which carries the stored exit code, signal and reason.run_verbs_and_wait_timeout_return_124_with_code_timeoutdrivestask::run_outcomefor both run-verb cases and the wait mapping. cargo-nextest is missing from the runtime's sandbox, so CI runs the tests.Tests
cargo nextest run -p minimal box_wait_returns_retained_exit_code_or_128_plus_signalcargo nextest run -p minimal box_wait_orphaned_stopped_record_returns_137cargo nextest run -p minimal box_wait_timeout_flag_returns_124_box_runs_oncargo nextest run -p minimal run_verbs_and_wait_timeout_return_124_with_code_timeoutVerify
min task run agent-verifyexited 101 under rustc 1.99.0, which the repository does not pin (1.99.1 in rust-toolchain.toml); the PR is not a draft on that alone — CI, which honours the pin, is the gate.Closes #2896
Closes #3198