agentic-dev-loop 0.3.0__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-0.3.0 → agentic_dev_loop-1.0.0a2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentic-dev-loop"
-version = "0.3.0"
+version = "1.0.0a2"
 description = "Opinionated LangGraph engine for OpenHands agent pipelines"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -57,3 +57,8 @@ where = ["src"]
 
 [tool.setuptools.package-data]
 agentic_dev_loop = ["py.typed"]
+
+[tool.pytest.ini_options]
+markers = [
+    "docker: real-Docker integration tests (require a running Linux daemon)",
+]

{agentic_dev_loop-0.3.0 → agentic_dev_loop-1.0.0a2}/src/agentic_dev_loop/actions.py

@@ -30,6 +30,15 @@ def _git(args: list[str], cwd: Path) -> subprocess.CompletedProcess:
                           env=child_env())
 
 
+def _trusted_hooks_dir() -> str:
+    """The agentic-dev-loop-managed hooks dir (Q3): repo hooks in ``.git/hooks``
+    never execute during the trusted commit action. Created empty; git runs
+    with ``-c core.hooksPath=<this dir>`` so there is no hook to run."""
+    d = Path("~/.agentic-dev-loop/state/hooks").expanduser()
+    d.mkdir(parents=True, exist_ok=True)
+    return str(d)
+
+
 def git_worktree_clean(path: Path) -> bool:
     """True only when `path` is a git repo with no uncommitted changes.
     Outside a repo there is no clean baseline — False (fail-safe, keeps the
@@ -155,6 +164,28 @@ def kill_listeners_on_port(port: int, match: str | None = None,
                            shell=False, env=child_env())
 
 
+def checkpoint_exclude_pathspec(state_dir: str | None, cwd: Path) -> str | None:
+    """git pathspec excluding the live checkpoint DB from ``git add -A``.
+
+    The checkpointer keeps ``state_dir/loop-checkpoints.sqlite`` open for the
+    whole run; on Windows an open SQLite file blocks other readers, so
+    ``git add`` fails to hash it (CI-red gate failure). When the state dir
+    sits inside the repo, exclude its sqlite files (db + wal/shm) from the
+    auto-commit — checkpoint state is runtime machinery, not constructed
+    work. Returns None when there is nothing in-repo to exclude (no state
+    dir known, or it lives outside the repo).
+    """
+    if not state_dir:
+        return None
+    rel = os.path.relpath(state_dir, cwd)
+    if rel == ".." or rel.startswith(".." + os.sep):
+        return None
+    rel = rel.replace(os.sep, "/")
+    if rel == ".":
+        return ":(exclude)*.sqlite*"
+    return f":(exclude){rel}/*.sqlite*"
+
+
 def commit(state: dict, params: dict) -> dict:
     """The pipeline's only commit point. Skipped loudly when the worktree was
     dirty at run start, so the auto-commit can never swallow pre-existing
@@ -172,12 +203,24 @@ def commit(state: dict, params: dict) -> dict:
         raise ValueError("commit action requires params.message "
                          "(a template rendered with {subject})")
     cwd = Path.cwd()
-    _git(["add", "-A"], cwd=cwd)
+    hooks = _trusted_hooks_dir()
+    add_argv = ["-c", f"core.hooksPath={hooks}", "add", "-A"]
+    exclude = checkpoint_exclude_pathspec(state.get("state_dir"), cwd)
+    if exclude:
+        add_argv += ["--", exclude]
+    added = _git(add_argv, cwd=cwd)
+    if added.returncode != 0:
+        # The add is the step that touches the most files (a locked DB, a
+        # permission problem) — its error is the diagnostic that matters.
+        print(f"WARNING: [{subject}] auto-commit failed — git add: "
+              f"{added.stderr.strip()}", file=sys.stderr, flush=True)
+        return {}
     if not _git(["status", "--porcelain"], cwd=cwd).stdout.strip():
         print(f"[{subject}] Nothing to commit.", flush=True)
         return {}
     message = params["message"].format(subject=subject)
-    result = _git(["commit", "-m", message], cwd=cwd)
+    result = _git(["-c", f"core.hooksPath={hooks}", "commit", "-m", message],
+                  cwd=cwd)
     if result.returncode != 0:
         # The work is built and verified — a git error is a loud warning,
         # not a pipeline failure.

agentic_dev_loop-1.0.0a2/src/agentic_dev_loop/agents.py

@@ -0,0 +1,125 @@
+"""Agent file loading + SDK factory mechanics.
+
+The SDK's built-in tools are registered at import (its registry is global);
+consumer tools are registered by extensions via `Registry.add_tool`. Unit-3
+adds the sandbox terminal seam: `SandboxTerminalExecutor` delegates each
+terminal action to a `Sandbox.run`, and `register_sandbox_terminal` re-registers
+the `terminal` tool name per run (KD-4 / §6)."""
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from openhands.sdk import LLM
+from openhands.sdk.tool import ToolExecutor
+from openhands.tools.file_editor import FileEditorTool  # noqa: F401 — registers "file_editor"
+from openhands.tools.task_tracker import TaskTrackerTool  # noqa: F401 — registers "task_tracker"
+from openhands.tools.terminal import TerminalTool  # noqa: F401 — registers "terminal"
+
+from .isolation import SandboxExecutionRequest, command_argv, resolve_sandbox_env
+
+if TYPE_CHECKING:
+    from openhands.sdk.agent.agent import Agent
+
+    from .isolation import Sandbox
+
+
+def load_agent(agents_dir: Path | str, name: str, llm: LLM) -> "Agent":
+    """Load `<agents_dir>/<name>.agent.md` and build the Agent via the SDK
+    factory (frontmatter tool names resolved against the registry, unknown →
+    ValueError; the markdown body is delivered as the system prompt suffix).
+
+    Tool surface (BR-1): the frontmatter `tools:` list is the exact
+    capability allowlist — every name must resolve to a registered SDK tool.
+    `FinishTool` (done signal) and `ThinkTool` (reasoning scaffold) are added
+    by the SDK as default infra, never part of the allowlist and never
+    removable via `tools:`. There is no regex or default-tools knob.
+
+    Two pipeline policies on top of the SDK's native AgentDefinition loader:
+    the file must exist (fail fast — the SDK's dir loader would silently
+    skip it) and its frontmatter name must match its filename. A file with
+    no frontmatter or no name gets the SDK's stem fallback ("<name>.agent"),
+    which can never match the stem — so both degenerate cases fail the name
+    check."""
+    from openhands.sdk.subagent.registry import agent_definition_to_factory
+    from openhands.sdk.subagent.schema import AgentDefinition
+
+    path = Path(agents_dir) / f"{name}.agent.md"
+    if not path.is_file():
+        raise FileNotFoundError(f"Agent file not found: {path}")
+
+    agent_def = AgentDefinition.load(path)
+
+    stem = path.name.removesuffix(".agent.md")
+    if agent_def.name != stem:
+        raise ValueError(
+            f"Agent file {path} name {agent_def.name!r} does not match "
+            f"filename {stem!r}")
+    return agent_definition_to_factory(agent_def)(llm)
+
+
+class SandboxTerminalExecutor(ToolExecutor):
+    """A stateless terminal executor: each action is a fresh ``Sandbox.run``
+    (no persistent shell session). ``is_input`` degrades to an unsupported
+    observation; ``reset`` is a no-op (there is no session to reset)."""
+
+    def __init__(self, sandbox: "Sandbox", *, workspace: str = "",
+                 env: dict[str, str] | None = None,
+                 pipeline: str | None = None, step: str | None = None):
+        self._sandbox = sandbox
+        self._workspace = workspace
+        self._env = env or {}
+        self._pipeline = pipeline
+        self._step = step
+
+    def __call__(self, action, conversation=None):
+        from openhands.tools.terminal import TerminalObservation
+        from openhands.tools.terminal.metadata import CmdOutputMetadata
+
+        if action.reset:
+            return TerminalObservation.from_text(
+                "[reset unsupported — stateless sandbox]",
+                command=action.command, exit_code=None, timeout=False,
+                metadata=CmdOutputMetadata(exit_code=-1))
+
+        if action.is_input:
+            return TerminalObservation.from_text(
+                "[input unsupported — stateless sandbox]",
+                command=action.command, exit_code=None, timeout=False,
+                metadata=CmdOutputMetadata(exit_code=-1))
+
+        request = SandboxExecutionRequest(
+            argv=command_argv(action.command), cwd=self._workspace,
+            env=self._env, timeout=action.timeout,
+            pipeline=self._pipeline, step=self._step)
+        result = self._sandbox.run(request)
+        output = result.stdout + result.stderr
+        return TerminalObservation.from_text(
+            output, is_error=not result.succeeded and not result.is_timeout,
+            command=action.command, exit_code=result.exit_code,
+            timeout=result.timed_out,
+            metadata=CmdOutputMetadata(
+                exit_code=result.exit_code if result.exit_code is not None else -1,
+                working_dir=self._workspace))
+
+    def close(self) -> None:
+        pass  # the sandbox is closed by Runtime; idempotent
+
+
+def register_sandbox_terminal(sandbox: "Sandbox", *, env: dict[str, str | None] | None = None,
+                              workspace: str = "", pipeline: str | None = None,
+                              step: str | None = None) -> None:
+    """Per-run re-registration of the `terminal` name (KD-4): a callable
+    factory that builds the SDK terminal with a `SandboxTerminalExecutor`.
+    Pipelines are sequential, so re-registering per agent step is safe."""
+    from openhands.sdk.tool import register_tool
+
+    resolved_env = resolve_sandbox_env(env)
+
+    def factory(conv_state, **params):
+        return TerminalTool.create(
+            conv_state,
+            executor=SandboxTerminalExecutor(
+                sandbox, workspace=workspace, env=resolved_env,
+                pipeline=pipeline, step=step))
+
+    register_tool("terminal", factory)