cargo-hauler 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.8.3
+
+### Patch Changes
+
+- 711f6ea: Identity, coverage, and batch/fold now refuse to share when the forwarded caller environment differs, so two `cargo test`/`check` runs that differ only in `OUT` (or any other variable cargo will see) no longer coalesce onto one result (#222). Duration estimates still key on the compile surface — including when the variable arrives via `env OUT=…` — so one-off output paths do not cold-start EWMA. The PATH shim stays in the foreground for non-TTY callers instead of returning exit 75 and running later against torn-down state; `CARGO_HAULER_SHIM_BACKGROUND=1` restores auto-background for scripts that consume tickets (#223).
+
+## 0.8.2
+
+### Patch Changes
+
+- 7490839: Internal: the implementation behind the Agent Bundle entrypoints now lives
+  under `src/internal/<owner>/` (contracts, cargo, daemon/{runtime,broker,
+  scheduling,reporting}, storage, client, operations, host-hooks,
+  integrations/kache, platform, shim, ui/{documents,dashboard,shared}, util)
+  instead of `daemon/`, `lib/`, `hooks/`, and friends; `tests/` is grouped by
+  what a test executes (unit, integration, packaging, acceptance). A move-only
+  change: no route, executable, protocol, or scheduling behaviour changed.
+  `docs/architecture.md` is the ownership map and walkthrough.
+
 ## 0.8.1
 
 ### Patch Changes

package/README.md

@@ -378,16 +378,20 @@ too, along with any log whose row is gone. `hauler exec --bg -- cargo …` and
 `hauler_request` return the ticket immediately. A synchronous request also switches to background mode when a
 *measured* estimate — EWMA history or kache priors, never the cold-start
 default — exceeds the host's shell-tool cap (nine minutes for Claude, ten for
-Codex, fourteen for Cursor; the PATH shim uses `CARGO_HAULER_HOST` when it is
-exported, otherwise the Claude cap). The estimate that is compared is the
-whole wait: the work queued ahead in the lane plus the job's own runtime,
-which the queued line reports as `wait ~Ns, run ~Ns`. That conversion exits
-`75` (`EX_TEMPFAIL`) with the ticket on stderr, so `cargo build && …` chains
-and scripts cannot mistake "submitted" for "built"; explicit `--bg` keeps exit
-`0`. When the caller's stdout is not a terminal (`cargo test > out.log`), the
-notice adds that the redirect receives no output and to read it with
-`hauler result cc-N --full`. Failed runs feed the estimate history too, so a broken build is not
-re-estimated cold on every retry.
+Codex, fourteen for Cursor). The PATH shim (`--host shim`) is cargo to its
+caller: a non-TTY invocation (a script, `spawnSync`, `make`) waits for the
+ticket to finish and returns cargo's exit code. An interactive shim (stdout
+is a TTY) still auto-backgrounds on the cap, using `CARGO_HAULER_HOST` when
+it is exported, otherwise the Claude cap; `CARGO_HAULER_SHIM_BACKGROUND=1`
+restores that for scripts that consume tickets themselves. The estimate that
+is compared is the whole wait: the work queued ahead in the lane plus the
+job's own runtime, which the queued line reports as `wait ~Ns, run ~Ns`. That
+conversion exits `75` (`EX_TEMPFAIL`) with the ticket on stderr, so
+`cargo build && …` chains and scripts cannot mistake "submitted" for "built";
+explicit `--bg` keeps exit `0`. When the caller's stdout is not a terminal
+(`cargo test > out.log`), the notice adds that the redirect receives no
+output and to read it with `hauler result cc-N --full`. Failed runs feed the
+estimate history too, so a broken build is not re-estimated cold on every retry.
 
 A foreground `hauler exec` that receives SIGINT or SIGTERM (Ctrl-C, or a
 `timeout N …` wrapper) asks the daemon to kill its ticket, waits for the
@@ -674,7 +678,8 @@ Per-host notes and hook timeouts are in [docs/install.md](docs/install.md).
 | `CARGO_HAULER_LEDGER_MAX_ROWS` | `50000` | Total ledger rows beyond which the oldest finished rows are deleted when the daemon starts; `0` disables the row cap. Pruned rows take their `tickets/<ticket>.log` files with them. |
 | `CARGO_HAULER_TICKET_LOG_MAX_BYTES` | `67108864` (64 MiB) | Bytes of a leader run's combined output written to `<state dir>/tickets/<ticket>.log` before the log stops with one truncation line; `0` writes no ticket logs (`hauler result` then has only the tail). |
 | `CARGO_HAULER_LOG_LEVEL` | `Info` | Daemon log level. |
-| `CARGO_HAULER_HOST`, `CARGO_HAULER_SESSION` | Unset | Default `--host` and `--session` attribution for `hauler exec`; the PATH shim also borrows `CARGO_HAULER_HOST`'s shell cap for auto-background. |
+| `CARGO_HAULER_HOST`, `CARGO_HAULER_SESSION` | Unset | Default `--host` and `--session` attribution for `hauler exec`; the PATH shim also borrows `CARGO_HAULER_HOST`'s shell cap when auto-background is allowed. |
+| `CARGO_HAULER_SHIM_BACKGROUND` | Unset | `1` / `true` / `on` / `yes` lets a non-TTY PATH shim auto-background over the host cap (exit 75). Without it, a shim that is not a TTY waits for cargo's exit. |
 
 A numeric value that does not parse or falls outside its range is reported
 as a warning (daemon log, or stderr for hand-run commands) and the default
@@ -787,7 +792,6 @@ argv parser, or string-concatenated Markdown; the `src/` tree is the app.
 src/
   layout.tsx                    the hauler shell around every rendered route
   providers/hauler-daemon.ts    request-scoped daemon configuration
-  components/                   typed components over pure view-models
   mcp/hauler/tools/*.tsx        hauler_status, _dashboard, _log, _last, _await, _result, _request, _kill
   mcp/hauler/tools/*.cli.ts     each tool's `hauler <command>` projection (flags, positionals)
   mcp/hauler/apps/dashboard.tsx the MCP App (ui://cargo-hauler/dashboard.html)
@@ -796,9 +800,26 @@ src/
   events/tool/{before,after}.tsx    the shell hook routes, gated by *.preflight.ts
   skills/cargo-hauler/SKILL.md, skills/hauler-dashboard/SKILL.tsx
   scripts/hauler.ts             the `hauler` process entry hooks rewrite cargo to
-  daemon/, client/, hooks/, shim/, lib/   the broker and its libraries
+  internal/                     the implementation the entrypoints import, by owner
+    contracts/                  wire protocol, tool schemas, wire version
+    cargo/                      argv, intent, workspace, topology, execution/
+    daemon/                     composition (main, config), runtime/, broker/, scheduling/, reporting/
+    storage/                    the SQLite ledger and per-ticket output logs
+    client/                     socket clients: control, exec, tickets, ensure-daemon
+    operations/                 what the routes call: tickets, status, inspection
+    host-hooks/                 the shell/session hook handlers and their small RPC client
+    integrations/kache/         kache status and store pressure
+    platform/                   state and socket paths, private-file policy, executable location
+    shim/                       the PATH shim installer
+    ui/documents/, ui/dashboard/, ui/shared/   agent documents, the browser App, shared formatters
+    util/                       guards, ids, text, ANSI
 ```
 
+Everything above `internal/` is discovered by the framework's conventions;
+everything under it is ordinary imported code. [docs/architecture.md](docs/architecture.md)
+is the ownership map and walks the three main paths (submitting cargo, reading
+status, processing a shell hook) file by file.
+
 #### The shell (`src/layout.tsx`)
 
 Every rendered route — MCP tool, CLI command, rendered script — composes
@@ -826,7 +847,7 @@ addition: each re-exports a `preflight` (`before.preflight.ts`,
 `hooks/event-route-tool-before.<host>.mjs`, a few hundred KB with no React,
 Flight worker, or Effect — and runs before the rendered route
 (`*.execute.mjs`) is loaded. The gate decides on the raw command
-(`src/hooks/tokens.ts`; `session-ping.ts` for the one bounded completion ping
+(`src/internal/host-hooks/tokens.ts`; `session-ping.ts` for the one bounded completion ping
 after a tool ran): `continue` for the shell calls that name neither cargo nor
 hauler, `execute` for the rest. Both routes declare `providers: []`, so
 neither mounts the daemon-config provider; the rendered route calls
@@ -843,7 +864,7 @@ socket, and ledger paths); active health and status I/O belongs to the operation
 that needs it. Routes read the config through `requestDaemonConfig(context)`,
 and tests inject a fixture through the harness `context.providers` seam.
 
-#### Components (`src/components/`)
+#### Components (`src/internal/ui/documents/`)
 
 Components render view-models and nothing else. The models are pure functions
 in `view-models.ts`, so the MCP document, the CLI Markdown, and a test
@@ -871,7 +892,7 @@ assertion share one derivation.
 same operation render the same document with different command spellings
 (`surface.ts`).
 
-#### Streaming (`src/components/streaming.tsx`)
+#### Streaming (`src/internal/ui/documents/streaming.tsx`)
 
 `hauler_await` and `hauler_log` are progressive documents. Each is a
 valueless `Agent.Result` container around one `Suspense` boundary:
@@ -944,7 +965,7 @@ with the wait split by cause: *lane-bound* (a same-lane leader was still
 compiling — before its `Finished` line or exit), *permit-bound* (every
 admission permit was held and no same-lane compile was to blame), and *other*
 (admission holds, `--after` prerequisites, scheduling latency). The
-classification is a pure sweep over ledger rows (`src/daemon/wait-split.ts`)
+classification is a pure sweep over ledger rows (`src/internal/daemon/reporting/wait-split.ts`)
 run once per status refresh against the daemon's current permit count, which
 the tile states; runs admitted under an earlier cap are classified against
 today's. With `buildFinishedAtMs` on the row, the by-command split adds
@@ -957,12 +978,19 @@ the lane time the execution-phase hand-back released.
 pnpm run check   # validate + build + typecheck + Effect diagnostics + rstest + route tests
 ```
 
+`tests/` is grouped by what a test executes: `unit/<subsystem>/` is scoped to
+one owner under `src/internal/`; `integration/` runs a real broker
+in-process through `tests/support/harness.ts`; `packaging/` reads the built
+`artifact/` or spawns the package entries; `acceptance/` drives real `cargo`
+against the workspaces under `evals/fixtures/`; `route-unit/` and
+`browser-app/` are the framework-level suites below.
+
 `tests/route-unit/` renders the app through the framework compiler with no
 artifact build, at the harness proof levels:
 
 | Level | Suite | What it proves |
 | --- | --- | --- |
-| route-unit | `routes`, `layout`, `streaming`, `events` | documents, shell metadata, Suspense fallbacks and settled values, lineage attribution, event decisions (the shell routes' preflight gates are unit-tested in `tests/event-preflight.test.ts` and against their compiled entries in `tests/hooks-simulate.test.ts`) |
+| route-unit | `routes`, `layout`, `streaming`, `events` | documents, shell metadata, Suspense fallbacks and settled values, lineage attribution, event decisions (the shell routes' preflight gates are unit-tested in `tests/integration/event-preflight.test.ts` and against their compiled entries in `tests/integration/hooks-simulate.test.ts`) |
 | cli-dispatch | `cli-dispatch`, `layout` | argv through the routed CLI shell; Markdown wrapped by the shell, `--json` bare |
 | script-dispatch | `script-dispatch` | the `hauler` entry through its `main` envelope as its own process |
 | mcp-in-memory | `mcp-surface`, `layout` | tool names, `outputSchema`, the dashboard resource link, `_meta.hauler`, and a live fixture broker over the in-memory transport |
@@ -971,7 +999,7 @@ artifact build, at the harness proof levels:
 | workbench-surface | `workbench-surface` | what `agent-bundle dev` would show: catalog, provider, lifecycles per host, counts |
 
 Daemon-backed cases run a real broker in-process with a fake `cargo`
-(`tests/harness.ts`) and reach it either through the `haulerDaemon` provider
+(`tests/support/harness.ts`) and reach it either through the `haulerDaemon` provider
 seam or through `CARGO_HAULER_STATE_DIR`.
 
 ### Development

package/dist/.claude-plugin/marketplace.json

@@ -1 +1 @@
-{"description":"Coalesce, schedule, and stream cargo so concurrent agent sessions share compiles instead of fighting locks.","name":"cargo-hauler-marketplace","owner":{"name":"cargo-hauler"},"plugins":[{"description":"Coalesce, schedule, and stream cargo so concurrent agent sessions share compiles instead of fighting locks.","keywords":["cargo","rust","agent","mcp","claude-code","codex","cursor","build-orchestration"],"license":"MIT","name":"cargo-hauler","repository":"https://github.com/ScriptedAlchemy/cargo-hauler","source":"./","version":"0.8.1"}]}
+{"description":"Coalesce, schedule, and stream cargo so concurrent agent sessions share compiles instead of fighting locks.","name":"cargo-hauler-marketplace","owner":{"name":"cargo-hauler"},"plugins":[{"description":"Coalesce, schedule, and stream cargo so concurrent agent sessions share compiles instead of fighting locks.","keywords":["cargo","rust","agent","mcp","claude-code","codex","cursor","build-orchestration"],"license":"MIT","name":"cargo-hauler","repository":"https://github.com/ScriptedAlchemy/cargo-hauler","source":"./","version":"0.8.3"}]}

package/dist/.claude-plugin/plugin.json

@@ -1 +1 @@
-{"author":{"name":"cargo-hauler"},"description":"Coalesce, schedule, and stream cargo so concurrent agent sessions share compiles instead of fighting locks.","name":"cargo-hauler","version":"0.8.1"}
+{"author":{"name":"cargo-hauler"},"description":"Coalesce, schedule, and stream cargo so concurrent agent sessions share compiles instead of fighting locks.","name":"cargo-hauler","version":"0.8.3"}

package/dist/.codex-plugin/plugin.json

@@ -1 +1 @@
-{"author":{"name":"cargo-hauler"},"description":"Coalesce, schedule, and stream cargo so concurrent agent sessions share compiles instead of fighting locks.","hooks":"./.codex-plugin/hooks.json","interface":{"capabilities":["mcp","hooks","skills"],"category":"Productivity","defaultPrompt":["Help me use cargo-hauler."],"developerName":"cargo-hauler","displayName":"cargo-hauler","longDescription":"Coalesce, schedule, and stream cargo so concurrent agent sessions share compiles instead of fighting locks.","shortDescription":"Coalesce, schedule, and stream cargo so concurrent agent sessions share compiles instead of fighting locks."},"keywords":["cargo","rust","agent","mcp","claude-code","codex","cursor","build-orchestration"],"license":"MIT","mcpServers":"./.codex-plugin/mcp.json","name":"cargo-hauler","repository":"https://github.com/ScriptedAlchemy/cargo-hauler","skills":"./skills/","version":"0.8.1"}
+{"author":{"name":"cargo-hauler"},"description":"Coalesce, schedule, and stream cargo so concurrent agent sessions share compiles instead of fighting locks.","hooks":"./.codex-plugin/hooks.json","interface":{"capabilities":["mcp","hooks","skills"],"category":"Productivity","defaultPrompt":["Help me use cargo-hauler."],"developerName":"cargo-hauler","displayName":"cargo-hauler","longDescription":"Coalesce, schedule, and stream cargo so concurrent agent sessions share compiles instead of fighting locks.","shortDescription":"Coalesce, schedule, and stream cargo so concurrent agent sessions share compiles instead of fighting locks."},"keywords":["cargo","rust","agent","mcp","claude-code","codex","cursor","build-orchestration"],"license":"MIT","mcpServers":"./.codex-plugin/mcp.json","name":"cargo-hauler","repository":"https://github.com/ScriptedAlchemy/cargo-hauler","skills":"./skills/","version":"0.8.3"}

package/dist/.cursor-plugin/plugin.json

@@ -1 +1 @@
-{"description":"Coalesce, schedule, and stream cargo so concurrent agent sessions share compiles instead of fighting locks.","displayName":"cargo-hauler","hooks":"./.cursor-plugin/hooks.json","keywords":["cargo","rust","agent","mcp","claude-code","codex","cursor","build-orchestration"],"license":"MIT","mcpServers":"./.cursor-plugin/mcp.json","name":"cargo-hauler","repository":"https://github.com/ScriptedAlchemy/cargo-hauler","skills":"./skills/","version":"0.8.1"}
+{"description":"Coalesce, schedule, and stream cargo so concurrent agent sessions share compiles instead of fighting locks.","displayName":"cargo-hauler","hooks":"./.cursor-plugin/hooks.json","keywords":["cargo","rust","agent","mcp","claude-code","codex","cursor","build-orchestration"],"license":"MIT","mcpServers":"./.cursor-plugin/mcp.json","name":"cargo-hauler","repository":"https://github.com/ScriptedAlchemy/cargo-hauler","skills":"./skills/","version":"0.8.3"}

package/dist/AGENTS.md

@@ -11,14 +11,15 @@
   diagnostics, `rstest`, the route-unit suite, and browser App tests. Run it
   before claiming a change is done.
 - The plugin surface is an agent-bundle application: `src/layout.tsx` (the
-  shell), `src/providers/hauler-daemon.ts` (daemon connection), `src/components`
-  (typed components over `view-models.ts`), `src/mcp/hauler/tools` and
+  shell), `src/providers/hauler-daemon.ts` (daemon connection),
+  `src/internal/ui/documents` (typed components over `view-models.ts`), `src/mcp/hauler/tools` and
   `src/mcp/hauler/apps` (MCP; each tool's `<tool>.cli.ts` is its `hauler`
   command), `src/events` (hook routes; `tool/before.preflight.ts` and
   `tool/after.preflight.ts` decide on the raw command before the route
-  loads — keep them free of React and Effect), `src/hooks` (the handlers
-  the routes call), `src/cli/daemon.ts`, `src/scripts/hauler.ts` (process entry),
-  `src/skills`. The README's tour is the map; do not reintroduce a
+  loads — keep them free of React and Effect), `src/internal/host-hooks` (the
+  handlers the routes call), `src/cli/daemon.ts`, `src/scripts/hauler.ts` (process
+  entry), `src/skills`. Everything else lives under `src/internal/<owner>/`
+  (`docs/architecture.md` is the ownership map); do not reintroduce a
   hand-written server, argv parser, or string-concatenated documents — add a
   component and a view-model.
 - Documents must stay honest: a daemon the probe could not reach renders as

package/dist/INSTALL.md

@@ -2,7 +2,7 @@
 
 Coalesce, schedule, and stream cargo so concurrent agent sessions share compiles instead of fighting locks.
 
-Version: `0.8.1`
+Version: `0.8.3`
 
 Run these commands from this bundle directory. The bundle is self-contained: every command below is
 a host command or the bundled installer, and nothing requires the `agent-bundle` CLI. Where that CLI is

package/dist/README.md

@@ -378,16 +378,20 @@ too, along with any log whose row is gone. `hauler exec --bg -- cargo …` and
 `hauler_request` return the ticket immediately. A synchronous request also switches to background mode when a
 *measured* estimate — EWMA history or kache priors, never the cold-start
 default — exceeds the host's shell-tool cap (nine minutes for Claude, ten for
-Codex, fourteen for Cursor; the PATH shim uses `CARGO_HAULER_HOST` when it is
-exported, otherwise the Claude cap). The estimate that is compared is the
-whole wait: the work queued ahead in the lane plus the job's own runtime,
-which the queued line reports as `wait ~Ns, run ~Ns`. That conversion exits
-`75` (`EX_TEMPFAIL`) with the ticket on stderr, so `cargo build && …` chains
-and scripts cannot mistake "submitted" for "built"; explicit `--bg` keeps exit
-`0`. When the caller's stdout is not a terminal (`cargo test > out.log`), the
-notice adds that the redirect receives no output and to read it with
-`hauler result cc-N --full`. Failed runs feed the estimate history too, so a broken build is not
-re-estimated cold on every retry.
+Codex, fourteen for Cursor). The PATH shim (`--host shim`) is cargo to its
+caller: a non-TTY invocation (a script, `spawnSync`, `make`) waits for the
+ticket to finish and returns cargo's exit code. An interactive shim (stdout
+is a TTY) still auto-backgrounds on the cap, using `CARGO_HAULER_HOST` when
+it is exported, otherwise the Claude cap; `CARGO_HAULER_SHIM_BACKGROUND=1`
+restores that for scripts that consume tickets themselves. The estimate that
+is compared is the whole wait: the work queued ahead in the lane plus the
+job's own runtime, which the queued line reports as `wait ~Ns, run ~Ns`. That
+conversion exits `75` (`EX_TEMPFAIL`) with the ticket on stderr, so
+`cargo build && …` chains and scripts cannot mistake "submitted" for "built";
+explicit `--bg` keeps exit `0`. When the caller's stdout is not a terminal
+(`cargo test > out.log`), the notice adds that the redirect receives no
+output and to read it with `hauler result cc-N --full`. Failed runs feed the
+estimate history too, so a broken build is not re-estimated cold on every retry.
 
 A foreground `hauler exec` that receives SIGINT or SIGTERM (Ctrl-C, or a
 `timeout N …` wrapper) asks the daemon to kill its ticket, waits for the
@@ -674,7 +678,8 @@ Per-host notes and hook timeouts are in [docs/install.md](docs/install.md).
 | `CARGO_HAULER_LEDGER_MAX_ROWS` | `50000` | Total ledger rows beyond which the oldest finished rows are deleted when the daemon starts; `0` disables the row cap. Pruned rows take their `tickets/<ticket>.log` files with them. |
 | `CARGO_HAULER_TICKET_LOG_MAX_BYTES` | `67108864` (64 MiB) | Bytes of a leader run's combined output written to `<state dir>/tickets/<ticket>.log` before the log stops with one truncation line; `0` writes no ticket logs (`hauler result` then has only the tail). |
 | `CARGO_HAULER_LOG_LEVEL` | `Info` | Daemon log level. |
-| `CARGO_HAULER_HOST`, `CARGO_HAULER_SESSION` | Unset | Default `--host` and `--session` attribution for `hauler exec`; the PATH shim also borrows `CARGO_HAULER_HOST`'s shell cap for auto-background. |
+| `CARGO_HAULER_HOST`, `CARGO_HAULER_SESSION` | Unset | Default `--host` and `--session` attribution for `hauler exec`; the PATH shim also borrows `CARGO_HAULER_HOST`'s shell cap when auto-background is allowed. |
+| `CARGO_HAULER_SHIM_BACKGROUND` | Unset | `1` / `true` / `on` / `yes` lets a non-TTY PATH shim auto-background over the host cap (exit 75). Without it, a shim that is not a TTY waits for cargo's exit. |
 
 A numeric value that does not parse or falls outside its range is reported
 as a warning (daemon log, or stderr for hand-run commands) and the default
@@ -787,7 +792,6 @@ argv parser, or string-concatenated Markdown; the `src/` tree is the app.
 src/
   layout.tsx                    the hauler shell around every rendered route
   providers/hauler-daemon.ts    request-scoped daemon configuration
-  components/                   typed components over pure view-models
   mcp/hauler/tools/*.tsx        hauler_status, _dashboard, _log, _last, _await, _result, _request, _kill
   mcp/hauler/tools/*.cli.ts     each tool's `hauler <command>` projection (flags, positionals)
   mcp/hauler/apps/dashboard.tsx the MCP App (ui://cargo-hauler/dashboard.html)
@@ -796,9 +800,26 @@ src/
   events/tool/{before,after}.tsx    the shell hook routes, gated by *.preflight.ts
   skills/cargo-hauler/SKILL.md, skills/hauler-dashboard/SKILL.tsx
   scripts/hauler.ts             the `hauler` process entry hooks rewrite cargo to
-  daemon/, client/, hooks/, shim/, lib/   the broker and its libraries
+  internal/                     the implementation the entrypoints import, by owner
+    contracts/                  wire protocol, tool schemas, wire version
+    cargo/                      argv, intent, workspace, topology, execution/
+    daemon/                     composition (main, config), runtime/, broker/, scheduling/, reporting/
+    storage/                    the SQLite ledger and per-ticket output logs
+    client/                     socket clients: control, exec, tickets, ensure-daemon
+    operations/                 what the routes call: tickets, status, inspection
+    host-hooks/                 the shell/session hook handlers and their small RPC client
+    integrations/kache/         kache status and store pressure
+    platform/                   state and socket paths, private-file policy, executable location
+    shim/                       the PATH shim installer
+    ui/documents/, ui/dashboard/, ui/shared/   agent documents, the browser App, shared formatters
+    util/                       guards, ids, text, ANSI
 ```
 
+Everything above `internal/` is discovered by the framework's conventions;
+everything under it is ordinary imported code. [docs/architecture.md](docs/architecture.md)
+is the ownership map and walks the three main paths (submitting cargo, reading
+status, processing a shell hook) file by file.
+
 #### The shell (`src/layout.tsx`)
 
 Every rendered route — MCP tool, CLI command, rendered script — composes
@@ -826,7 +847,7 @@ addition: each re-exports a `preflight` (`before.preflight.ts`,
 `hooks/event-route-tool-before.<host>.mjs`, a few hundred KB with no React,
 Flight worker, or Effect — and runs before the rendered route
 (`*.execute.mjs`) is loaded. The gate decides on the raw command
-(`src/hooks/tokens.ts`; `session-ping.ts` for the one bounded completion ping
+(`src/internal/host-hooks/tokens.ts`; `session-ping.ts` for the one bounded completion ping
 after a tool ran): `continue` for the shell calls that name neither cargo nor
 hauler, `execute` for the rest. Both routes declare `providers: []`, so
 neither mounts the daemon-config provider; the rendered route calls
@@ -843,7 +864,7 @@ socket, and ledger paths); active health and status I/O belongs to the operation
 that needs it. Routes read the config through `requestDaemonConfig(context)`,
 and tests inject a fixture through the harness `context.providers` seam.
 
-#### Components (`src/components/`)
+#### Components (`src/internal/ui/documents/`)
 
 Components render view-models and nothing else. The models are pure functions
 in `view-models.ts`, so the MCP document, the CLI Markdown, and a test
@@ -871,7 +892,7 @@ assertion share one derivation.
 same operation render the same document with different command spellings
 (`surface.ts`).
 
-#### Streaming (`src/components/streaming.tsx`)
+#### Streaming (`src/internal/ui/documents/streaming.tsx`)
 
 `hauler_await` and `hauler_log` are progressive documents. Each is a
 valueless `Agent.Result` container around one `Suspense` boundary:
@@ -944,7 +965,7 @@ with the wait split by cause: *lane-bound* (a same-lane leader was still
 compiling — before its `Finished` line or exit), *permit-bound* (every
 admission permit was held and no same-lane compile was to blame), and *other*
 (admission holds, `--after` prerequisites, scheduling latency). The
-classification is a pure sweep over ledger rows (`src/daemon/wait-split.ts`)
+classification is a pure sweep over ledger rows (`src/internal/daemon/reporting/wait-split.ts`)
 run once per status refresh against the daemon's current permit count, which
 the tile states; runs admitted under an earlier cap are classified against
 today's. With `buildFinishedAtMs` on the row, the by-command split adds
@@ -957,12 +978,19 @@ the lane time the execution-phase hand-back released.
 pnpm run check   # validate + build + typecheck + Effect diagnostics + rstest + route tests
 ```
 
+`tests/` is grouped by what a test executes: `unit/<subsystem>/` is scoped to
+one owner under `src/internal/`; `integration/` runs a real broker
+in-process through `tests/support/harness.ts`; `packaging/` reads the built
+`artifact/` or spawns the package entries; `acceptance/` drives real `cargo`
+against the workspaces under `evals/fixtures/`; `route-unit/` and
+`browser-app/` are the framework-level suites below.
+
 `tests/route-unit/` renders the app through the framework compiler with no
 artifact build, at the harness proof levels:
 
 | Level | Suite | What it proves |
 | --- | --- | --- |
-| route-unit | `routes`, `layout`, `streaming`, `events` | documents, shell metadata, Suspense fallbacks and settled values, lineage attribution, event decisions (the shell routes' preflight gates are unit-tested in `tests/event-preflight.test.ts` and against their compiled entries in `tests/hooks-simulate.test.ts`) |
+| route-unit | `routes`, `layout`, `streaming`, `events` | documents, shell metadata, Suspense fallbacks and settled values, lineage attribution, event decisions (the shell routes' preflight gates are unit-tested in `tests/integration/event-preflight.test.ts` and against their compiled entries in `tests/integration/hooks-simulate.test.ts`) |
 | cli-dispatch | `cli-dispatch`, `layout` | argv through the routed CLI shell; Markdown wrapped by the shell, `--json` bare |
 | script-dispatch | `script-dispatch` | the `hauler` entry through its `main` envelope as its own process |
 | mcp-in-memory | `mcp-surface`, `layout` | tool names, `outputSchema`, the dashboard resource link, `_meta.hauler`, and a live fixture broker over the in-memory transport |
@@ -971,7 +999,7 @@ artifact build, at the harness proof levels:
 | workbench-surface | `workbench-surface` | what `agent-bundle dev` would show: catalog, provider, lifecycles per host, counts |
 
 Daemon-backed cases run a real broker in-process with a fake `cargo`
-(`tests/harness.ts`) and reach it either through the `haulerDaemon` provider
+(`tests/support/harness.ts`) and reach it either through the `haulerDaemon` provider
 seam or through `CARGO_HAULER_STATE_DIR`.
 
 ### Development