agentic-dev-loop 1.0.0a8__tar.gz → 1.0.0a10__tar.gz

{agentic_dev_loop-1.0.0a8 → agentic_dev_loop-1.0.0a10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a8
+Version: 1.0.0a10
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -90,10 +90,27 @@ LLM timeout (agent runs are long).
 | 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.0a8"
+pip install "agentic-dev-loop==1.0.0a9"
 agentic-dev-loop --version
 ```
 
+The canonical consumer install is **pipx**, which puts the engine's venv
+*outside* the workspace — the sandbox mount set is exactly `{workspace}`, so an
+out-of-workspace install is unmounted and never agent-writable:
+
+```bash
+pipx install "agentic-dev-loop==1.0.0a9"
+```
+
+If you install with `uv` shortly after a release, pass `--refresh` — PyPI
+serves the package index with `Cache-Control: max-age=600`, and uv otherwise
+reuses a pre-upload snapshot of the index for up to 10 minutes, reporting
+"no version of agentic-dev-loop==X.Y.Z" for a version that is already live:
+
+```bash
+uv pip install --refresh "agentic-dev-loop==1.0.0a9"
+```
+
 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
@@ -188,12 +205,53 @@ steps:
 
 | 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. |
+| `agent:` / `command:` / `action:` | Exactly one per step. Agents live in `agents_dir` as `<name>.agent.md`; commands run sandboxed (mechanical, never an LLM call). `commit` is the sole host-side built-in action; consumer actions are sandbox-executed, command-shaped scripts (see [Host boundary](#host-boundary-security-model)). |
 | `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:` / `network:` | `env:` declares step vars (fixed safe base + declared vars only); `setup:` provisions the sandbox (command steps, network ON, stamp-cached); `network: true` grants egress to a command or agent step (default off) — see [Per-stage networking](#per-stage-networking). |
+| `secrets:` (top-level) / step `secrets:` | Declares secret **refs only — never values**; each step opts in to the refs it needs. Resolved host-side and injected into that step's exec env only. See [Secrets](#secrets--refs-only-never-values). |
 | `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. |
+| `extensions_dir` | Where consumer `extensions:` modules resolve — defaults to `~/.agentic-dev-loop/extensions`, **outside** the workspace. Workspace-resident extension/tool modules are refused at load. |
+
+### Secrets (`secrets:`) — refs only, never values
+
+Secret values never belong in the pipeline yaml, the workspace, or `state_dir`.
+Declare the refs at the top level and opt each step into the refs it needs:
+
+```yaml
+secrets:                              # refs only — never values
+  kinde-client-secret:                # ref name (arbitrary)
+    from: env                         # provider name
+    key: KINDIE_CLIENT_SECRET         # provider-specific locator
+  r2-keys:
+    from: env
+    key: YOSK_R2_KEYS
+
+steps:
+  - name: qa
+    agent: qa
+    secrets: [kinde-client-secret, r2-keys]
+```
+
+- The engine resolves every declared ref **host-side at run start** (the `env`
+  provider reads the named host environment variable). A missing variable, an
+  unknown provider, or a ref a step lists without declaring it fails fast —
+  naming the ref, the step, and the provider error. No silent fallback.
+- A resolved secret is injected into a step's exec env **only when that step
+  lists the ref** — the same path step `env:` uses, no new channel. The secret
+  never reaches the provision container, `state_dir`, or any other step.
+- Prefer a mechanical `command` step for secret-consuming work (a script runs
+  the app with creds) so the LLM and the secret never meet; an `agent` step
+  holds a secret only when its job genuinely requires it.
+- **`.env*` ban.** At run start the workspace root is scanned for `.env*`
+  files. Any hit fails fast, naming the files, with the remedy text. The
+  convention fixtures `.env.example`, `.env.template`, and `.env.sample` are
+  whitelisted. This applies regardless of `network:` flags.
+- **Output scrubbing.** Resolved secret values are scrubbed from every
+  engine-written output — captured step output, retry notes, artifacts, and
+  `state_dir` files. (Hygiene: the declaring step's agent has already seen
+  the value in its own env.)
 
 ### Per-stage networking
 
@@ -213,29 +271,79 @@ steps:
   sandbox container (`--read-only`, `--cap-drop ALL`, single workspace mount)
   on the Docker bridge network — the default network-none container is always
   created too, so no infrastructure work happens mid-run.
-- **Command and agent steps** may declare it. Action steps are host-side and
-  never take it (a load-time error).
+- **Command, agent, and sandbox-action steps** may declare it. The host-side
+  built-in `commit` action never takes it (refused once the registry is known).
 - **Author opt-in is the control.** A networked step gives its agent raw
   egress for that stage; the default stays network-off everywhere. Reserve it
   for stages that need it (QA, integration). The residual risk is documented
   in [docs/setup.md](docs/setup.md).
 
+## Host boundary (security model)
+
+The orchestrator, tool layer, and the `commit` action run in the **host
+process** — they hold your credentials and your full user account, so the
+engine keeps anything agent-writable out of that process:
+
+- **Consumer actions are sandbox-executed.** An action you register via an
+  extension is a command-shaped script (`script + params`), run through the
+  same sandbox path as command steps — the exit code is the verdict, and the
+  code never runs in the host. Only the engine's trusted built-ins (`commit`,
+  document loaders) run host-side.
+- **Extensions load from outside the workspace.** `extensions_dir` defaults to
+  `~/.agentic-dev-loop/extensions`; at load time any extension or tool module
+  whose file resolves under the workspace is refused *before import*, naming
+  the file.
+- **The engine installs outside the workspace.** Install with pipx so the venv
+  is unmounted from the sandbox; a startup self-check refuses to run if
+  `agentic_dev_loop` resolves under the workspace (an editable install bypasses
+  everything).
+- **Tooling is read-only by the loop.** At run start the pipeline file,
+  `agents_dir`, `additional_files`, `aidlc-docs/`, and `tools/` must be
+  git-clean relative to HEAD — otherwise the run refuses, naming the dirty
+  files. The `commit` action excludes those paths from its sweep, so the loop
+  never commits its own tooling.
+- **`commit` stays host-side, deliberately.** It holds push credentials; moving
+  it into the sandbox would trade host-exec-of-trusted-code for
+  credential-in-sandbox. It runs argv-style with a scrubbed child env and
+  `-c core.hooksPath=~/.agentic-dev-loop/state/hooks` so repo hooks never
+  execute.
+
+Net: the host executes nothing from the workspace, reads only git-clean
+control files, and the only agent-writable host-consumed thing left is the code
+the loop is building.
+
+### Consumer migration notes
+
+- **Actions** — replace a host-side `fn` registration with
+  `registry.add_sandbox_action(name, script)`. `script` is a command string
+  rendered with the step's `params:` plus `{subject}`; the exit code is the
+  verdict. `add_action` (host-side) is now engine-built-in-only and is refused
+  from extensions.
+- **Extensions** — move workspace-resident extension modules (e.g.
+  `extensions/*.py`) into `~/.agentic-dev-loop/extensions/` (or whatever
+  `extensions_dir:` names), and reinstall the engine via pipx so it is not
+  editable/in-workspace.
+- **Tooling** — commit the pipeline, agent defs, shared `additional_files`,
+  `aidlc-docs/`, and `tools/` before running: the run refuses dirty tooling,
+  and `commit` never commits it.
+
 ## 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
+pipx install "agentic-dev-loop==1.0.0a9"   # engine venv OUTSIDE the workspace (self-check)
+export OPENAI_API_KEY=...           # set your LLM key in the host env (no .env in the repo)
+python -m pytest tests/ -q            # fast suite (in-repo .venv is for tests only)
 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
+agentic-dev-loop agentic-dev-loop/pipeline.yaml --dry-run   # run the shipped pipeline
 ./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.
+- `setup-venv.sh` builds the throwaway `.venv` for local `pytest` runs (the
+  pipeline's `test` step provisions its own `.venv-sandbox` inside the
+  sandbox). The loop itself must run from the pipx install — never an
+  in-workspace `.venv`, which the startup self-check refuses.
 - 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

{agentic_dev_loop-1.0.0a8 → agentic_dev_loop-1.0.0a10}/README.md

@@ -51,10 +51,27 @@ LLM timeout (agent runs are long).
 | 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.0a8"
+pip install "agentic-dev-loop==1.0.0a9"
 agentic-dev-loop --version
 ```
 
+The canonical consumer install is **pipx**, which puts the engine's venv
+*outside* the workspace — the sandbox mount set is exactly `{workspace}`, so an
+out-of-workspace install is unmounted and never agent-writable:
+
+```bash
+pipx install "agentic-dev-loop==1.0.0a9"
+```
+
+If you install with `uv` shortly after a release, pass `--refresh` — PyPI
+serves the package index with `Cache-Control: max-age=600`, and uv otherwise
+reuses a pre-upload snapshot of the index for up to 10 minutes, reporting
+"no version of agentic-dev-loop==X.Y.Z" for a version that is already live:
+
+```bash
+uv pip install --refresh "agentic-dev-loop==1.0.0a9"
+```
+
 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
@@ -149,12 +166,53 @@ steps:
 
 | 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. |
+| `agent:` / `command:` / `action:` | Exactly one per step. Agents live in `agents_dir` as `<name>.agent.md`; commands run sandboxed (mechanical, never an LLM call). `commit` is the sole host-side built-in action; consumer actions are sandbox-executed, command-shaped scripts (see [Host boundary](#host-boundary-security-model)). |
 | `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:` / `network:` | `env:` declares step vars (fixed safe base + declared vars only); `setup:` provisions the sandbox (command steps, network ON, stamp-cached); `network: true` grants egress to a command or agent step (default off) — see [Per-stage networking](#per-stage-networking). |
+| `secrets:` (top-level) / step `secrets:` | Declares secret **refs only — never values**; each step opts in to the refs it needs. Resolved host-side and injected into that step's exec env only. See [Secrets](#secrets--refs-only-never-values). |
 | `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. |
+| `extensions_dir` | Where consumer `extensions:` modules resolve — defaults to `~/.agentic-dev-loop/extensions`, **outside** the workspace. Workspace-resident extension/tool modules are refused at load. |
+
+### Secrets (`secrets:`) — refs only, never values
+
+Secret values never belong in the pipeline yaml, the workspace, or `state_dir`.
+Declare the refs at the top level and opt each step into the refs it needs:
+
+```yaml
+secrets:                              # refs only — never values
+  kinde-client-secret:                # ref name (arbitrary)
+    from: env                         # provider name
+    key: KINDIE_CLIENT_SECRET         # provider-specific locator
+  r2-keys:
+    from: env
+    key: YOSK_R2_KEYS
+
+steps:
+  - name: qa
+    agent: qa
+    secrets: [kinde-client-secret, r2-keys]
+```
+
+- The engine resolves every declared ref **host-side at run start** (the `env`
+  provider reads the named host environment variable). A missing variable, an
+  unknown provider, or a ref a step lists without declaring it fails fast —
+  naming the ref, the step, and the provider error. No silent fallback.
+- A resolved secret is injected into a step's exec env **only when that step
+  lists the ref** — the same path step `env:` uses, no new channel. The secret
+  never reaches the provision container, `state_dir`, or any other step.
+- Prefer a mechanical `command` step for secret-consuming work (a script runs
+  the app with creds) so the LLM and the secret never meet; an `agent` step
+  holds a secret only when its job genuinely requires it.
+- **`.env*` ban.** At run start the workspace root is scanned for `.env*`
+  files. Any hit fails fast, naming the files, with the remedy text. The
+  convention fixtures `.env.example`, `.env.template`, and `.env.sample` are
+  whitelisted. This applies regardless of `network:` flags.
+- **Output scrubbing.** Resolved secret values are scrubbed from every
+  engine-written output — captured step output, retry notes, artifacts, and
+  `state_dir` files. (Hygiene: the declaring step's agent has already seen
+  the value in its own env.)
 
 ### Per-stage networking
 
@@ -174,29 +232,79 @@ steps:
   sandbox container (`--read-only`, `--cap-drop ALL`, single workspace mount)
   on the Docker bridge network — the default network-none container is always
   created too, so no infrastructure work happens mid-run.
-- **Command and agent steps** may declare it. Action steps are host-side and
-  never take it (a load-time error).
+- **Command, agent, and sandbox-action steps** may declare it. The host-side
+  built-in `commit` action never takes it (refused once the registry is known).
 - **Author opt-in is the control.** A networked step gives its agent raw
   egress for that stage; the default stays network-off everywhere. Reserve it
   for stages that need it (QA, integration). The residual risk is documented
   in [docs/setup.md](docs/setup.md).
 
+## Host boundary (security model)
+
+The orchestrator, tool layer, and the `commit` action run in the **host
+process** — they hold your credentials and your full user account, so the
+engine keeps anything agent-writable out of that process:
+
+- **Consumer actions are sandbox-executed.** An action you register via an
+  extension is a command-shaped script (`script + params`), run through the
+  same sandbox path as command steps — the exit code is the verdict, and the
+  code never runs in the host. Only the engine's trusted built-ins (`commit`,
+  document loaders) run host-side.
+- **Extensions load from outside the workspace.** `extensions_dir` defaults to
+  `~/.agentic-dev-loop/extensions`; at load time any extension or tool module
+  whose file resolves under the workspace is refused *before import*, naming
+  the file.
+- **The engine installs outside the workspace.** Install with pipx so the venv
+  is unmounted from the sandbox; a startup self-check refuses to run if
+  `agentic_dev_loop` resolves under the workspace (an editable install bypasses
+  everything).
+- **Tooling is read-only by the loop.** At run start the pipeline file,
+  `agents_dir`, `additional_files`, `aidlc-docs/`, and `tools/` must be
+  git-clean relative to HEAD — otherwise the run refuses, naming the dirty
+  files. The `commit` action excludes those paths from its sweep, so the loop
+  never commits its own tooling.
+- **`commit` stays host-side, deliberately.** It holds push credentials; moving
+  it into the sandbox would trade host-exec-of-trusted-code for
+  credential-in-sandbox. It runs argv-style with a scrubbed child env and
+  `-c core.hooksPath=~/.agentic-dev-loop/state/hooks` so repo hooks never
+  execute.
+
+Net: the host executes nothing from the workspace, reads only git-clean
+control files, and the only agent-writable host-consumed thing left is the code
+the loop is building.
+
+### Consumer migration notes
+
+- **Actions** — replace a host-side `fn` registration with
+  `registry.add_sandbox_action(name, script)`. `script` is a command string
+  rendered with the step's `params:` plus `{subject}`; the exit code is the
+  verdict. `add_action` (host-side) is now engine-built-in-only and is refused
+  from extensions.
+- **Extensions** — move workspace-resident extension modules (e.g.
+  `extensions/*.py`) into `~/.agentic-dev-loop/extensions/` (or whatever
+  `extensions_dir:` names), and reinstall the engine via pipx so it is not
+  editable/in-workspace.
+- **Tooling** — commit the pipeline, agent defs, shared `additional_files`,
+  `aidlc-docs/`, and `tools/` before running: the run refuses dirty tooling,
+  and `commit` never commits it.
+
 ## 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
+pipx install "agentic-dev-loop==1.0.0a9"   # engine venv OUTSIDE the workspace (self-check)
+export OPENAI_API_KEY=...           # set your LLM key in the host env (no .env in the repo)
+python -m pytest tests/ -q            # fast suite (in-repo .venv is for tests only)
 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
+agentic-dev-loop agentic-dev-loop/pipeline.yaml --dry-run   # run the shipped pipeline
 ./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.
+- `setup-venv.sh` builds the throwaway `.venv` for local `pytest` runs (the
+  pipeline's `test` step provisions its own `.venv-sandbox` inside the
+  sandbox). The loop itself must run from the pipx install — never an
+  in-workspace `.venv`, which the startup self-check refuses.
 - 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

{agentic_dev_loop-1.0.0a8 → agentic_dev_loop-1.0.0a10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentic-dev-loop"
-version = "1.0.0a8"
+version = "1.0.0a10"
 description = "Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase."
 readme = "README.md"
 requires-python = ">=3.12"

{agentic_dev_loop-1.0.0a8 → agentic_dev_loop-1.0.0a10}/src/agentic_dev_loop/core/config.py

@@ -11,6 +11,7 @@ import yaml
 from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
 TERMINALS = frozenset({"success", "failure"})
+KNOWN_SECRET_PROVIDERS = frozenset({"env"})
 
 
 class VerdictSpec(BaseModel):
@@ -36,6 +37,34 @@ def route_target(route: RouteTarget | None) -> str | None:
     return route.goto if isinstance(route, Route) else route
 
 
+class SecretSpec(BaseModel):
+    """One ``secrets:`` ref — the locator only, never a value. ``from`` names
+    the provider (``env`` first); ``key`` is that provider's locator (for
+    ``env``, the host environment variable to read and the step env name to
+    inject). Unknown keys fail at load (extra="forbid")."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    from_: str = Field(alias="from")
+    key: str
+
+    @field_validator("from_")
+    @classmethod
+    def _known_provider(cls, v: str) -> str:
+        if v not in KNOWN_SECRET_PROVIDERS:
+            raise ValueError(
+                f"unknown secret provider {v!r} (known: "
+                f"{sorted(KNOWN_SECRET_PROVIDERS)})")
+        return v
+
+    @field_validator("key")
+    @classmethod
+    def _nonempty_key(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("secret key must be a non-empty string")
+        return v
+
+
 class IsolationConfig(BaseModel):
     """Optional `isolation:` section — configures the always-on sandbox (BR-2).
     Absence means opinionated defaults, never unsandboxed behaviour. Unknown
@@ -85,7 +114,8 @@ class StepConfig(BaseModel):
     timeout: float | None = Field(default=None, gt=0)  # seconds, command steps only
     env: dict[str, str | None] | None = None  # NFR-1: null = inherit host value
     setup: str | None = None  # BR-13: command steps only
-    network: bool = False  # per-stage egress (command + agent steps; action steps reject)
+    network: bool = False  # per-stage egress (command/agent + sandbox actions; host-side actions reject at registry time)
+    secrets: list[str] = []  # declared ref names; action steps reject
     on_pass: RouteTarget | None = None
     on_fail: RouteTarget | None = None
 
@@ -143,9 +173,14 @@ class StepConfig(BaseModel):
             raise ValueError(
                 f"step {self.name!r}: 'setup' is only allowed on 'command' steps"
             )
-        if self.network and self.action is not None:
+        # `network` is NOT rejected here: the schema can't tell a host-side
+        # built-in action (e.g. `commit`, which must never take egress) from
+        # a sandbox-executed consumer action (which may, like a command step).
+        # That distinction is enforced once the registry is known — see
+        # `validate_action_network` (020).
+        if self.secrets and self.action is not None:
             raise ValueError(
-                f"step {self.name!r}: 'network' is only allowed on 'agent' or "
+                f"step {self.name!r}: 'secrets' is only allowed on 'agent' or "
                 "'command' steps"
             )
         return self
@@ -166,14 +201,37 @@ class PipelineConfig(BaseModel):
     name: str
     extensions: list[str] = []
     additional_files: list[str] = []
+    # Where consumer `extensions:` modules resolve (work item 020). Must live
+    # OUTSIDE the workspace — the host refuses workspace-resident extension and
+    # tool-handler modules, so agent-writable files are never imported by the
+    # host process.
+    extensions_dir: str = "~/.agentic-dev-loop/extensions"
     env_allowlist: list[str] = []
     llm: LlmConfig
     isolation: IsolationConfig | None = None  # None = always-on defaults
     state_dir: str = ".pr"  # default relocated to ~/.agentic-dev-loop/runs/<hash>/ at load
+    secrets: dict[str, SecretSpec] = {}  # ref name -> locator; values never appear here
     max_attempts: int = 3
     agents_dir: str
     steps: list[StepConfig] = Field(min_length=1)
 
+    @field_validator("secrets", mode="before")
+    @classmethod
+    def _reject_value_shaped_refs(cls, v: Any) -> Any:
+        if v is None:
+            return {}
+        if not isinstance(v, dict):
+            raise ValueError(
+                "'secrets' must be a mapping of ref name to "
+                "{from: ..., key: ...}")
+        for name, spec in v.items():
+            if not isinstance(spec, dict):
+                raise ValueError(
+                    f"secret ref {name!r} must be a mapping "
+                    "{from: ..., key: ...}, not a literal value — secret "
+                    "values never belong in the pipeline yaml")
+        return v
+
     @model_validator(mode="after")
     def _check_graph(self) -> "PipelineConfig":
         names = [s.name for s in self.steps]
@@ -191,6 +249,12 @@ class PipelineConfig(BaseModel):
                     raise ValueError(
                         f"step {step.name!r}: unknown route target {target!r}"
                     )
+        for step in self.steps:
+            for ref in step.secrets:
+                if ref not in self.secrets:
+                    raise ValueError(
+                        f"step {step.name!r}: secret ref {ref!r} is not "
+                        "declared in the top-level 'secrets:' section")
         return self
 
 

{agentic_dev_loop-1.0.0a8 → agentic_dev_loop-1.0.0a10}/src/agentic_dev_loop/engine/actions.py

@@ -186,6 +186,23 @@ def checkpoint_exclude_pathspec(state_dir: str | None, cwd: Path) -> str | None:
     return f":(exclude){rel}/*.sqlite*"
 
 
+def tooling_exclude_pathspec(tooling_paths: list[str] | None) -> list[str]:
+    """git pathspecs excluding tooling paths from ``git add -A`` (020).
+
+    The loop must never commit its own tooling (pipeline, agent defs,
+    additional files, aidlc-docs, tools): the run-start integrity check
+    requires those paths to be clean relative to HEAD, so the auto-commit
+    must sweep everything *except* them. Empty when there is nothing to
+    exclude."""
+    specs = []
+    for rel in (tooling_paths or []):
+        rel = rel.replace(os.sep, "/")
+        if rel in ("", ".", ".."):
+            continue
+        specs.append(f":(exclude){rel}")
+    return specs
+
+
 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
@@ -205,9 +222,13 @@ def commit(state: dict, params: dict) -> dict:
     cwd = Path.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]
+    excludes = []
+    checkpoint_exclude = checkpoint_exclude_pathspec(state.get("state_dir"), cwd)
+    if checkpoint_exclude:
+        excludes.append(checkpoint_exclude)
+    excludes.extend(tooling_exclude_pathspec(state.get("tooling_paths")))
+    if excludes:
+        add_argv += ["--", *excludes]
     added = _git(add_argv, cwd=cwd)
     if added.returncode != 0:
         # The add is the step that touches the most files (a locked DB, a

{agentic_dev_loop-1.0.0a8 → agentic_dev_loop-1.0.0a10}/src/agentic_dev_loop/engine/agents.py

@@ -110,13 +110,17 @@ class SandboxTerminalExecutor(ToolExecutor):
 def register_sandbox_terminal(sandbox: "Sandbox", *, env: dict[str, str | None] | None = None,
                               workspace: str = "", pipeline: str | None = None,
                               step: str | None = None,
-                              network: bool = False) -> None:
+                              network: bool = False,
+                              secrets: dict[str, 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."""
+    Pipelines are sequential, so re-registering per agent step is safe.
+
+    ``secrets`` (019) is the per-step resolved secret env, injected into the
+    terminal's exec env only for steps that declared the refs."""
     from openhands.sdk.tool import register_tool
 
-    resolved_env = resolve_sandbox_env(env)
+    resolved_env = resolve_sandbox_env(env, secrets=secrets)
 
     def factory(conv_state, **params):
         return TerminalTool.create(

{agentic_dev_loop-1.0.0a8 → agentic_dev_loop-1.0.0a10}/src/agentic_dev_loop/engine/cli.py

@@ -71,7 +71,8 @@ def _registry_for(cfg_path: Path) -> tuple[Registry, PipelineConfig]:
     run path instead of being rebuilt."""
     cfg = load_config(cfg_path)
     registry = default_registry()
-    load_extensions(cfg.extensions, registry)
+    load_extensions(cfg.extensions, registry,
+                    extensions_dir=cfg.extensions_dir, workspace=Path.cwd())
     return registry, cfg
 
 

{agentic_dev_loop-1.0.0a8 → agentic_dev_loop-1.0.0a10}/src/agentic_dev_loop/engine/dryrun.py

@@ -13,10 +13,13 @@ from __future__ import annotations
 from pathlib import Path
 
 from agentic_dev_loop.core.config import PipelineConfig, StepConfig, load_config
+from .hostboundary import check_orchestrator_install, check_tooling_integrity
 from .loaders import resolve_docs
 from .isolation import (isolation_state_dir, resolve_effective_profile,
                         resolve_image_ref)
-from .registry import Registry, default_registry, load_extensions
+from .registry import (Registry, default_registry, load_extensions,
+                       validate_action_network)
+from .secrets import scan_env_files
 
 
 def _validate_agents(cfg: PipelineConfig, agents_dir: Path) -> None:
@@ -31,12 +34,18 @@ def _validate_agents(cfg: PipelineConfig, agents_dir: Path) -> None:
 
 def _validate_actions(cfg: PipelineConfig, registry: Registry) -> None:
     """Unknown action names fail at graph build time; catch them here so a
-    dry run is a true load pass."""
+    dry run is a true load pass. Host-side built-in actions cannot take
+    ``network`` (020) — deferred here because the config schema can't
+    distinguish host-side from sandbox actions."""
+    known = set(registry.actions) | set(registry.sandbox_actions)
     for step in cfg.steps:
-        if step.action is not None and step.action not in registry.actions:
+        if step.action is None:
+            continue
+        if step.action not in known:
             raise ValueError(
                 f"step {step.name!r}: unknown action {step.action!r} "
-                f"(registered: {sorted(registry.actions)})")
+                f"(registered: {sorted(known)})")
+        validate_action_network(step.name, step.action, step.network, registry)
 
 
 def _resolved_image(cfg: PipelineConfig) -> tuple[str, str, float]:
@@ -113,10 +122,15 @@ def dry_run(cfg_path, args, registry: Registry | None = None) -> int:
     cfg_path = Path(cfg_path)
     cfg = load_config(cfg_path)
     base = cfg_path.resolve().parent
+    check_orchestrator_install(Path.cwd())
+    scan_env_files(Path.cwd())
+    check_tooling_integrity(cfg, cfg_path, base, Path.cwd())
 
     if registry is None:
         registry = default_registry()
-        load_extensions(cfg.extensions, registry)
+        load_extensions(cfg.extensions, registry,
+                        extensions_dir=cfg.extensions_dir,
+                        workspace=Path.cwd())
 
     _validate_agents(cfg, base / cfg.agents_dir)
     _validate_actions(cfg, registry)