cleveragents/cleveragents-core

Fork 3

UAT: `stop_container()` hardcodes `docker stop` — Podman and other container engines are not supported, violating the multi-engine container spec #2151

New issue

Open

opened 2026-04-03 04:28:23 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 04:28:23 +00:00

Owner

Metadata

Branch: fix/container-stop-engine-dispatch
Commit Message: fix(resource): dispatch container stop to correct engine type
Milestone: v3.7.0
Parent Epic: #825

Bug Report

What Was Tested

The container stop mechanism in stop_container() for non-Docker container engines.

Expected Behavior (from spec)

Per ADR-039 (Container Resource Types), the system supports multiple container engines:

Docker
Podman
containerd
LXC/LXD
CRI-O

The container-runtime resource type has an engine-type field that specifies which engine is in use. The spec's container integration should respect the configured engine type when performing operations like stopping containers.

Per docs/specification.md line 43751:

devcontainer CLI (optional) — Used for building and managing devcontainer-instance resources from .devcontainer/devcontainer.json configurations. Falls back to direct Docker/Podman CLI when not installed, with reduced feature support.

The spec acknowledges multiple engines and the devcontainer CLI's ability to target different engines.

Actual Behavior (from code)

In src/cleveragents/resource/handlers/devcontainer_lifecycle.py lines 350-370:

container_id = tracker.container_id
if container_id:
    result = runner(
        ["docker", "stop", container_id],  # Hardcoded to docker!
        ...
    )

The stop_container() function always calls docker stop regardless of the container engine configured for the resource. This means:

Podman users cannot stop their devcontainers via agents resource stop
The engine_type field on container-runtime resources is ignored during stop operations
Users running Podman-based devcontainers will get docker: command not found errors

Root Cause

The stop_container() function was implemented with a hardcoded docker stop call. The devcontainer CLI does not yet offer a stop subcommand, so the implementation bypassed the CLI and called Docker directly, without considering other engines.

Code Location

src/cleveragents/resource/handlers/devcontainer_lifecycle.py, line 352: ["docker", "stop", container_id]
src/cleveragents/resource/handlers/devcontainer_lifecycle.py, line 270: ["docker", "stop", cid] (orphan cleanup)
docs/reference/devcontainer_resources.md, line 252: Known limitation "Hardcoded docker stop (F21)"

Steps to Reproduce

Configure a Podman-based devcontainer (set engine_type: podman on the container-runtime)
Activate the devcontainer
Attempt to stop: agents resource stop local/my-dc
Observe: docker: command not found error (or incorrect behavior if Docker is also installed)

Severity

Medium — Affects users running Podman or other non-Docker container engines. Docker is the most common engine, so this does not affect the majority of users, but it is a spec violation for multi-engine support.

Subtasks

Read the engine_type from the resource's container-runtime parent (or resource properties)
Dispatch to the appropriate stop command based on engine type (docker stop, podman stop, etc.)
Handle the case where the devcontainer CLI offers a stop subcommand in future versions
Add unit tests for stop with different engine types
Remove the "Hardcoded docker stop (F21)" known limitation from docs/reference/devcontainer_resources.md

Definition of Done

stop_container() dispatches to the correct engine-specific stop command
Podman users can stop devcontainers via agents resource stop
All existing tests continue to pass
The associated PR is merged
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/container-stop-engine-dispatch` - **Commit Message**: `fix(resource): dispatch container stop to correct engine type` - **Milestone**: v3.7.0 - **Parent Epic**: #825 ## Bug Report ### What Was Tested The container stop mechanism in `stop_container()` for non-Docker container engines. ### Expected Behavior (from spec) Per ADR-039 (Container Resource Types), the system supports multiple container engines: - Docker - Podman - containerd - LXC/LXD - CRI-O The `container-runtime` resource type has an `engine-type` field that specifies which engine is in use. The spec's container integration should respect the configured engine type when performing operations like stopping containers. Per `docs/specification.md` line 43751: > **devcontainer CLI** (optional) — Used for building and managing `devcontainer-instance` resources from `.devcontainer/devcontainer.json` configurations. Falls back to direct Docker/Podman CLI when not installed, with reduced feature support. The spec acknowledges multiple engines and the devcontainer CLI's ability to target different engines. ### Actual Behavior (from code) In `src/cleveragents/resource/handlers/devcontainer_lifecycle.py` lines 350-370: ```python container_id = tracker.container_id if container_id: result = runner( ["docker", "stop", container_id], # Hardcoded to docker! ... ) ``` The `stop_container()` function always calls `docker stop` regardless of the container engine configured for the resource. This means: 1. Podman users cannot stop their devcontainers via `agents resource stop` 2. The `engine_type` field on `container-runtime` resources is ignored during stop operations 3. Users running Podman-based devcontainers will get `docker: command not found` errors ### Root Cause The `stop_container()` function was implemented with a hardcoded `docker stop` call. The devcontainer CLI does not yet offer a `stop` subcommand, so the implementation bypassed the CLI and called Docker directly, without considering other engines. ### Code Location - `src/cleveragents/resource/handlers/devcontainer_lifecycle.py`, line 352: `["docker", "stop", container_id]` - `src/cleveragents/resource/handlers/devcontainer_lifecycle.py`, line 270: `["docker", "stop", cid]` (orphan cleanup) - `docs/reference/devcontainer_resources.md`, line 252: Known limitation "Hardcoded `docker stop` (F21)" ### Steps to Reproduce 1. Configure a Podman-based devcontainer (set `engine_type: podman` on the container-runtime) 2. Activate the devcontainer 3. Attempt to stop: `agents resource stop local/my-dc` 4. Observe: `docker: command not found` error (or incorrect behavior if Docker is also installed) ### Severity **Medium** — Affects users running Podman or other non-Docker container engines. Docker is the most common engine, so this does not affect the majority of users, but it is a spec violation for multi-engine support. ## Subtasks - [ ] Read the `engine_type` from the resource's `container-runtime` parent (or resource properties) - [ ] Dispatch to the appropriate stop command based on engine type (`docker stop`, `podman stop`, etc.) - [ ] Handle the case where the devcontainer CLI offers a stop subcommand in future versions - [ ] Add unit tests for stop with different engine types - [ ] Remove the "Hardcoded `docker stop` (F21)" known limitation from `docs/reference/devcontainer_resources.md` ## Definition of Done - [ ] `stop_container()` dispatches to the correct engine-specific stop command - [ ] Podman users can stop devcontainers via `agents resource stop` - [ ] All existing tests continue to pass - [ ] The associated PR is merged - All nox stages pass - Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.7.0 milestone

2026-04-03 04:28:28 +00:00

freemo added a new dependency

2026-04-03 04:29:15 +00:00

#825 Epic: ResourceHandler Protocol Completion

freemo referenced this issue

2026-04-03 04:29:51 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo referenced this issue

2026-04-03 04:31:47 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 731 — v3.7.0 #2157

freemo referenced this issue

2026-04-03 04:32:08 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo referenced this issue

2026-04-03 04:41:54 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 741 — v3.7.0 #2169

freemo referenced this issue

2026-04-03 04:52:01 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 751 — v3.7.0 #2171

freemo referenced this issue

2026-04-03 05:02:08 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 761 — v3.7.0 #2172

freemo referenced this issue

2026-04-03 05:12:16 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 771 — v3.7.0 #2173

freemo referenced this issue

2026-04-03 05:22:23 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 781 — v3.7.0 #2174

freemo referenced this issue

2026-04-03 05:32:30 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 791 — v3.7.0 #2175

freemo referenced this issue

2026-04-03 05:42:37 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 801 — v3.7.0 #2176

freemo referenced this issue

2026-04-03 05:52:45 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 811 — v3.7.0 #2177

freemo referenced this issue

2026-04-03 06:02:54 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 821 — v3.7.0 #2179

freemo referenced this issue

2026-04-03 06:13:02 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 831 — v3.7.0 #2182

freemo referenced this issue

2026-04-03 06:23:09 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 841 — v3.7.0 #2183

freemo referenced this issue

2026-04-03 06:33:17 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 851 — v3.7.0 #2184

freemo referenced this issue

2026-04-03 06:43:24 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 861 — v3.7.0 #2185

freemo referenced this issue

2026-04-03 06:53:32 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 871 — v3.7.0 #2186

freemo referenced this issue

2026-04-03 07:03:41 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 881 — v3.7.0 #2187

freemo referenced this issue

2026-04-03 07:13:49 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 891 — v3.7.0 #2188

freemo referenced this issue

2026-04-03 07:23:59 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 901 — v3.7.0 #2189

freemo referenced this issue

2026-04-03 07:34:09 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 911 — v3.7.0 #2190

freemo referenced this issue

2026-04-03 07:44:17 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 921 — v3.7.0 #2191

freemo referenced this issue

2026-04-03 07:54:24 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 931 — v3.7.0 #2192

freemo referenced this issue

2026-04-03 08:04:32 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 941 — v3.7.0 #2193

freemo referenced this issue

2026-04-03 08:14:40 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 951 — v3.7.0 #2194

freemo referenced this issue

2026-04-03 08:24:51 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 961 — v3.7.0 #2195

freemo referenced this issue

2026-04-03 08:35:00 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 971 — v3.7.0 #2196

freemo referenced this issue

2026-04-03 08:45:10 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 981 — v3.7.0 #2197

freemo referenced this issue

2026-04-03 08:55:18 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 991 — v3.7.0 #2198

freemo referenced this issue

2026-04-03 09:05:29 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1001 — v3.7.0 #2199

freemo referenced this issue

2026-04-03 09:15:36 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1011 — v3.7.0 #2200

freemo referenced this issue

2026-04-03 09:25:44 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 1021 — v3.7.0 #2201

freemo self-assigned this

2026-04-03 16:58:01 +00:00

freemo commented

2026-04-03 18:27:32 +00:00

Author

Owner

MoSCoW classification: Should Have

Rationale: This issue addresses an important spec requirement or quality improvement. The project should include this fix but it is not strictly essential for the milestone.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

MoSCoW classification: **Should Have** Rationale: This issue addresses an important spec requirement or quality improvement. The project should include this fix but it is not strictly essential for the milestone. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo removed this from the v3.7.0 milestone

2026-04-07 01:19:46 +00:00