docs: mark PRD 0041 Active

Before this change, int() on a non-numeric Content-Length raised an
unhandled ValueError, crashing the request handler. There was also no
upper bound on how much memory a POST body could consume.

After this change:
- Non-numeric or missing Content-Length returns HTTP 400.
- Negative Content-Length returns HTTP 400.
- Bodies declared larger than 1 MiB (_MAX_BODY_BYTES) return HTTP 413,
  matching the cap already in supervise_server.py.

Closes #138

bot_bottle/backend/docker/bottle_state.py

@@ -105,6 +105,10 @@ class BottleMetadata:
     # written before chunk 3 (resume / inspect should fall back to
     # deriving from identity in that case).
     compose_project: str = ""
+    # PRD 0040: backend name ("docker" or "smolmachines"). Empty string
+    # for state dirs written before PRD 0040; callers default to "docker"
+    # for backward compatibility.
+    backend: str = ""
 
 
 def metadata_path(identity: str) -> Path:
@@ -138,6 +142,7 @@ def read_metadata(identity: str) -> BottleMetadata | None:
         copy_cwd=bool(raw.get("copy_cwd", False)),
         started_at=str(raw.get("started_at", "")),
         compose_project=str(raw.get("compose_project", "")),
+        backend=str(raw.get("backend", "")),
     )
 
 

bot_bottle/backend/docker/prepare.py

@@ -79,6 +79,7 @@ def resolve_plan(
         copy_cwd=spec.copy_cwd,
         started_at=datetime.now(timezone.utc).isoformat(),
         compose_project=f"bot-bottle-{slug}",
+        backend="docker",
     ))
     # Clear any leftover preserve marker from a prior capability-block
     # so this fresh launch can be cleaned up at session-end unless

bot_bottle/backend/smolmachines/prepare.py

@@ -28,6 +28,7 @@ from ...backend.docker.bottle_state import (
     write_metadata,
 )
 from ...egress import Egress
+from ...env import resolve_env
 from ...git_gate import GitGate
 from ...pipelock import PipelockProxy
 from ...supervise import Supervise
@@ -70,25 +71,24 @@ def resolve_plan(
         cwd=spec.user_cwd if spec.copy_cwd else "",
         copy_cwd=spec.copy_cwd,
         started_at=datetime.now(timezone.utc).isoformat(),
-        # No compose project for smolmachines bottles; chunk 4
-        # will give dashboard discovery a backend-specific path.
         compose_project="",
+        backend="smolmachines",
     ))
 
     subnet, gateway, bundle_ip = smolmachines_bundle_subnet(slug)
 
-    # Agent's env: the prepare-time view doesn't yet know the
-    # host loopback ports the bundle's daemons get published on
-    # (those come from docker AFTER `docker run` returns), so
-    # HTTPS_PROXY / GIT_GATE_URL / MCP_SUPERVISE_URL are
-    # populated in launch.py and stamped onto guest_env there.
-    # What we set here is the part that doesn't depend on
-    # bundle bringup — bottle.env literals, the empty-NO_PROXY
-    # safe default, and the TLS trust env trio
-    # (NODE_EXTRA_CA_CERTS / SSL_CERT_FILE / REQUESTS_CA_BUNDLE)
-    # pointing at Debian's update-ca-certificates output bundle.
+    # Agent's env: resolve through resolve_env() so ?prompt entries
+    # are prompted and ${HOST_VAR} entries are interpolated — matching
+    # the Docker backend's contract. Forwarded (secret/interpolated)
+    # values still reach the guest as -e K=V smolvm flags because
+    # smolvm 0.8.0 has no env-file or stdin injection path; this is
+    # the known argv-exposure gap documented in PRD 0038.
+    # HTTPS_PROXY / GIT_GATE_URL / MCP_SUPERVISE_URL are populated
+    # in launch.py after bundle bringup.
+    resolved = resolve_env(manifest, spec.agent_name)
     guest_env: dict[str, str] = {
-        **bottle.env,
+        **resolved.literals,
+        **resolved.forwarded,
         "NO_PROXY":    "localhost,127.0.0.1",
         "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/ca-certificates.crt",
         "SSL_CERT_FILE":       "/etc/ssl/certs/ca-certificates.crt",

bot_bottle/cli/dashboard.py

@@ -175,6 +175,13 @@ def approve(
             qp.proposal.bottle_slug, file_to_apply,
         )
     elif qp.proposal.tool == TOOL_CAPABILITY_BLOCK:
+        _meta = read_metadata(qp.proposal.bottle_slug)
+        if _meta is not None and not _meta.compose_project:
+            raise CapabilityApplyError(
+                "capability-block remediation is not supported for smolmachines "
+                "bottles. Reject this proposal or handle the capability change "
+                "manually, then restart the bottle."
+            )
         diff_before, diff_after = apply_capability_change(
             qp.proposal.bottle_slug, file_to_apply,
         )
@@ -640,23 +647,19 @@ def _bottle_for_slug(
 ) -> tuple["object", str]:
     """Return `(bottle_handle, prompt_path_hint)` for a re-attach.
     If the slug is in `bottles` (dashboard-owned), return the stored
-    handle directly. Otherwise synthesize a `DockerBottle` from the
-    container name `bot-bottle-<slug>`. For synthesized bottles
-    the prompt-file path comes from the manifest's agent if we can
-    resolve it via metadata.json + the loaded manifest; otherwise
-    the re-attach runs without `--append-system-prompt-file`.
+    handle directly. Otherwise synthesize a bottle from the persisted
+    metadata. The backend field in metadata (PRD 0040) selects Docker
+    or smolmachines; unknown or missing metadata defaults to Docker.
 
     Returns the empty string for prompt_path_hint when we omit the
     flag — the caller passes None to DockerBottle in that case."""
     from ..backend.docker.bottle import DockerBottle
     from ..backend.docker.bottle_state import read_metadata
+    from ..backend.smolmachines.bottle import SmolmachinesBottle
     if slug in bottles:
         _cm, bottle, _identity = bottles[slug]
         return bottle, ""
-    # The container hosting the agent's agent process is named
-    # `bot-bottle-<slug>` — set by the compose renderer
-    # (no service suffix on the agent service, by design).
-    container_name = f"bot-bottle-{slug}"
+    instance_name = f"bot-bottle-{slug}"
     prompt_path: str | None = None
     metadata = read_metadata(slug)
     if metadata is not None and manifest is not None:
@@ -666,11 +669,18 @@ def _bottle_for_slug(
                 "BOT_BOTTLE_CONTAINER_HOME", "/home/node",
             )
             prompt_path = f"{container_home}/.bot-bottle-prompt.txt"
-    synth = DockerBottle(
-        container=container_name,
-        teardown=lambda: None,
-        prompt_path_in_container=prompt_path,
-    )
+    backend = metadata.backend if metadata is not None else ""
+    if backend == "smolmachines":
+        synth: object = SmolmachinesBottle(
+            instance_name,
+            prompt_path=prompt_path,
+        )
+    else:
+        synth = DockerBottle(
+            container=instance_name,
+            teardown=lambda: None,
+            prompt_path_in_container=prompt_path,
+        )
     return synth, (prompt_path or "")
 
 

bot_bottle/cli/resume.py

@@ -52,8 +52,10 @@ def cmd_resume(argv: list[str]) -> int:
         user_cwd=metadata.cwd or USER_CWD,
         identity=metadata.identity,
     )
+    backend_name = metadata.backend or None
     return _launch_bottle(
         spec,
         dry_run=args.dry_run,
         remote_control=args.remote_control,
+        backend_name=backend_name,
     )

docs/prds/0038-smolmachines-env-contract.md

@@ -0,0 +1,102 @@
+# PRD 0038: smolmachines Env Contract and Secret-Safe Injection
+
+- **Status:** Active
+- **Author:** didericis-codex
+- **Created:** 2026-06-02
+- **Issue:** #135
+
+## Summary
+
+Make smolmachines env handling match Docker's contract: resolve manifest env
+entries through `resolve_env()`, keep secret and interpolated values out of
+host argv, and document or enforce an explicit env contract for the backend.
+
+## Problem
+
+`bot_bottle/backend/smolmachines/prepare.py` builds the guest env from
+`bottle.env` directly, bypassing `resolve_env()`. Entries like `?prompt` and
+`${HOST_VAR}` can reach the guest literally rather than being prompted or
+resolved. In contrast, Docker resolves env through `resolve_env()` before
+writing a mode-600 env file.
+
+`smolmachines/smolvm.py` renders env as `-e KEY=VALUE` on `smolvm machine
+create` argv, and `SmolmachinesBottle.agent_argv` / `exec` prepend
+`env KEY=VALUE …` onto the `smolvm machine exec` argv. Any literal or resolved
+secret value is therefore visible in the host process table.
+
+The two backends have no shared env contract document. Divergence will silently
+widen as new manifest env features are added.
+
+## Goals / Success Criteria
+
+- Manifest env entries are resolved through `resolve_env()` before being
+  injected into the smolmachines guest, matching Docker behaviour.
+- No manifest env value (literal or resolved) appears on host argv during
+  machine creation or exec.
+- Define and document an explicit smolmachines env contract covering literals,
+  `?prompt` secrets, and `${HOST_VAR}` interpolations.
+- Unit tests cover: literal passthrough, prompted-secret resolution,
+  host-var interpolation, and the no-argv-leak invariant.
+
+## Non-goals
+
+- No changes to the Docker env path.
+- No changes to manifest schema or `resolve_env()` itself.
+- No changes to smolmachines networking or mount handling.
+- No new runtime dependencies.
+
+## Scope
+
+In scope:
+
+- `bot_bottle/backend/smolmachines/prepare.py` env resolution.
+- `bot_bottle/backend/smolmachines/smolvm.py` machine-create argv.
+- `bot_bottle/backend/smolmachines/bottle.py` `agent_argv` / `exec` env
+  injection.
+- `bot_bottle/env.py` if helper changes are needed to support the smolmachines
+  path.
+- Unit tests in `tests/unit/` covering the above.
+
+Out of scope:
+
+- Integration tests that start a live smolmachines VM.
+- Docker backend changes.
+- Dashboard or CLI changes.
+
+## Design
+
+Run smolmachines env through `resolve_env()` at prepare time, exactly as Docker
+does. After resolution, inject env into the guest through a mechanism that does
+not expose values on host argv — for example by writing a mode-600 env file
+into the machine's state directory and loading it at exec time, or by passing
+env through `smolvm`'s stdin if the tool supports it.
+
+If `smolvm` provides no stdin or env-file injection path, document this as a
+known limitation and at minimum move env values behind a per-invocation
+tmpfile rather than inline argv.
+
+The env contract for smolmachines should mirror Docker's:
+
+- Literals: passed as-is after resolution.
+- `?prompt` entries: prompted at prepare time; resolved value injected, never
+  on argv.
+- `${HOST_VAR}` entries: interpolated from the operator's env at prepare time;
+  resolved value injected, never on argv.
+
+## Testing Strategy
+
+- Unit tests for `prepare.py` asserting `resolve_env()` is called and that
+  resolution results are used rather than raw `bottle.env` values.
+- Unit tests for `smolvm.py` machine-create argv asserting no env value appears
+  inline.
+- Unit tests for `bottle.py` exec path asserting the same argv invariant.
+
+Run:
+
+- `python3 -m unittest tests.unit.test_smolmachines_prepare`
+- `python3 -m unittest discover -s tests/unit`
+
+## Open Questions
+
+- Does `smolvm machine create` support an env-file flag or stdin injection that
+  avoids `-e KEY=VALUE` argv?

docs/prds/0039-smolmachines-capability-remediation.md

@@ -0,0 +1,87 @@
+# PRD 0039: smolmachines Capability-Block Remediation
+
+- **Status:** Active
+- **Author:** didericis-codex
+- **Created:** 2026-06-02
+- **Issue:** #136
+
+## Summary
+
+Make capability-block remediation backend-aware. Today the dashboard approval
+path calls Docker-only teardown and apply code regardless of which backend
+created the bottle. Either implement smolmachines remediation or add a clean
+disable/unsupported path so operators never get a partial Docker teardown
+against a smolmachines slug.
+
+## Problem
+
+`bot_bottle/cli/dashboard.py` dispatches every capability-block approval to
+`bot_bottle/backend/docker/capability_apply.py`. That code snapshots with
+`docker cp`, pushes via `docker exec`, rewrites a Dockerfile override, and
+removes Docker containers and networks. It does not stop or delete a smolvm
+machine.
+
+smolmachines bottles still receive the capability-block supervise tool through
+`backend/smolmachines/provision/supervise.py`, so agents can queue a
+remediation the host cannot correctly apply. A partial Docker teardown against
+a smolmachines slug corrupts neither backend cleanly.
+
+## Goals / Success Criteria
+
+- Capability-block approval is routed to backend-specific code.
+- For the smolmachines backend, either:
+  a. A real remediation implementation that stops the VM, applies the
+     capability change, and restarts correctly; or
+  b. A clean unsupported response that tells the operator the action cannot
+     be taken and leaves the bottle in a consistent state.
+- If option (b): smolmachines agents do not receive the capability-block tool,
+  so the operator is never prompted for an action that will fail.
+- Unit tests cover the dispatch logic and the smolmachines path.
+
+## Non-goals
+
+- No changes to the Docker capability-apply path.
+- No changes to other supervise tools (cred-block, pipelock-block).
+- No changes to manifest or egress configuration.
+
+## Scope
+
+In scope:
+
+- `bot_bottle/cli/dashboard.py` approval dispatch.
+- `bot_bottle/backend/smolmachines/provision/supervise.py` tool registration.
+- New or updated backend-specific capability apply/disable module for
+  smolmachines.
+- Unit tests for dispatch routing and smolmachines path.
+
+Out of scope:
+
+- Changes to `backend/docker/capability_apply.py` internals.
+- Integration tests that exercise a live smolmachines VM remediation.
+
+## Design
+
+Introduce a backend-aware dispatch at the approval call site. Each backend
+exposes a capability remediation entry point; the dashboard calls the one that
+matches the bottle's backend. If the backend does not support remediation,
+the entry point returns a structured error that the dashboard surfaces as an
+operator message without attempting any teardown.
+
+If option (b) is chosen initially, suppress capability-block registration in
+`smolmachines/provision/supervise.py` so agents never see the tool.
+
+## Testing Strategy
+
+- Unit test that approval dispatch selects the smolmachines path for a
+  smolmachines bottle and the Docker path for a Docker bottle.
+- Unit test for the smolmachines path (unsupported response or real apply).
+- Regression test that Docker approval still calls `capability_apply.py`.
+
+Run:
+
+- `python3 -m unittest discover -s tests/unit`
+
+## Open Questions
+
+- Is a real smolmachines capability-apply implementation in scope for this PRD,
+  or should it be deferred to a follow-on after PRD 0040 lands?

docs/prds/0040-backend-aware-resume-and-dashboard.md

@@ -0,0 +1,87 @@
+# PRD 0040: Backend-Aware Resume and Dashboard Reattach
+
+- **Status:** Active
+- **Author:** didericis-codex
+- **Created:** 2026-06-02
+- **Issue:** #137
+
+## Summary
+
+Persist the backend name in `BottleMetadata` and thread it through `resume` and
+dashboard reattach so both flows construct the correct backend bottle without
+relying on env overrides or defaulting to Docker.
+
+## Problem
+
+`BottleMetadata` records identity, agent, cwd, started_at, and compose project,
+but not the backend name. Without it:
+
+- `cli/resume.py` cannot select the right backend from a preserved state dir
+  alone; operators must remember to set `BOT_BOTTLE_BACKEND=smolmachines`
+  separately.
+- `cli/dashboard.py` `_bottle_for_slug` constructs a `DockerBottle` for any
+  externally discovered slug, so reattaching to a live smolmachines agent
+  from the dashboard sends Docker commands to a smolvm machine.
+
+## Goals / Success Criteria
+
+- `BottleMetadata` includes the backend name, written at bottle creation time
+  for both Docker and smolmachines.
+- `cli resume` reads the persisted backend name and constructs the correct
+  bottle type without requiring an env override.
+- Dashboard reattach (`_bottle_for_slug`) reads the persisted backend name and
+  constructs the correct bottle type.
+- Existing Docker bottles without a persisted backend name fall back to Docker
+  (backward-compatible default).
+- Unit tests cover write, read, backward-compatible fallback, and both
+  resume/reattach code paths.
+
+## Non-goals
+
+- No changes to manifest or egress configuration.
+- No new CLI flags (backend selection at resume time should be automatic).
+- No smolmachines capability-apply implementation (see PRD 0039).
+
+## Scope
+
+In scope:
+
+- `bot_bottle/backend/docker/bottle_state.py` `BottleMetadata` schema and
+  write path.
+- `bot_bottle/backend/docker/bottle.py` and
+  `bot_bottle/backend/smolmachines/bottle.py` metadata write at creation.
+- `bot_bottle/cli/resume.py` backend selection from metadata.
+- `bot_bottle/cli/dashboard.py` `_bottle_for_slug` backend selection.
+- Unit tests covering the above.
+
+Out of scope:
+
+- Migration tooling for existing state dirs.
+- Integration tests that exercise full resume across process restarts.
+
+## Design
+
+Add a `backend` field to `BottleMetadata` with a default of `"docker"` for
+backward compatibility. Both `DockerBottle` and `SmolmachinesBottle` write
+their backend name into metadata at creation time.
+
+`resume` reads the metadata before constructing the bottle object and selects
+the appropriate backend class. `_bottle_for_slug` does the same. A helper
+function in the metadata module can encapsulate the backend-name-to-class
+mapping so the logic is not duplicated.
+
+## Testing Strategy
+
+- Unit tests for `BottleMetadata` serialisation with and without the backend
+  field.
+- Unit tests for the backward-compatible default.
+- Unit tests for `resume` selecting smolmachines vs Docker from metadata.
+- Unit tests for `_bottle_for_slug` selecting smolmachines vs Docker.
+
+Run:
+
+- `python3 -m unittest discover -s tests/unit`
+
+## Open Questions
+
+None.

tests/unit/test_bottle_state.py

@@ -216,5 +216,112 @@ class TestBottleMetadata(_FakeHomeMixin, unittest.TestCase):
         self.assertEqual("t2", loaded.started_at)
 
 
+class TestBottleMetadataBackend(_FakeHomeMixin, unittest.TestCase):
+    """PRD 0040: backend field is persisted and read back."""
+
+    def setUp(self):
+        self._setup_fake_home()
+
+    def tearDown(self):
+        self._teardown_fake_home()
+
+    def test_backend_field_roundtrips_docker(self):
+        meta = BottleMetadata(
+            identity="dev-b1",
+            agent_name="dev",
+            cwd="",
+            copy_cwd=False,
+            started_at="2026-06-02T00:00:00+00:00",
+            compose_project="bot-bottle-dev-b1",
+            backend="docker",
+        )
+        write_metadata(meta)
+        loaded = read_metadata("dev-b1")
+        self.assertIsNotNone(loaded)
+        assert loaded is not None
+        self.assertEqual("docker", loaded.backend)
+
+    def test_backend_field_roundtrips_smolmachines(self):
+        meta = BottleMetadata(
+            identity="dev-b2",
+            agent_name="dev",
+            cwd="",
+            copy_cwd=False,
+            started_at="2026-06-02T00:00:00+00:00",
+            compose_project="",
+            backend="smolmachines",
+        )
+        write_metadata(meta)
+        loaded = read_metadata("dev-b2")
+        self.assertIsNotNone(loaded)
+        assert loaded is not None
+        self.assertEqual("smolmachines", loaded.backend)
+
+    def test_missing_backend_field_defaults_to_empty(self):
+        # Old state dirs written before PRD 0040 have no backend key.
+        import json
+        from bot_bottle.backend.docker import bottle_state as bs
+        path = bs.metadata_path("dev-b3")
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps({
+            "identity": "dev-b3",
+            "agent_name": "dev",
+            "cwd": "",
+            "copy_cwd": False,
+            "started_at": "2026-06-02T00:00:00+00:00",
+            "compose_project": "bot-bottle-dev-b3",
+        }))
+        loaded = read_metadata("dev-b3")
+        self.assertIsNotNone(loaded)
+        assert loaded is not None
+        self.assertEqual("", loaded.backend)
+
+
+class TestBottleForSlugBackend(_FakeHomeMixin, unittest.TestCase):
+    """PRD 0040: _bottle_for_slug constructs the right bottle type."""
+
+    def setUp(self):
+        self._setup_fake_home()
+
+    def tearDown(self):
+        self._teardown_fake_home()
+
+    def test_docker_metadata_returns_docker_bottle(self):
+        from bot_bottle.backend.docker.bottle import DockerBottle
+        from bot_bottle.cli.dashboard import _bottle_for_slug
+        write_metadata(BottleMetadata(
+            identity="dev-d1",
+            agent_name="dev",
+            cwd="",
+            copy_cwd=False,
+            started_at="2026-06-02T00:00:00+00:00",
+            compose_project="bot-bottle-dev-d1",
+            backend="docker",
+        ))
+        bottle, _ = _bottle_for_slug("dev-d1", {}, None)
+        self.assertIsInstance(bottle, DockerBottle)
+
+    def test_smolmachines_metadata_returns_smolmachines_bottle(self):
+        from bot_bottle.backend.smolmachines.bottle import SmolmachinesBottle
+        from bot_bottle.cli.dashboard import _bottle_for_slug
+        write_metadata(BottleMetadata(
+            identity="dev-s1",
+            agent_name="dev",
+            cwd="",
+            copy_cwd=False,
+            started_at="2026-06-02T00:00:00+00:00",
+            compose_project="",
+            backend="smolmachines",
+        ))
+        bottle, _ = _bottle_for_slug("dev-s1", {}, None)
+        self.assertIsInstance(bottle, SmolmachinesBottle)
+
+    def test_no_metadata_defaults_to_docker_bottle(self):
+        from bot_bottle.backend.docker.bottle import DockerBottle
+        from bot_bottle.cli.dashboard import _bottle_for_slug
+        bottle, _ = _bottle_for_slug("unknown-slug", {}, None)
+        self.assertIsInstance(bottle, DockerBottle)
+
+
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_dashboard.py

@@ -577,5 +577,54 @@ class TestEditInEditor(unittest.TestCase):
                 os.environ["EDITOR"] = original_editor
 
 
+class TestCapabilityBlockSmolmachinesGuard(_FakeHomeMixin, unittest.TestCase):
+    """approve() must refuse capability-block for smolmachines bottles and
+    pass it through for Docker bottles (PRD 0039)."""
+
+    def setUp(self):
+        self._setup_fake_home()
+        self._original_apply_capability = dashboard.apply_capability_change
+        dashboard.apply_capability_change = lambda slug, content: ("", content)
+
+    def tearDown(self):
+        dashboard.apply_capability_change = self._original_apply_capability
+        self._teardown_fake_home()
+
+    def _enqueue_capability(self, slug: str = "dev") -> "dashboard.QueuedProposal":
+        p = _proposal(slug=slug, tool=TOOL_CAPABILITY_BLOCK)
+        qdir = supervise.queue_dir_for_slug(slug)
+        qdir.mkdir(parents=True, exist_ok=True)
+        supervise.write_proposal(qdir, p)
+        return dashboard.QueuedProposal(proposal=p, queue_dir=qdir)
+
+    def _write_metadata(self, slug: str, compose_project: str) -> None:
+        from bot_bottle.backend.docker.bottle_state import BottleMetadata, write_metadata
+        write_metadata(BottleMetadata(
+            identity=slug,
+            agent_name="myagent",
+            cwd="",
+            copy_cwd=False,
+            started_at="2026-06-02T00:00:00+00:00",
+            compose_project=compose_project,
+        ))
+
+    def test_smolmachines_bottle_raises_capability_apply_error(self):
+        self._write_metadata("dev", compose_project="")
+        qp = self._enqueue_capability("dev")
+        with self.assertRaises(CapabilityApplyError) as ctx:
+            dashboard.approve(qp)
+        self.assertIn("smolmachines", str(ctx.exception))
+
+    def test_docker_bottle_calls_apply_capability_change(self):
+        self._write_metadata("dev", compose_project="bot-bottle-dev")
+        qp = self._enqueue_capability("dev")
+        dashboard.approve(qp)  # must not raise
+
+    def test_no_metadata_falls_through_to_docker_path(self):
+        # No metadata at all → assume Docker (backward-compatible).
+        qp = self._enqueue_capability("dev")
+        dashboard.approve(qp)  # must not raise
+
+
 if __name__ == "__main__":
     unittest.main()

tests/unit/test_smolmachines_prepare.py

@@ -0,0 +1,133 @@
+"""Unit: smolmachines prepare.py env resolution (PRD 0038)."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+from bot_bottle.agent_provider import AgentProvisionPlan
+from bot_bottle.env import ResolvedEnv
+
+
+class TestSmolmachinesResolveEnv(unittest.TestCase):
+    """resolve_plan() must call resolve_env() and build guest_env
+    from the resolved values rather than from raw bottle.env."""
+
+    def _run_resolve_plan(
+        self,
+        resolved: ResolvedEnv,
+        *,
+        extra_host_env: dict[str, str] | None = None,
+    ) -> dict[str, str]:
+        from bot_bottle.backend import BottleSpec
+        from bot_bottle.manifest import Manifest
+
+        with tempfile.TemporaryDirectory() as tmp:
+            stage = Path(tmp) / "stage"
+            stage.mkdir()
+
+            # Minimal manifest with one env literal so the spec is valid.
+            manifest = Manifest.from_json_obj({
+                "agents": {"myagent": {"bottle": "mybottle"}},
+                "bottles": {"mybottle": {"env": {"PLAIN": "literal-value"}}},
+            })
+            spec = BottleSpec(
+                manifest=manifest,
+                agent_name="myagent",
+                copy_cwd=False,
+                user_cwd=tmp,
+                identity="test-slug-00001",
+            )
+
+            from bot_bottle import supervise as _sup
+            orig_root = _sup.bot_bottle_root
+            _sup.bot_bottle_root = lambda: Path(tmp) / ".bot-bottle"  # type: ignore[assignment]
+
+            host_env = {**os.environ, **(extra_host_env or {})}
+
+            try:
+                with (
+                    patch("bot_bottle.backend.smolmachines.prepare.resolve_env",
+                          return_value=resolved) as mock_resolve,
+                    patch("bot_bottle.backend.smolmachines.prepare.smolmachines_preflight"),
+                    patch("bot_bottle.backend.smolmachines.prepare.smolmachines_bundle_subnet",
+                          return_value=("10.99.0.0/24", "10.99.0.1", "10.99.0.2")),
+                    patch("bot_bottle.backend.smolmachines.prepare.GitGate") as mock_gg,
+                    patch("bot_bottle.backend.smolmachines.prepare.PipelockProxy") as mock_pl,
+                    patch("bot_bottle.backend.smolmachines.prepare.Egress") as mock_eg,
+                    patch("bot_bottle.backend.smolmachines.prepare.Supervise"),
+                    patch("bot_bottle.backend.smolmachines.prepare.agent_provision_plan") as mock_app,
+                    patch("bot_bottle.backend.smolmachines.prepare.runtime_for"),
+                ):
+                    mock_gg.return_value.prepare.return_value = MagicMock()
+                    mock_pl.return_value.prepare.return_value = MagicMock()
+                    mock_eg.return_value.prepare.return_value = MagicMock()
+                    def _make_provision(**kwargs):
+                        return AgentProvisionPlan(
+                            template="claude",
+                            command="claude",
+                            prompt_mode="append_file",
+                            dockerfile="",
+                            image="bot-bottle-claude:latest",
+                            guest_env=dict(kwargs.get("guest_env") or {}),
+                        )
+                    mock_app.side_effect = lambda **kw: _make_provision(**kw)
+
+                    from bot_bottle.backend.smolmachines.prepare import resolve_plan
+                    plan = resolve_plan(spec, stage_dir=stage)
+
+                mock_resolve.assert_called_once_with(manifest, "myagent")
+                return dict(plan.guest_env)
+            finally:
+                _sup.bot_bottle_root = orig_root  # type: ignore[assignment]
+
+    def test_literal_env_reaches_guest_env(self):
+        resolved = ResolvedEnv(
+            literals={"PLAIN": "hello"},
+            forwarded={},
+        )
+        guest_env = self._run_resolve_plan(resolved)
+        self.assertEqual("hello", guest_env["PLAIN"])
+
+    def test_forwarded_env_reaches_guest_env(self):
+        # Secrets / interpolated values land in forwarded; they must
+        # still reach the guest (argv exposure is the known gap).
+        resolved = ResolvedEnv(
+            literals={},
+            forwarded={"SECRET": "s3cr3t", "INTERP": "resolved-val"},
+        )
+        guest_env = self._run_resolve_plan(resolved)
+        self.assertEqual("s3cr3t", guest_env["SECRET"])
+        self.assertEqual("resolved-val", guest_env["INTERP"])
+
+    def test_raw_manifest_sentinel_not_in_guest_env(self):
+        # Before the fix, ?prompt and ${HOST} would appear verbatim.
+        # After the fix, resolve_env() is called so the caller sees
+        # the mocked resolved values (no raw sentinel survives).
+        resolved = ResolvedEnv(
+            literals={},
+            forwarded={"MY_SECRET": "actual-value"},
+        )
+        guest_env = self._run_resolve_plan(resolved)
+        for v in guest_env.values():
+            self.assertFalse(
+                v.startswith("?"),
+                f"raw secret sentinel survived in guest_env: {v!r}",
+            )
+            self.assertFalse(
+                v.startswith("${"),
+                f"raw interpolation sentinel survived in guest_env: {v!r}",
+            )
+
+    def test_tls_trust_env_always_present(self):
+        resolved = ResolvedEnv(literals={}, forwarded={})
+        guest_env = self._run_resolve_plan(resolved)
+        for key in ("NODE_EXTRA_CA_CERTS", "SSL_CERT_FILE", "REQUESTS_CA_BUNDLE"):
+            self.assertIn(key, guest_env, f"{key} missing from guest_env")
+
+
+if __name__ == "__main__":
+    unittest.main()