Repository navigation
docs(specs): draft the BOX implementation plan - #2026
mitodrummer wants to merge 5 commits into
Conversation
The order and size of the pull requests that implement BOX, beside its spec: four scripted renames first (R1-R4, box naming), then refactor pull requests that split the CLI and daemon files the work touches, then the spec's slices, with joins, open questions, existing code, totals, the critical path and risks. Drawn against spec commit 0d37c6a; it is re-run after the renames before any issue is created. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CdRDynXbYoKR6dByN13KsD
|
Important Draft PR not reviewedDraft PRs are not automatically reviewed by default.
To automatically review draft PRs, update your CodeRabbit configuration: reviews:
auto_review:
drafts: true
Comment |
| > - A **box** is the thing: its record, id, state, lifecycle, events, spec and processes. Code about the box says box: `BoxId`, `BoxRecord`, `BoxState`, `BoxSpec`, `BoxManager`, `BoxActor`, `box_runtime`. | ||
| > - **session**, **task**, **agent**, **service**, **build** and **container-build** are **Box Type** names. They name a kind of box, never the box itself. `min session` and `min task` are type-filtered forms of `min box`. | ||
| > - A **sandbox** is the operating-system isolation (namespaces, mounts, cgroups) under boxes *and* package builds. It is the `sandbox` crate. | ||
| > - A **Box Host** is the machine that hosts boxes, so no module or type in a daemon uses that name for anything else. | ||
| > - `box` is a reserved word in Rust: a module about boxes is `boxes` or `box_<noun>`, and a type is `Box<Noun>`, never a bare `Box`, which would shadow `std::boxed::Box`. | ||
| > - No code uses session or task to mean the box. Wire, on-disk, printed and environment names that say session stay only where a spec keeps them for compatibility. The Rust name says box and carries a serde rename or alias. | ||
| > - New files, modules and types about the box take box names from the start. A rename of existing names is its own PR, never mixed into a move or a feature. |
There was a problem hiding this comment.
This is great! Fantastic to see clearer naming in the code that is aligned with Arch. This will make the clankers far less confused.
…e BOX plan A task becomes a box whose entrypoint is the task. T42 adds one launcher keyed on the spec, T9 becomes one exit rule keyed on lifetime, and T43 moves min task run off the task-run exec into a task box. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CdRDynXbYoKR6dByN13KsD
… the BOX plan T44 rewrites the repository's minimal.toml files, docs and the daemon's scaffold from [session] to [sessions.default], so nothing of ours hits the exit 3 when the grace release ends. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CdRDynXbYoKR6dByN13KsD
norrietaylor
left a comment
There was a problem hiding this comment.
I had my arch expert review the plan against foundry plan rules and spec 29 at the #1697 head.
Summary:
- The headline block is stale. gominimal/arch#98 and gominimal/arch#99 are closed, so the first slice is not blocked on them.
- OQ2 (HIGH) waits on the NET epic. It needs one issue that decides it.
- T43 changes what users see, but it is marked enablement and covers no requirement. Spec 29 has BOX-015 and BOX-038 for it. The Ctrl-C change is not in the spec.
- The renames are outside the linted plan, and they conflict with open NET pull requests. Start them after the NET epic closes.
- A person cannot try slice S0. Make its join cover BCLI-001 and BCLI-003.
- The plan is older than the spec (68 requirements against 71), and the linted plan is not posted on the epic. Run it again.
| | OQ6 | LOW | How `[params]` values reach the entrypoint | Waits on **gominimal/arch#100** | T18 | | ||
| | OQ7 | LOW | `[io] exec_enabled` is still marked proposed | **Needs an issue**: whoever rules on it in the architecture | T31 | | ||
|
|
||
| **Headline:** under these states **the first slice's feature PRs cannot start**, because T1, T2 and T3 all wait on gominimal/arch#98. Since revision 2 the refactor PRs T34–T39 can run in the meantime, so V004 no longer fires. The five MEDIUM and LOW questions are the only ones that can move: |
There was a problem hiding this comment.
Must fix: this block is stale. gominimal/arch#98 and gominimal/arch#99 are closed.
Problem:
- The headline says that the feature PRs of the first slice cannot start, because T1, T2 and T3 wait on gominimal/arch#98.
- gominimal/arch#98 closed on 2026-10-06. gominimal/arch#99 also closed on 2026-10-06. Only gominimal/arch#100 is open.
- The plan rule says: a deciding issue that is already closed is a stale question, not a block.
Do this:
- Remove the headline and the two options below it.
- Remove risk 1 in §6.
- Remove the "under the defaults" wording from the critical path in §5.
There was a problem hiding this comment.
Fixed in 6b89491. The headline, its two options and the old risk 1 are gone, and §5 no longer says "under the defaults". The plan comment keeps the edges to the closed issues with closed 2026-10-06 on their lines, as the skill's rule for a closed deciding issue says, but no task waits on them in the readable plan.
|
|
||
| | # | Sev | Question (short) | State in the plan | What it holds back | | ||
| |---|---|---|---|---| | ||
| | OQ1 | MEDIUM | Stop grace duration | Waits on **gominimal/arch#98** (open) | T3, T31 | |
There was a problem hiding this comment.
Must fix: mark OQ1, OQ3, OQ4 and OQ5 as closed.
Problem:
- OQ1 and OQ5 wait on gominimal/arch#98. OQ3 also waits on gominimal/arch#98. OQ4 waits on gominimal/arch#99. Both issues are closed.
- The table still shows these questions as open, so a reader thinks that T3, T17, T18, T19 and T31 are blocked.
Do this:
- Write
closed 2026-10-06and the ruling on each closed row. - Add a checkpoint-1 question: does the spec author remove the matching NEEDS CLARIFICATION markers from spec 29?
- Keep a row open only if its deciding issue is still open. Today that is only gominimal/arch#100.
There was a problem hiding this comment.
Fixed in 6b89491. OQ1, OQ3, OQ4 and OQ5 are marked closed 2026-10-06 with each ruling, and so are two new ones from spec 29: OQ8 (arch#112) and OQ11 (arch#113). §3 ends with a note for the spec author to remove those six markers from spec 29.
One finding came out of the rulings: arch#99 puts egress_deny_subnets into the §6.3.2 projection, while BOX-071 projects it nowhere. §3 and risk 10 flag it, and the spec needs that change before T26.
| | # | Sev | Question (short) | State in the plan | What it holds back | | ||
| |---|---|---|---|---| | ||
| | OQ1 | MEDIUM | Stop grace duration | Waits on **gominimal/arch#98** (open) | T3, T31 | | ||
| | OQ2 | **HIGH** | NET's "exists", "destroyed" and "removed" against the retained states | Waits on **gominimal/minimal#1437** (NET epic, open). GWI on #1419 also has to rule on "removed". | T8 | |
There was a problem hiding this comment.
Must fix: OQ2 waits on an epic, not on a decision.
Problem:
- OQ2 is HIGH. It waits on Box networking — preview by name, bounded egress, and secure reach across hosts #1437, which is the NET epic.
- An epic does not decide a question. The NET epic is close to its end, and it can close without an answer to OQ2.
- A HIGH question must have a deciding issue. Without one, S1 (T8) has no clear point at which it can start.
Do this:
- Open one issue that asks the OQ2 question: what "exists", "destroyed" and "removed" mean in NET against the retained box states.
- Point OQ2 and T8 at that issue, not at the epic.
- Update line 217 and the S1 entry in §5 to match.
There was a problem hiding this comment.
Done. I opened #2041 to decide OQ2, asking NET and GWI to confirm the spec's reading. OQ2, T8, the NET join row and the S1 lane in §5 now point at it instead of the epic.
| |---|---|---|---|---|---| | ||
| | T42 | One launcher starts every box's entrypoint from its stored spec: the argv, the PTY flag, cwd and env. The spec carries `execution.exec`, `lifetime` and `pty_enabled`, from the `[session]` table (login shell, PTY) or the task (its command line, no PTY). No branch in the box runtime reads the type. | (enablement) | mfile spec.rs; minimald session_host/launcher.rs, session_host.rs, session.rs, session_host/mock.rs, session_host/tests.rs | L, 380+240 | Yes: a session's spec names the shell it starts today | | ||
| | T9 | One exit rule, read from `lifetime`: an `until_complete` box whose entrypoint returns ends as exited and keeps its record, with or without a client. Idleness and client loss never stop a box. A session whose shell exits ends the same way, which **retires the keep/save/delete prompt**. | BOX-015, 038 | minimald session_host.rs, session.rs, sessions.rs, session/tests.rs, session_host/tests.rs | L, 360+240 | **No.** The shell-exit prompt is gone and the record is kept | | ||
| | T43 | `min task run` puts the task's command line, bound args, cwd and env into the spec, creates a `task` box, streams its output and returns its exit code. `end_run_box` and the `owns_box` branch go. An older client's `TaskRun` keeps working for one release through the exit rule. | (enablement) | minimal task.rs, cmd/boxes/create.rs; minimald exec/run.rs, exec/process.rs; minimald-rpc exec.rs | L, 420+260 | **No.** Task boxes are retained, Ctrl-C and client loss no longer end a run | |
There was a problem hiding this comment.
Must fix: T43 changes what users see, but it covers no requirement.
Problem:
- T43 is marked enablement. The last column says it is not invisible to users: task boxes are retained, and Ctrl-C and client loss no longer end a run.
- Enablement is only for a task that unblocks a lane, a gated path or a missing piece of the tree. A change that users see is not enablement.
- Spec 29 has requirements for this change: BOX-015 (never stop for idleness or client loss), BOX-038 (an
until_completebox ends when its entrypoint returns, and the record is kept), themin task runuser story, and the session text that BOX-038 retires the shell-exit prompt. - Spec 29 does not say that Ctrl-C no longer ends a run. The plan adds that behaviour.
Do this:
- Make T43 cover BOX-015 and BOX-038, and write a proof that a person can try with
min task run. - For Ctrl-C, get a line in the spec, or keep the behaviour of today.
- Move the T43 proof into the S2 join, so that the slice shows the change.
There was a problem hiding this comment.
Done in 6b89491. T43 is now kind: task and covers BOX-015 and BOX-038, with a proof a person can try: run a task that sleeps and exits 3, close the terminal mid-run, and see min box show report exit code 3. The S2 join T11 gains a CLI test that does the same.
On Ctrl-C: Ctrl-C during min task run now stops the box. The client sends a stop, which BOX-013 already defines (SIGTERM, then SIGKILL, record kept as stopped), so the spec needs no new line. Only a lost client no longer ends a run, which is BOX-015.
|
|
||
| | PR | What it adds | Covers | Files | Size / est | Keeps behaviour? | | ||
| |---|---|---|---|---|---| | ||
| | T42 | One launcher starts every box's entrypoint from its stored spec: the argv, the PTY flag, cwd and env. The spec carries `execution.exec`, `lifetime` and `pty_enabled`, from the `[session]` table (login shell, PTY) or the task (its command line, no PTY). No branch in the box runtime reads the type. | (enablement) | mfile spec.rs; minimald session_host/launcher.rs, session_host.rs, session.rs, session_host/mock.rs, session_host/tests.rs | L, 380+240 | Yes: a session's spec names the shell it starts today | |
There was a problem hiding this comment.
Should fix: say what T42 unblocks.
Problem:
- T42 is marked enablement and covers no requirement. That is correct only if it unblocks other tasks.
- The row does not say which tasks it unblocks. Line 194 says that T9 and T43 consume
BoxLaunch.
Do this:
- In the T42 row, name T9 and T43 as the tasks it unblocks.
- If T43 changes to cover BOX-015 and BOX-038, check that T42 still changes no behaviour that users see.
There was a problem hiding this comment.
Done. The T42 row now says it unblocks T9, T10, T11 and T43, which consume its BoxLaunch. With T43 covering the user-facing change, T42 keeps behaviour: a session's spec names the shell it starts today, and tasks keep today's path until T43.
| |---|---|---|---|---|---| | ||
| | T33 | Every operation works over file-mode trust and there is no `identity.sock`. A `store` secret passes through, and a `broker` secret fails with exit 5 and `gatehouse_unenrolled_node`. | BOX-081, 140, 141 | minimald sessions.rs, rpc.rs | L, 200+340 | Yes | | ||
|
|
||
| **Coverage:** all 68 requirements are in exactly one task. Nothing is parked and nothing is marked already built. |
There was a problem hiding this comment.
Should fix: the plan is older than the spec.
Problem:
- This line says "all 68 requirements". Spec 29 now has 71 BOX requirements.
- Line 6 surveys
mainat173f033. The PR body says that the plan must run again against spec0d37c6a. - The linted plan is not posted on the epic, so nobody can check the result "exit 0, 22 advisory".
Do this:
- Run the plan again against the current spec head and the current
main. - Run
plan-lint, and post the result as one comment on the epic. - Update the count of requirements and the survey commit.
There was a problem hiding this comment.
Re-run in 6b89491 against the spec at 28d8723d (71 requirements) and main at 2aa1a7f6: plan-lint exit 0, 0 blocking, 27 advisory. All 71 requirements are covered: BOX-162 joined T2, BOX-164 joined T10, BOX-163 is the new T46, and the renamed spec tests are matched.
Posting on the epic waits until the spec merges and the paths are re-mapped after the renames, per the owner's plan.
| | T37 | **Moves inline tests out** of the daemon's `rpc.rs` (3,900 test lines), `server.rs`, `exec.rs` and minimald-rpc's `lib.rs` into sibling `tests.rs` files, the layout `session_host/` already uses. | 4 files + 4 × tests.rs *new* | S, 60+120 | **Yes**, pure move | | ||
| | T38 | **Splits the box actor** (`box_actor.rs`, today `minimald/src/session.rs`: 5,300 lines of code, most of it one `impl`). The groups become further `impl BoxActor` blocks in `box_actor/{naming, ports, setup, attach, host, launcher, handle}.rs`. | box_actor.rs + 7 *new* | M, 240+60 | **Yes**, pure move. Target: session.rs under 1,000 lines | | ||
| | T39 | **Splits the box runtime** (`box_runtime.rs`, today `session_host.rs`: 6,200 lines) into `box_runtime/{binding, handle, hooks, backend, enforcement, launcher, mock}.rs`. | box_runtime.rs + 7 *new* | | ||
| | T41 | **Splits the box manager** (`box_manager.rs`, today the daemon's `sessions.rs`). Its 1,430-line test module moves to `box_manager/tests.rs`, and the handle API (`BoxManagerHandle`, its weak form, `BoxControl`) moves to `box_manager/handle.rs`. Fifteen BOX tasks change this file, and after T41 they see only the actor. | box_manager.rs + 2 *new* | S, 80+60 | **Yes**, pure move | M, 240+60 | **Yes**, pure move. Target: under 1,600 lines | |
There was a problem hiding this comment.
Minor: the table is broken here.
Problem:
- The T39 row (line 93) has no size columns.
- The T41 row has cells from the T39 row in it.
Do this: fix the two rows so that each row has all its columns.
There was a problem hiding this comment.
Fixed. T39 and T41 each have their own complete row.
|
|
||
| ### S2: Tasks leave exited boxes (the session+task unification) | ||
|
|
||
| **T40 comes first in this slice: it splits the daemon's exec dispatch.** It is a pure move, so it keeps behaviour. It changes `exec.rs` plus 4 new files, size M (160+60), and it waits on T37. `exec.rs` keeps the `Exec`/`Process` traits and the dispatch entry. The rest moves to `exec/{process, bridge, run, git}.rs`. Eight BOX tasks change `exec.rs`, and after T40 each one touches one concern's file. T43 and the join T11 wait on it. |
There was a problem hiding this comment.
Minor: T40 is only in a paragraph.
Problem: every other task is a table row. T40 is only in this paragraph, so a reader can miss its files, size and dependencies.
Do this: add T40 as a row in the S2 table.
There was a problem hiding this comment.
Fixed. T40 is a row in the S2 table, with its files, size and the tasks that wait on it.
| | T35 | **Breaks activation into named steps.** The 1,065-line `activate_session` becomes a short function calling resolve spec → register with the VM host → create → configure and finalize → announce or attach. Each step is testable alone and gets its own tracing span. | minimal cmd/boxes/create.rs | M, 320+120 | **Yes**: same printed lines, same state | | ||
| | T36 | **Box names inside the CLI.** The operations become `create_box`, `attach_box`, `stop_box`, `remove_box` and so on. Each `min session` handler maps its arguments to the box operation, and that thin layer is what BCLI's aliases later replace. `min task run` calls the same operations. | the 8 cmd/boxes files, cmd/session.rs, task.rs | L, 420+120 | **Yes**: printed text, flags and wire names unchanged | | ||
| | T37 | **Moves inline tests out** of the daemon's `rpc.rs` (3,900 test lines), `server.rs`, `exec.rs` and minimald-rpc's `lib.rs` into sibling `tests.rs` files, the layout `session_host/` already uses. | 4 files + 4 × tests.rs *new* | S, 60+120 | **Yes**, pure move | | ||
| | T38 | **Splits the box actor** (`box_actor.rs`, today `minimald/src/session.rs`: 5,300 lines of code, most of it one `impl`). The groups become further `impl BoxActor` blocks in `box_actor/{naming, ports, setup, attach, host, launcher, handle}.rs`. | box_actor.rs + 7 *new* | M, 240+60 | **Yes**, pure move. Target: session.rs under 1,000 lines | |
There was a problem hiding this comment.
Minor: the T38 target uses the old file name.
Problem: the target says "session.rs under 1,000 lines". After R4, that file is box_actor.rs.
Do this: use the name the file has after the renames.
There was a problem hiding this comment.
Fixed. The target now reads box_actor.rs under 1,000 lines, and the T39 target says box_runtime.rs.
| By size that is 22 L, 13 M and 8 S. | ||
|
|
||
| - **Rough total:** about 19,800 lines, roughly 10,650 code and 9,150 tests. The refactor PRs add about 2,350 of those, and the unification about 1,250. At ~1/2/3 days per S/M/L PR that is about 100 PR-days. The four renames add about 4 more days, landed back to back. | ||
| - **How a pure move is sized:** a move's estimate counts only the lines that change (`mod` and `use` lines, visibility), not the moved lines. `git diff --color-moved` shows a reviewer the moved blocks as moved, so they cost little to review. T34 moves about 5,800 lines, T37 about 9,000, T38 about 4,300, T39 about 4,600, T40 about 2,300 and T41 about 1,800. |
There was a problem hiding this comment.
Minor: this sizing rule makes large moves look small.
Problem:
- A move's estimate counts only the lines that change. That rule is the planner's own, not the plan format's.
- T37 moves about 9,000 lines. A reviewer must still read the whole diff to check that the move changes nothing.
Do this: give each move two numbers, the lines that change and the lines that move, and use the larger number for the size.
There was a problem hiding this comment.
Done. Each move row shows both numbers, lines changed and lines moved, and a review size taken from the larger, so all six moves are L. The day count and the critical path in §5 use the review size: 119 PR-days and about 47 working days. The plan comment's linted estimate stays at the lines changed, because every move would otherwise pass the 900-line ceiling and have to be split, which would multiply the conflicts.
Re-run against the spec at 28d8723 and main at 2aa1a7f: BOX-162, BOX-163 and BOX-164 are covered, and the renamed spec tests match. Closed architecture issues mark their questions closed, OQ2 waits on #2041, T43 covers BOX-015 and BOX-038 with Ctrl-C stopping the box, T7 carries min box list and show, the SessionId merge becomes T45, the renames wait for NET's open pull requests, and move PRs are sized for review by the lines they move. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CdRDynXbYoKR6dByN13KsD
Spec 29 re-pinned to arch 823f45f and turned eight open questions into citations, so the plan drops its edges to the closed arch issues and keeps three questions. T46 adds the <name>-<n> fresh-instance rule, a new T47 plans the implicit default session entry (BOX-165), T27's golden vectors gain that case, and T26's proof follows the projected deny field. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CdRDynXbYoKR6dByN13KsD
|
Closing this draft. The plan was only ever a review vehicle; it is now drawn against spec 29 at cd2e309 (revision 5) and stays on the |
Draft of the implementation plan for BOX (#1697, gominimal/inbox#731), added as
docs/specs/29-spec-box-local-first/plan.mdbeside the spec. This PR is stacked on #1697's branch, so the diff is only the plan.What the plan says
sandbox2→sandbox, plus the box naming rule inAGENTS.md.sessions→boxes.sessions.rs→box_manager,session.rs→box_actor,session_host.rs→box_runtime.Session*types →Box*, with no change on the wire. Merging the three id types into oneBoxIdis a planned task (T45), and R5 renames its callers.cmd/session.rsintocmd/boxes/, break up activation, and split the daemon's actor, runtime, manager and exec files. Each names the BOX tasks that wait on it.min box listandmin box show, so a person can try it.lifetimeends it, so a new Box Type needs no code path of its own.Status: draft
cd2e3090andmainat2aa1a7f6. The plan comment lints withplan-lintagainst spec 29: 0 blocking findings, 27 advisory. Its file paths are today's; one pass re-maps them after R1–R4, before any issue is created.just lint-prosestill reports alerts on the new file, mostly requirement IDs and identifiers read as misspellings, passive voice and semicolons. They will be fixed before this leaves draft.refactor/sandbox-crate-nameand isn't pushed yet. It waits for NET's open pull requests.🤖 Generated with Claude Code
https://claude.ai/code/session_01CdRDynXbYoKR6dByN13KsD