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

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?