agentic-dev-loop 1.0.0a1__tar.gz → 1.0.0a2__tar.gz

agentic_dev_loop-1.0.0a2/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: agentic-dev-loop
+Version: 1.0.0a2
+Summary: Opinionated LangGraph engine for OpenHands agent pipelines
+Author: Luke Wilson
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/lukedawilson/agentic-dev-loop
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openhands-sdk~=1.17.0
+Requires-Dist: openhands-tools~=1.17.0
+Requires-Dist: langgraph>=1.2
+Requires-Dist: langgraph-checkpoint-sqlite>=3.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.0; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# agentic-dev-loop
+
+> **Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.**
+
+Describe your pipeline in one YAML file — agent steps, mechanical test gates, and
+trusted actions — and `agentic-dev-loop` runs it end to end: agent and command steps get
+kernel-level sandboxing via Docker, verdicts route the graph, every boundary is
+checkpointed, and nothing gets committed until every gate passes.
+
+```mermaid
+flowchart LR
+    dev["agent: dev"] --> test{{"test gate"}} --> review["agent: review"] --> qa["agent: qa"] --> commit["action: commit"]
+    test -- fail --> dev
+    review -- fail --> dev
+    qa -- fail --> dev
+```
+
+- **A tool, not a wiring project.** One CLI entry point, opinionated defaults,
+  fixed safety policies. You write the pipeline and the agent definitions —
+  nothing else.
+- **Deterministic.** Same pipeline + same state → same routing. Verdicts are
+  parsed from files, retries are bounded, nothing is best-effort.
+- **Sandboxed by default.** The agent's shell and every command step run inside
+  an always-on Docker sandbox. There is no opt-out.
+
+---
+
+## Core features
+
+| Feature | What it gives you |
+| --- | --- |
+| **Stage-gated agent loop** | Agents do the work, test stages verify it, and the pipeline only advances when each stage passes its gates — looping back with full context when one fails. |
+| **Kernel-level sandboxing** | Agent work and command stages run isolated from your machine: no network access, no writes outside your workspace. No sandbox available → the run stops instead of degrading. |
+| **Crash-safe resume** | Interrupt a run at any time and pick it up later — finished stages stay finished, and you resume from exactly where it stopped. |
+| **Live graph visualisation** | Follow every run in the browser: stage status, pass/fail verdicts, retry cycles, and live console output as it happens. |
+| **Extensible** | Plug in your own actions, tools, and document loaders to adapt the loop to your projects. |
+
+The fixed policies *are* the product: fail fast on missing config/secrets, no
+silent fallbacks, verdicts only from artifacts, bounded retries, per-attempt
+artifact hygiene, a single clean-worktree-gated commit point, and no default
+LLM timeout (agent runs are long).
+
+## Installation
+
+**Prerequisites**
+
+| Requirement | Detail |
+| --- | --- |
+| Python | ≥ 3.12 |
+| Docker engine | Engine API ≥ 1.43 (Engine 24). Any compliant engine works — Docker Desktop, OrbStack, Colima, Rancher Desktop, podman docker-compat. On Windows, Linux-containers mode is required. |
+| LLM API key | The env var named by your pipeline's `api_key_env` (e.g. `OPENAI_API_KEY`) must be set — a missing key fails fast, naming it. |
+
+```bash
+pip install agentic-dev-loop==1.0.0a1   # current release (alpha — pin it explicitly)
+# or: pip install --pre agentic-dev-loop
+agentic-dev-loop --version
+```
+
+On the first run the engine pulls the **digest-pinned** dev image
+(`ghcr.io/lukedawilson/agentic-dev-loop/dev`) and verifies its digest — the
+supply-chain check refuses to continue on a mismatch. If you're running
+pre-publish tooling, point `AGENTIC_DEV_LOOP_DEV_IMAGE` at your locally built
+image. Engine setup, first-run details, the full `pipeline.yaml` contract, and
+troubleshooting for every fail-fast code live in
+[docs/setup.md](docs/setup.md).
+
+## Usage
+
+```bash
+export OPENAI_API_KEY=...                          # whatever api_key_env names
+agentic-dev-loop pipeline.yaml                     # run it
+agentic-dev-loop pipeline.yaml --dry-run           # validate first — no LLM, no Docker
+agentic-dev-loop pipeline.yaml --resume <thread-id> --max-attempts 5
+```
+
+| Flag | Effect |
+| --- | --- |
+| `--dry-run` | Full load-and-validate pass, then print the resolved plan. No LLM, no Docker, no state writes, no API key. Exit `0` on a clean load. |
+| `--resume <thread-id>` | Continue the latest checkpoint of a previous run (crash, Ctrl-C, exhaustion) with all accumulated notes intact. |
+| `--max-attempts <n>` | Override the pipeline's `max_attempts`. |
+| `--refresh` | Force re-provision of every `setup:` hook (bypasses the stamp cache). |
+| `--clean-stamps` | Delete cached provision stamps and exit. |
+| `--no-viz` / `--viz-port <port>` | Suppress the live graph view / set a preferred port (default 8321; falls back to a free port when busy). |
+| extension flags | Document-loader flags (e.g. `--plan`, `--aidlc-unit`) appear once the pipeline's extensions are loaded — `agentic-dev-loop PIPELINE --help` shows them. |
+
+Exit code is `0` on pipeline success, `1` otherwise.
+
+**What a run looks like** (the shipped self-loop example):
+
+![The live graph view — pipeline stages with verdict badges, retry cycles, and per-stage consoles](docs/viz-screenshot.png)
+
+1. **dev** — the dev agent works with full context (loaded docs + shared files).
+   Its edits are untracked; only declared `produces:` files are hygiene-tracked.
+2. **test** — a mechanical command step runs the suite inside the sandbox.
+   Exit 0 moves on; anything else rewinds to `dev` with the failing output.
+3. **review / qa** — verdict agents write artifacts whose `VERDICT:` lines route
+   the graph. `fail` rewinds to `dev` and consumes an attempt.
+4. **commit** — the single commit point fires only when all gates passed and
+   the worktree was clean at start.
+5. **success** — committed; or **failure** when attempts are exhausted.
+
+### pipeline.yaml reference
+
+```yaml
+name: my-construction-loop
+extensions:
+  - agentic_dev_loop.extensions.aidlc:AidlcExtension   # bundled AI-DLC doc loader
+additional_files:
+  - ../README.md                                       # shared context for every agent step
+
+llm:
+  model: openai/deepseek-v4-pro
+  base_url: https://api.deepseek.com
+  api_key_env: OPENAI_API_KEY
+
+max_attempts: 10                                        # CLI --max-attempts overrides
+agents_dir: sdk_agents                                  # your <name>.agent.md files
+
+steps:
+  - name: dev
+    agent: dev
+    produces: implementation-summary.md
+    on_pass: test
+
+  - name: test
+    command: .venv-sandbox/bin/python -m pytest tests/ -q -m "not docker"
+    setup: python -m venv .venv-sandbox && .venv-sandbox/bin/pip install -e ".[dev]"
+    timeout: 600
+    on_pass: review
+    on_fail: { goto: dev, retry: true }
+
+  - name: review
+    agent: review
+    artifact: review-findings.md
+    verdicts: { pass: APPROVED, fail: NEEDS CHANGES }
+    on_pass: qa
+    on_fail: { goto: dev, retry: true }
+
+  - name: qa
+    agent: qa
+    artifact: qa-report.md
+    verdicts: { pass: PASS, fail: FAIL }
+    on_pass: commit
+    on_fail: { goto: dev, retry: true }
+
+  - name: commit
+    action: commit
+    params: { message: "feat: construct {subject} (agent dev loop)" }
+```
+
+| Key | Notes |
+| --- | --- |
+| `agent:` / `command:` / `action:` | Exactly one per step. Agents live in `agents_dir` as `<name>.agent.md`; commands run sandboxed (mechanical, never an LLM call); actions are registered host-side functions. |
+| `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs verdict-parsed routing. The **last** `VERDICT:` line wins; stale artifacts are deleted at each attempt start. |
+| `on_pass:` / `on_fail:` | A step name, terminal `success`/`failure`, or `{goto: X, retry: true}`. No loops happen unless you write them. |
+| `env:` / `setup:` (command steps) | Declared env inside the sandbox (fixed safe base + declared vars only); `setup:` provisions the sandbox (network ON, stamp-cached, `--refresh` forces). |
+| `isolation:` (optional) | Configures the sandbox — image override, resource caps, `allow_git_mutations`. It can never disable it. |
+| `state_dir` | Defaults to `~/.agentic-dev-loop/runs/<pipeline-hash>/` — artifacts and checkpoints live outside the sandbox mount. |
+
+## Development environment
+
+```bash
+git clone git@github.com:lukedawilson/agentic-dev-loop.git
+cd agentic-dev-loop
+./setup-venv.sh                       # idempotent .venv setup (never touches bare pip)
+# create .env with your LLM key (loaded by trigger-agentic-dev-loop.sh, never committed):
+#   echo 'OPENAI_API_KEY=...' > .env
+python -m pytest tests/ -q            # fast suite
+python -m pytest tests/ -q -m "not docker"   # skip engine-dependent tests
+./trigger-agentic-dev-loop.sh --dry-run      # run the shipped pipeline against this repo
+./run-demo.sh                         # viz demo — scripted run replay, no pipeline needed
+```
+
+- `setup-venv.sh` is safe to re-run and picks the right interpreter even on
+  machines with exotic Python installations.
+- Docker-marked integration tests need a local daemon; CI runs them on Linux.
+- The shipped pipeline (`agentic-dev-loop/pipeline.yaml`) **dogfoods the tool on
+  its own repo** — dev → test → review → qa → commit, with the engine's own
+  three agent definitions in `sdk_agents/`.
+- CI: `ci.yml` (unit + integration suite, ubuntu + windows),
+  `publish-image.yml` (multi-arch dev image, amd64 + arm64), `release.yml`
+  (PyPI publishing).
+
+## Contributing
+
+- **Read [AGENTS.md](AGENTS.md) first** — it is the instruction set for both
+  human and agent contributors (default mode: the user drives, ask before
+  coding, TDD, no silent fallbacks).
+- Development is structured by **AI-DLC** — the lifecycle workflow in
+  `.aidlc/aidlc-rules/aws-aidlc-rules/` with working docs (plans, units, state)
+  in `aidlc-docs/`. The bundled document loader autodetects the current unit
+  from `aidlc-state.md` via `--aidlc-unit`, or load any plan with `--plan`.
+- OpenCode commands over the workflow: `/unit-status`, `/epic-status`,
+  `/ticket-details`, `/update-subtask`, `/apply-aidlc-patches`, and more.
+- Working extension samples (actions, tools, document loaders) ship as
+  `tests/sample_ext.py`.
+
+---
+
+Built on [OpenHands SDK](https://github.com/OpenHands/software-agent-sdk) and
+[LangGraph](https://github.com/langchain-ai/langgraph).

agentic_dev_loop-1.0.0a2/README.md

@@ -0,0 +1,201 @@
+# agentic-dev-loop
+
+> **Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.**
+
+Describe your pipeline in one YAML file — agent steps, mechanical test gates, and
+trusted actions — and `agentic-dev-loop` runs it end to end: agent and command steps get
+kernel-level sandboxing via Docker, verdicts route the graph, every boundary is
+checkpointed, and nothing gets committed until every gate passes.
+
+```mermaid
+flowchart LR
+    dev["agent: dev"] --> test{{"test gate"}} --> review["agent: review"] --> qa["agent: qa"] --> commit["action: commit"]
+    test -- fail --> dev
+    review -- fail --> dev
+    qa -- fail --> dev
+```
+
+- **A tool, not a wiring project.** One CLI entry point, opinionated defaults,
+  fixed safety policies. You write the pipeline and the agent definitions —
+  nothing else.
+- **Deterministic.** Same pipeline + same state → same routing. Verdicts are
+  parsed from files, retries are bounded, nothing is best-effort.
+- **Sandboxed by default.** The agent's shell and every command step run inside
+  an always-on Docker sandbox. There is no opt-out.
+
+---
+
+## Core features
+
+| Feature | What it gives you |
+| --- | --- |
+| **Stage-gated agent loop** | Agents do the work, test stages verify it, and the pipeline only advances when each stage passes its gates — looping back with full context when one fails. |
+| **Kernel-level sandboxing** | Agent work and command stages run isolated from your machine: no network access, no writes outside your workspace. No sandbox available → the run stops instead of degrading. |
+| **Crash-safe resume** | Interrupt a run at any time and pick it up later — finished stages stay finished, and you resume from exactly where it stopped. |
+| **Live graph visualisation** | Follow every run in the browser: stage status, pass/fail verdicts, retry cycles, and live console output as it happens. |
+| **Extensible** | Plug in your own actions, tools, and document loaders to adapt the loop to your projects. |
+
+The fixed policies *are* the product: fail fast on missing config/secrets, no
+silent fallbacks, verdicts only from artifacts, bounded retries, per-attempt
+artifact hygiene, a single clean-worktree-gated commit point, and no default
+LLM timeout (agent runs are long).
+
+## Installation
+
+**Prerequisites**
+
+| Requirement | Detail |
+| --- | --- |
+| Python | ≥ 3.12 |
+| Docker engine | Engine API ≥ 1.43 (Engine 24). Any compliant engine works — Docker Desktop, OrbStack, Colima, Rancher Desktop, podman docker-compat. On Windows, Linux-containers mode is required. |
+| LLM API key | The env var named by your pipeline's `api_key_env` (e.g. `OPENAI_API_KEY`) must be set — a missing key fails fast, naming it. |
+
+```bash
+pip install agentic-dev-loop==1.0.0a1   # current release (alpha — pin it explicitly)
+# or: pip install --pre agentic-dev-loop
+agentic-dev-loop --version
+```
+
+On the first run the engine pulls the **digest-pinned** dev image
+(`ghcr.io/lukedawilson/agentic-dev-loop/dev`) and verifies its digest — the
+supply-chain check refuses to continue on a mismatch. If you're running
+pre-publish tooling, point `AGENTIC_DEV_LOOP_DEV_IMAGE` at your locally built
+image. Engine setup, first-run details, the full `pipeline.yaml` contract, and
+troubleshooting for every fail-fast code live in
+[docs/setup.md](docs/setup.md).
+
+## Usage
+
+```bash
+export OPENAI_API_KEY=...                          # whatever api_key_env names
+agentic-dev-loop pipeline.yaml                     # run it
+agentic-dev-loop pipeline.yaml --dry-run           # validate first — no LLM, no Docker
+agentic-dev-loop pipeline.yaml --resume <thread-id> --max-attempts 5
+```
+
+| Flag | Effect |
+| --- | --- |
+| `--dry-run` | Full load-and-validate pass, then print the resolved plan. No LLM, no Docker, no state writes, no API key. Exit `0` on a clean load. |
+| `--resume <thread-id>` | Continue the latest checkpoint of a previous run (crash, Ctrl-C, exhaustion) with all accumulated notes intact. |
+| `--max-attempts <n>` | Override the pipeline's `max_attempts`. |
+| `--refresh` | Force re-provision of every `setup:` hook (bypasses the stamp cache). |
+| `--clean-stamps` | Delete cached provision stamps and exit. |
+| `--no-viz` / `--viz-port <port>` | Suppress the live graph view / set a preferred port (default 8321; falls back to a free port when busy). |
+| extension flags | Document-loader flags (e.g. `--plan`, `--aidlc-unit`) appear once the pipeline's extensions are loaded — `agentic-dev-loop PIPELINE --help` shows them. |
+
+Exit code is `0` on pipeline success, `1` otherwise.
+
+**What a run looks like** (the shipped self-loop example):
+
+![The live graph view — pipeline stages with verdict badges, retry cycles, and per-stage consoles](docs/viz-screenshot.png)
+
+1. **dev** — the dev agent works with full context (loaded docs + shared files).
+   Its edits are untracked; only declared `produces:` files are hygiene-tracked.
+2. **test** — a mechanical command step runs the suite inside the sandbox.
+   Exit 0 moves on; anything else rewinds to `dev` with the failing output.
+3. **review / qa** — verdict agents write artifacts whose `VERDICT:` lines route
+   the graph. `fail` rewinds to `dev` and consumes an attempt.
+4. **commit** — the single commit point fires only when all gates passed and
+   the worktree was clean at start.
+5. **success** — committed; or **failure** when attempts are exhausted.
+
+### pipeline.yaml reference
+
+```yaml
+name: my-construction-loop
+extensions:
+  - agentic_dev_loop.extensions.aidlc:AidlcExtension   # bundled AI-DLC doc loader
+additional_files:
+  - ../README.md                                       # shared context for every agent step
+
+llm:
+  model: openai/deepseek-v4-pro
+  base_url: https://api.deepseek.com
+  api_key_env: OPENAI_API_KEY
+
+max_attempts: 10                                        # CLI --max-attempts overrides
+agents_dir: sdk_agents                                  # your <name>.agent.md files
+
+steps:
+  - name: dev
+    agent: dev
+    produces: implementation-summary.md
+    on_pass: test
+
+  - name: test
+    command: .venv-sandbox/bin/python -m pytest tests/ -q -m "not docker"
+    setup: python -m venv .venv-sandbox && .venv-sandbox/bin/pip install -e ".[dev]"
+    timeout: 600
+    on_pass: review
+    on_fail: { goto: dev, retry: true }
+
+  - name: review
+    agent: review
+    artifact: review-findings.md
+    verdicts: { pass: APPROVED, fail: NEEDS CHANGES }
+    on_pass: qa
+    on_fail: { goto: dev, retry: true }
+
+  - name: qa
+    agent: qa
+    artifact: qa-report.md
+    verdicts: { pass: PASS, fail: FAIL }
+    on_pass: commit
+    on_fail: { goto: dev, retry: true }
+
+  - name: commit
+    action: commit
+    params: { message: "feat: construct {subject} (agent dev loop)" }
+```
+
+| Key | Notes |
+| --- | --- |
+| `agent:` / `command:` / `action:` | Exactly one per step. Agents live in `agents_dir` as `<name>.agent.md`; commands run sandboxed (mechanical, never an LLM call); actions are registered host-side functions. |
+| `produces:` / `artifact:` + `verdicts:` | Hygiene-tracked outputs vs verdict-parsed routing. The **last** `VERDICT:` line wins; stale artifacts are deleted at each attempt start. |
+| `on_pass:` / `on_fail:` | A step name, terminal `success`/`failure`, or `{goto: X, retry: true}`. No loops happen unless you write them. |
+| `env:` / `setup:` (command steps) | Declared env inside the sandbox (fixed safe base + declared vars only); `setup:` provisions the sandbox (network ON, stamp-cached, `--refresh` forces). |
+| `isolation:` (optional) | Configures the sandbox — image override, resource caps, `allow_git_mutations`. It can never disable it. |
+| `state_dir` | Defaults to `~/.agentic-dev-loop/runs/<pipeline-hash>/` — artifacts and checkpoints live outside the sandbox mount. |
+
+## Development environment
+
+```bash
+git clone git@github.com:lukedawilson/agentic-dev-loop.git
+cd agentic-dev-loop
+./setup-venv.sh                       # idempotent .venv setup (never touches bare pip)
+# create .env with your LLM key (loaded by trigger-agentic-dev-loop.sh, never committed):
+#   echo 'OPENAI_API_KEY=...' > .env
+python -m pytest tests/ -q            # fast suite
+python -m pytest tests/ -q -m "not docker"   # skip engine-dependent tests
+./trigger-agentic-dev-loop.sh --dry-run      # run the shipped pipeline against this repo
+./run-demo.sh                         # viz demo — scripted run replay, no pipeline needed
+```
+
+- `setup-venv.sh` is safe to re-run and picks the right interpreter even on
+  machines with exotic Python installations.
+- Docker-marked integration tests need a local daemon; CI runs them on Linux.
+- The shipped pipeline (`agentic-dev-loop/pipeline.yaml`) **dogfoods the tool on
+  its own repo** — dev → test → review → qa → commit, with the engine's own
+  three agent definitions in `sdk_agents/`.
+- CI: `ci.yml` (unit + integration suite, ubuntu + windows),
+  `publish-image.yml` (multi-arch dev image, amd64 + arm64), `release.yml`
+  (PyPI publishing).
+
+## Contributing
+
+- **Read [AGENTS.md](AGENTS.md) first** — it is the instruction set for both
+  human and agent contributors (default mode: the user drives, ask before
+  coding, TDD, no silent fallbacks).
+- Development is structured by **AI-DLC** — the lifecycle workflow in
+  `.aidlc/aidlc-rules/aws-aidlc-rules/` with working docs (plans, units, state)
+  in `aidlc-docs/`. The bundled document loader autodetects the current unit
+  from `aidlc-state.md` via `--aidlc-unit`, or load any plan with `--plan`.
+- OpenCode commands over the workflow: `/unit-status`, `/epic-status`,
+  `/ticket-details`, `/update-subtask`, `/apply-aidlc-patches`, and more.
+- Working extension samples (actions, tools, document loaders) ship as
+  `tests/sample_ext.py`.
+
+---
+
+Built on [OpenHands SDK](https://github.com/OpenHands/software-agent-sdk) and
+[LangGraph](https://github.com/langchain-ai/langgraph).

{agentic_dev_loop-1.0.0a1 → agentic_dev_loop-1.0.0a2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentic-dev-loop"
-version = "1.0.0a1"
+version = "1.0.0a2"
 description = "Opinionated LangGraph engine for OpenHands agent pipelines"
 readme = "README.md"
 requires-python = ">=3.12"

{agentic_dev_loop-1.0.0a1 → agentic_dev_loop-1.0.0a2}/src/agentic_dev_loop/isolation.py

@@ -282,12 +282,14 @@ def host_user_flag() -> str | None:
 
 def docker_create_payload(*, run_id: str, image: str, profile: EffectiveProfile,
                           workspace: str) -> list[str]:
-    """Exact ``docker create`` argv for the execution container (§3.3, KD-8).
+    """Exact ``docker run -d --rm`` argv for the execution container (§3.3, KD-8).
     Single mount {workspace} (Q1); --network none, --read-only, --cap-drop ALL;
     --user host uid:gid (host-owned bind mounts, AE-SBX-009 root cause) with
-    HOME=/tmp (the rootfs is read-only; /tmp is a 1777 tmpfs)."""
+    HOME=/tmp (the rootfs is read-only; /tmp is a 1777 tmpfs). ``--rm`` lets the
+    daemon auto-remove the container the instant it exits, however it exits
+    (D1) — a SIGKILLed CLI never reaches close()."""
     payload = [
-        "docker", "create", "--name", f"{run_id}-exec",
+        "docker", "run", "--detach", "--rm", "--name", f"{run_id}-exec",
         "--network", "none", "--read-only", "--cap-drop", "ALL",
         "--memory", profile.memory, "--cpus", str(profile.cpus),
         "--tmpfs", "/tmp", "--tmpfs", "/root",
@@ -452,20 +454,17 @@ class DockerBackend(Sandbox):
         self._verify_digest()
 
     def create_execution_container(self) -> None:
-        """Eager create + start (Q2) — never lazy."""
+        """Eager create + start via ``docker run -d --rm`` (Q2, D1) — never
+        lazy; ``run -d`` is create + start in one call, so there is no
+        separate ``docker start``."""
         payload = docker_create_payload(
             run_id=self._run_id, image=self._image, profile=self._profile,
             workspace=self._workspace)
-        create = self._runner.run(payload, timeout=60)
-        if create.exit_code != 0:
-            raise SandboxError(
-                f"AE-SBX-010: container create failed: "
-                f"{create.stderr.strip() or create.stdout.strip()}")
-        start = self._runner.run(["docker", "start", self._container], timeout=60)
-        if start.exit_code != 0:
+        res = self._runner.run(payload, timeout=60)
+        if res.exit_code != 0:
             raise SandboxError(
-                f"AE-SBX-010: container start failed: "
-                f"{start.stderr.strip() or start.stdout.strip()}")
+                f"AE-SBX-010: container run failed: "
+                f"{res.stderr.strip() or res.stdout.strip()}")
         self._started = True
 
     def provision(self, setup_cmd: str, stamp_key: str, stamp_dir: str,
@@ -513,10 +512,14 @@ class DockerBackend(Sandbox):
         return result
 
     def close(self) -> None:
-        """Best-effort stop + rm; idempotent (BR-8.3)."""
+        """Best-effort stop + rm; idempotent (BR-8.3). With ``--rm`` the
+        daemon may already have auto-removed the container by the time close()
+        runs, so a nonzero stop/rm exit code ("no such container") is treated
+        as success, never raised (D2)."""
         if not self._started:
             return
         self._runner.run(["docker", "stop", "-t", "5", self._container], timeout=60)
+        # rm -f returns rc != 0 when --rm already removed it — ignore, never raise.
         self._runner.run(["docker", "rm", "-f", self._container], timeout=60)
         self._started = False
 
@@ -639,7 +642,7 @@ def clean_stamps(state_dir: Path) -> int:
 
 
 # ---------------------------------------------------------------------------
-# Eager startup (Q2) — probe → image → create/start → provision all setups
+# Eager startup (Q2) — probe → image → run -d --rm → provision all setups
 # ---------------------------------------------------------------------------
 
 _LOCKFILE_NAMES = ("package-lock.json", "requirements.txt")