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

@@ -0,0 +1,87 @@
+# PRD 0039: smolmachines Capability-Block Remediation
+
+- **Status:** Draft
+- **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?