feat: explicit profile-level host mounts, host_mounts (RM-12)

[AviBackToBlack]

Why

A real MCP integration (@whdrnr2583/token-meter) needs to read %USERPROFILE%\.claude and
%USERPROFILE%\.codex to ingest real session history — directories that are neither the project
tree, an argument the tool receives, nor something project_volumes/shared_volumes can express
(those are Docker-managed named volumes, not host bind mounts). ContainerBin had no declarative
way for a trusted profile to say "mount this exact host path here, with this access mode."

Filed as issue #29 / RM-12 in the roadmap (issue #2). This PR expands the trust boundary
deliberately and narrowly, with stricter rules than the existing inferred-argument mount
mechanism, per the issue's own explicit security requirements.

What changed

New provider-agnostic host_mounts registry field:

[tools.token-meter]
image = "example/token-meter:latest"
provider = "stateless"
host_mounts = [
  "%USERPROFILE%\.claude:/root/.claude:ro",
  "%USERPROFILE%\.codex:/root/.codex:ro",
]

Key design decisions:

• Reuses this project's own NAME:/container/path convention, extended with a required
  :MODE suffix — not Docker Compose's HOST:CONTAINER:MODE triplet, which is ambiguous against
  a literal Windows source path that already contains a colon (D:\Video). The existing
  ParseVolumeBinding "first :/" delimiter trick (already used by project_volumes/
  shared_volumes) solves this cleanly and is reused verbatim.
• Mode (ro/rw) is required, never defaulted — every mount's write access is visible by
  reading the registry line.
• Exactly one host variable is understood: %USERPROFILE%, only at the start of the source,
  with no other %...% token permitted anywhere else in it. Anything else is rejected outright —
  deliberately not a general expansion mechanism.
• Two-stage validation: static structural checks (target must be absolute, must not fall
  under the reserved /workspace//cb namespaces, no duplicate targets, no collision with a
  declared volume destination) happen at registry-load time with no filesystem/env access;
  environment-dependent resolution (variable expansion, canonicalization through the existing
  pathmap.CanonicalPath, UNC rejection, existence check) happens at RunTool time and fails
  closed.
• No second path-normalization implementation — reuses pathmap.CanonicalPath exactly.
• MountSpec's existing signature and every call site are untouched. A new MountSpecMode
  was added alongside it, not as a replacement.
• Diagnostics: cb inspect (raw declared entry) and cb trace (expanded/resolved entry, per
  each command's existing purpose) get new host_mount lines; cb doctor gets a new
  fail-closed-informing (warn, not fail — missing source is per-machine state, not a cb
  defect) existence check per declared mount, plus an optional bonus check for mapped-network
  drives reusing existing cb doctor machinery. cb bugreport needed no code changes — it
  already captures cb doctor's output through the existing redaction pass.
• Out of scope, deliberately: cwd_mode (the related-but-orthogonal launcher-CWD problem,
  filed as its own follow-up in issue Roadmap: post-bootstrap improvements (audit follow-ups, categorized) #2); any change to internal/pathmap's existing
  argument-path inference; a Token-Meter-specific provider; general shell-style variable
  expansion; making rw implicit.

Pipeline

Implemented by SWE-1.7 Max (comparable rigor to RM-2/RM-9, given this is the first registry field
that intentionally exposes arbitrary host paths beyond the project/argument mounts), verified
(blind, pasted-context) by GLM-5.2 High — clean PASS, with one item GLM correctly flagged as a
low-confidence note it couldn't resolve without file access: whether project_volumes
destinations are always /workspace-prefixed, the assumption the collision check relied on to
justify checking only shared_volumes.

The orchestrator checked, and the assumption was wrong — ParseVolumeBinding places no such
requirement; it's only true by convention for this repo's built-in profiles. Fixed directly
(4b522b8): the collision check now covers both project_volumes and shared_volumes
destinations, with a regression test. This is exactly the class of gap a blind, no-file-access
verifier is structurally unable to close on its own, and why the orchestrator reviews every diff
independently rather than relaying agent reports.

Independently re-validated (not just the implementer's report) inside golang:1.24 at every
stage, including after the orchestrator's own fix:

gofmt -l . ; go vet ./... && go test -race ./...

All clean, all green.

Validation

MSYS_NO_PATHCONV=1 docker run --rm -v "D:\Work\GIT\container-bin:/src" -w /src -e GOFLAGS=-buildvcs=false golang:1.24 sh -c "gofmt -l . ; go vet ./... && go test -race ./..."

🤖 Generated with a multi-agent pipeline (SWE-1.7 Max implementer, GLM-5.2 High blind verifier, orchestrated by Claude Code)

Update: a serious bug was found and fixed after the above was written

Round 2's fix for the target-collision-detection gap (normalizing container paths with
path.Clean so equivalent forms like /root/.x and /root/./.x are correctly recognized as the
same target) had a side effect nobody caught in that round: path.Clean("/workspace/..") returns
/, and / was not itself in the reserved-namespace list. A host_mounts entry declaring
target /workspace/.. (or /cb/..) would clean to / and pass validation — mounting a host
directory at the container's filesystem root, shadowing every container-bin-managed mount. The
broadest possible target, on this PR's own trust-boundary feature.

Neither Devin Review nor Copilot caught this across three review passes. It was found by a
second, full-diff GLM re-verify pass run specifically because this task's trust-boundary bar
warranted not stopping at "the named findings were addressed." Fixed directly by the
orchestrator (given validateHostMounts had by then had two independent gaps found in it):
reject any literal .. path segment in a declared target before path.Clean ever runs, plus a
defense-in-depth rejection of a cleaned target equal to bare /. A third, narrowly-scoped GLM
pass focused specifically on this fix confirmed it closes the hole without introducing a new one,
and flagged one coverage gap (the defense-in-depth branch itself was untested), closed
immediately.

This is exactly the failure mode a trust-boundary feature needs guarding against: a fix for one
(lower-severity) finding opening a new, more severe one in shared validation logic. Full details
in .handoff/RM-12/r2-verdict.md and .handoff/RM-12/r3-verdict-focused.md.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

Suppressed comments (4)

internal/diag/diag.go:361

• mode is discarded here, so cb doctor (and therefore cb bugreport) reports the source, target, and existence status but omits the declared ro/rw access. The linked diagnostics requirement explicitly includes mode, and omitting it hides the most security-relevant part of a host mount. Preserve the parsed mode and include it in hostMountVerdict output and its tests.

			source, target, _, err := registry.ParseHostMount(spec)

internal/dockerrun/dockerrun.go:298

• Every os.Stat failure is reported as “does not exist,” but errors such as access denied, an invalid path, or an unavailable device do not establish nonexistence. Keep failing closed, but reserve this message for errors.Is(statErr, os.ErrNotExist) and surface the actual error otherwise.

		if _, statErr := os.Stat(canon); statErr != nil {
			return nil, fmt.Errorf("host_mounts source %q does not exist: %s", source, canon)
		}

internal/cli/cli.go:117

• This labels every os.Stat error as a missing source, so cb trace gives incorrect guidance for permission, device, or other filesystem failures. Distinguish os.ErrNotExist from other errors and include the latter error in the would-fail annotation.

			if _, statErr := os.Stat(expanded); statErr != nil {
				fmt.Printf("host_mount:  %s -> %s (%s) [would fail: source does not exist]\n", expanded, target, mode)

internal/diag/diag.go:377

• Reducing statErr to a boolean makes doctor report every filesystem failure as “does not exist.” Access-denied and unavailable-device errors need a distinct warning containing the actual error; only os.ErrNotExist should use the missing-source verdict.

			_, statErr := os.Stat(canon)
			status, msg := hostMountVerdict(name, source, target, canon, statErr == nil)

[devin-ai-integration]

Devin Review found 4 new potential issues.