agentic-dev-loop 1.0.0a20__tar.gz → 1.0.0a21__tar.gz

{agentic_dev_loop-1.0.0a20/src/agentic_dev_loop.egg-info → agentic_dev_loop-1.0.0a21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-dev-loop
-Version: 1.0.0a20
+Version: 1.0.0a21
 Summary: Turn an LLM into a gated, sandboxed, resumable construction loop over your codebase.
 Author: Luke Wilson
 License-Expression: Apache-2.0
@@ -220,6 +220,7 @@ steps:
 | `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. |
 | `deps_policy` | `locked` (default) or `open`. `locked` = the human-owned lockfile is the source of truth and the agent may not add dependencies; `open` = the bootstrap protocol (the agent may add exact-pinned manifest entries). See [Dependency policy](#dependency-policy-locked-by-default). |
 | `lockfiles` | The pipeline's declared lockfile names (workspace-relative), injected into agent context and named by the missing-dependency fail-fast. Required (non-empty) when `deps_policy: locked` - a `locked` pipeline with no lockfiles fails fast at load. |
+| `caches:` / `sync_excludes:` | Top-level run-wide lists. `caches:` names repo-relative toolchain cache dirs bind-mounted rw from the real workspace (auto-created if missing); `sync_excludes:` names scratch paths skipped from both the export copy and sync-back (wildcard `*` spans separators, so `**/bin/**` matches a `/bin/` segment at any depth). Both default to `[]`. See [docs/setup.md](docs/setup.md). |
 
 ### Secrets (`secrets:`) - refs only, never values
 

{agentic_dev_loop-1.0.0a20 → agentic_dev_loop-1.0.0a21}/README.md

@@ -178,6 +178,7 @@ steps:
 | `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. |
 | `deps_policy` | `locked` (default) or `open`. `locked` = the human-owned lockfile is the source of truth and the agent may not add dependencies; `open` = the bootstrap protocol (the agent may add exact-pinned manifest entries). See [Dependency policy](#dependency-policy-locked-by-default). |
 | `lockfiles` | The pipeline's declared lockfile names (workspace-relative), injected into agent context and named by the missing-dependency fail-fast. Required (non-empty) when `deps_policy: locked` - a `locked` pipeline with no lockfiles fails fast at load. |
+| `caches:` / `sync_excludes:` | Top-level run-wide lists. `caches:` names repo-relative toolchain cache dirs bind-mounted rw from the real workspace (auto-created if missing); `sync_excludes:` names scratch paths skipped from both the export copy and sync-back (wildcard `*` spans separators, so `**/bin/**` matches a `/bin/` segment at any depth). Both default to `[]`. See [docs/setup.md](docs/setup.md). |
 
 ### Secrets (`secrets:`) - refs only, never values
 

{agentic_dev_loop-1.0.0a20 → agentic_dev_loop-1.0.0a21}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentic-dev-loop"
-version = "1.0.0a20"
+version = "1.0.0a21"
 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.0a20 → agentic_dev_loop-1.0.0a21}/src/agentic_dev_loop/core/config.py

@@ -4,12 +4,15 @@ from __future__ import annotations
 
 import hashlib
 import re
+import warnings
 from pathlib import Path
 from typing import Any
 
 import yaml
 from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
+from agentic_dev_loop.core.paths import _has_wildcards, path_excluded, relative_parts
+
 TERMINALS = frozenset({"success", "failure"})
 KNOWN_SECRET_PROVIDERS = frozenset({"env"})
 MOUNT_MODES = frozenset({"rw", "ro"})
@@ -51,6 +54,38 @@ def _validate_mount_path(path: str) -> str:
     return "/".join(parts) if parts else "."
 
 
+def _validate_declared_path(path: str, *, allow_wildcards: bool) -> str:
+    """Validate one declared ``caches:``/``sync_excludes:`` entry (028).
+
+    Same repo-relative contract as mount paths: non-empty, no absolute paths,
+    no ``..`` traversal, no ``.git`` component, no host-only dir. Wildcard
+    entries (``sync_excludes:`` only) skip wildcard segments in the literal
+    checks; the literal segments still obey the same rules. The normalised
+    forward-slash form is returned.
+    """
+    if not isinstance(path, str) or not path.strip():
+        raise ValueError("declared path must be a non-empty string")
+    p = path.strip()
+    if p.startswith(("/", "\\")) or (len(p) > 1 and p[1] == ":"):
+        raise ValueError(
+            f"declared path {path!r} must be repo-relative (no absolute paths)")
+    parts = [seg for seg in p.replace("\\", "/").split("/")
+             if seg not in ("", ".")]
+    for seg in parts:
+        if allow_wildcards and any(ch in seg for ch in "*?["):
+            continue
+        if seg == "..":
+            raise ValueError(
+                f"declared path {path!r} escapes the repo (no '..' traversal)")
+        if seg == ".git":
+            raise ValueError(
+                f"declared path {path!r} must never name '.git'")
+        if seg in HOST_ONLY_MOUNT_DIRS:
+            raise ValueError(
+                f"declared path {path!r} names the host-only dir {seg!r}")
+    return "/".join(parts) if parts else "."
+
+
 def parse_egress_target(spec: str) -> tuple[str, int | None]:
     """Parse ``host``, ``host:port``, or ``scheme://host[:port]`` into
     ``(host, port)``. Malformed entries that can never match fail loud
@@ -404,6 +439,13 @@ class PipelineConfig(BaseModel):
     # missing-dependency fail-fast.
     deps_policy: str = "locked"
     lockfiles: list[str] = []
+    # 028: pipeline-declared toolchain caches (rw bind-mounts from the real
+    # workspace) and run-wide sync-back excludes (scratch semantics: skipped
+    # from both the export copy and sync-back). Both default to [] - absent
+    # means "no toolchain caches beyond the engine's own sandbox venv" and
+    # "no sync-back excludes".
+    caches: list[str] = []
+    sync_excludes: list[str] = []
 
     @field_validator("deps_policy")
     @classmethod
@@ -418,6 +460,21 @@ class PipelineConfig(BaseModel):
     def _coerce_lockfiles(cls, v: Any) -> Any:
         return [v] if isinstance(v, str) else v
 
+    @field_validator("caches", "sync_excludes", mode="before")
+    @classmethod
+    def _coerce_declared_paths(cls, v: Any) -> Any:
+        return [v] if isinstance(v, str) else v
+
+    @field_validator("caches")
+    @classmethod
+    def _valid_caches(cls, v: list[str]) -> list[str]:
+        return [_validate_declared_path(c, allow_wildcards=False) for c in v]
+
+    @field_validator("sync_excludes")
+    @classmethod
+    def _valid_sync_excludes(cls, v: list[str]) -> list[str]:
+        return [_validate_declared_path(c, allow_wildcards=True) for c in v]
+
     @field_validator("secrets", mode="before")
     @classmethod
     def _reject_value_shaped_refs(cls, v: Any) -> Any:
@@ -464,6 +521,96 @@ class PipelineConfig(BaseModel):
                         f"the host-only state_dir {self.state_dir!r}")
         return self
 
+    @model_validator(mode="after")
+    def _caches_avoid_state_dir(self) -> "PipelineConfig":
+        """028: a declared cache may never name (or sit under) the host-only
+        run-state dir - it would bind-mount the engine's own state into the
+        sandbox as a rw cache."""
+        sd = self.state_dir.strip().rstrip("/\\")
+        if not sd or sd in ("/", "."):
+            return self
+        sd_parts = relative_parts(sd)
+        if not sd_parts:
+            return self
+        for cache in self.caches:
+            cp = relative_parts(cache)
+            if cp[:len(sd_parts)] == sd_parts:
+                raise ValueError(
+                    f"cache path {cache!r} names the host-only state_dir "
+                    f"{self.state_dir!r}")
+        return self
+
+    @model_validator(mode="after")
+    def _mounts_avoid_caches(self) -> "PipelineConfig":
+        """028/BR-1.3: a step mount equal to or under a declared cache is
+        rejected - the rw cache submount would silently defeat a declared
+        ``ro`` mount there. A whole-tree ``.`` mount stays fine (the cache
+        submount layers on top)."""
+        cache_parts = [relative_parts(c) for c in self.caches if relative_parts(c)]
+        if not cache_parts:
+            return self
+        for step in self.steps:
+            for m in step.mounts:
+                mp = relative_parts(m.path)
+                for cp in cache_parts:
+                    if mp[:len(cp)] == cp:
+                        raise ValueError(
+                            f"step {step.name!r}: mount path {m.path!r} names "
+                            f"declared cache {('/'.join(cp))!r}")
+        return self
+
+    @model_validator(mode="after")
+    def _excludes_avoid_caches(self) -> "PipelineConfig":
+        """028: a literal sync-exclude equal to or under a declared cache is
+        redundant (caches already behave as scratch) and fails loud. Wildcard
+        excludes are skipped - their overlap is fuzzy, not a contradiction."""
+        cache_parts = [relative_parts(c) for c in self.caches if relative_parts(c)]
+        if not cache_parts:
+            return self
+        for exclude in self.sync_excludes:
+            if _has_wildcards(exclude):
+                continue
+            ep = relative_parts(exclude)
+            for cp in cache_parts:
+                if ep[:len(cp)] == cp:
+                    raise ValueError(
+                        f"sync_excludes entry {exclude!r} is redundant: it is "
+                        f"already excluded as declared cache "
+                        f"{('/'.join(cp))!r}")
+        return self
+
+    @model_validator(mode="after")
+    def _sandbox_venv_not_declared_cache(self) -> "PipelineConfig":
+        """028: the sandbox venv is engine infrastructure, never author data.
+        Declaring ``.venv-sandbox`` in ``caches:`` while the 022 relocation
+        (``isolation.sandbox_venv_dir``) is set is a contradiction."""
+        if self.isolation is None or self.isolation.sandbox_venv_dir is None:
+            return self
+        for cache in self.caches:
+            if relative_parts(cache) == (".venv-sandbox",):
+                raise ValueError(
+                    "declaring '.venv-sandbox' in 'caches:' contradicts "
+                    "'isolation.sandbox_venv_dir' - the sandbox venv is "
+                    "relocated outside the workspace (022)")
+        return self
+
+    @model_validator(mode="after")
+    def _warn_shadowed_artifacts(self) -> "PipelineConfig":
+        """028: an artifact/produces path matching a sync-exclude would never
+        sync back. Non-fatal warning (wildcard overlap is fuzzy, so a hard
+        failure would false-positive)."""
+        if not self.sync_excludes:
+            return self
+        for step in self.steps:
+            for artifact in list(step.produces) + (
+                    [step.artifact] if step.artifact is not None else []):
+                if path_excluded(artifact, self.sync_excludes):
+                    warnings.warn(
+                        f"step {step.name!r}: {artifact!r} matches a "
+                        "sync_excludes entry and will never sync back",
+                        stacklevel=2)
+        return self
+
     @model_validator(mode="after")
     def _check_graph(self) -> "PipelineConfig":
         names = [s.name for s in self.steps]

agentic_dev_loop-1.0.0a21/src/agentic_dev_loop/core/paths.py

@@ -0,0 +1,69 @@
+"""Repo-relative path helpers shared by config validation and sync-back.
+
+One place for the declared-path exclusion vocabulary (028): literal entries
+exclude by component prefix (the dir and everything under it); wildcard
+entries match by ``fnmatch.fnmatchcase`` on the full posix relpath. Both the
+``caches:``/``sync_excludes:`` validators (core) and the export/sync-back
+planners (engine) consume these, so the semantics cannot drift.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+
+
+def relative_parts(path: str) -> tuple[str, ...]:
+    """Normalise a repo-relative path into its non-empty, non-``.`` segments."""
+    return tuple(seg for seg in path.replace("\\", "/").split("/")
+                 if seg not in ("", "."))
+
+
+def _has_wildcards(spec: str) -> bool:
+    return any(ch in spec for ch in "*?[")
+
+
+def path_excluded(rel: str, excludes: tuple[str, ...] | list[str]) -> bool:
+    """True when a repo-relative posix path is excluded by a declared
+    ``sync_excludes:`` spec (028).
+
+    Literal entries exclude by component prefix; wildcard entries by
+    ``fnmatch.fnmatchcase`` on the full posix relpath. ``*`` spans path
+    separators (fnmatch string semantics), so ``**/bin/**`` matches a literal
+    ``/bin/`` segment at any depth and ``*.dll`` matches at any depth.
+    """
+    parts = relative_parts(rel)
+    for spec in excludes:
+        if _has_wildcards(spec):
+            if fnmatch.fnmatchcase(rel, spec):
+                return True
+        else:
+            spec_parts = relative_parts(spec)
+            if not spec_parts:
+                # ``.`` (or a blank entry) excludes the whole tree.
+                return True
+            if parts[:len(spec_parts)] == spec_parts:
+                return True
+    return False
+
+
+def dir_excluded(dir_rel: str, excludes: tuple[str, ...] | list[str]) -> bool:
+    """True when a directory (as a posix relpath) must be pruned from a walk.
+
+    Literal excludes prune their subtree. Wildcard excludes prune only when
+    the directory itself is the matched target - checked with a trailing
+    separator so ``**/bin/**`` prunes ``src/proj/bin`` but ``*.dll`` never
+    prunes a directory.
+    """
+    parts = relative_parts(dir_rel)
+    for spec in excludes:
+        if _has_wildcards(spec):
+            if fnmatch.fnmatchcase(dir_rel.rstrip("/") + "/", spec):
+                return True
+        else:
+            spec_parts = relative_parts(spec)
+            if not spec_parts:
+                # ``.`` (or a blank entry) excludes the whole tree.
+                return True
+            if parts[:len(spec_parts)] == spec_parts:
+                return True
+    return False

{agentic_dev_loop-1.0.0a20 → agentic_dev_loop-1.0.0a21}/src/agentic_dev_loop/engine/isolation.py

@@ -40,7 +40,6 @@ from agentic_dev_loop.core.config import IsolationConfig, PipelineConfig
 from .egress_policy import EgressPolicy
 from .egress_proxy import EgressProxy
 from .mounts import Mount, MountSet
-from .presets import CACHE_DIRS
 from .proc import needs_shell, split_command
 from .seccomp import resolve_seccomp_profile
 from .step_workspace import StepWorkspace
@@ -230,21 +229,6 @@ class ContainerProfile:
         return container_profile_key(self.mount_set, self.egress_policy)
 
 
-def discover_cache_paths(workspace: str | Path,
-                         sandbox_venv_dir: str | None = None) -> list[str]:
-    """The in-workspace cache dirs to bind-mount into the export (BR-3/F2).
-
-    Only dirs that actually exist are caches - an absent cache dir is simply
-    not a cache (the toolchain is unused), so materialisation never fails on
-    a repo that does not use, say, node. The relocated sandbox venv (022) is
-    never a cache: it bind-mounts from outside the workspace instead."""
-    ws = Path(workspace)
-    paths = [d for d in CACHE_DIRS if (ws / d).is_dir()]
-    if sandbox_venv_dir is not None:
-        paths = [d for d in paths if d != SANDBOX_VENV_DIR]
-    return paths
-
-
 @dataclass
 class _ProfileContainer:
     """One pooled execution container (D-1/BR-10): its resolved profile plus
@@ -523,6 +507,53 @@ def remove_sandbox_venv(workspace: str | Path, *,
             f"- remove it manually and re-run (docs/setup.md §5)") from e
 
 
+def repair_venv_shebangs(venv_dir: str | Path, *,
+                           state_dir: str | Path,
+                           export_root: str | Path) -> None:
+    """Repair stale export-path shebangs in a sandbox venv (028).
+
+    Each run materialises a fresh export under ``state_dir/exports/<uuid>/``,
+    so a venv built by an earlier run carries console-script shebangs that bake
+    that (now dead) export path. Rewrite every regular file under
+    ``<venv_dir>/bin/`` whose first line starts with ``#!`` and points at a
+    dead ``state_dir/exports/`` path to the current run's venv python
+    (``{export_root}/.venv-sandbox/bin/python``). Symlinks and files without a
+    shebang are left alone; idempotent; host-side, before any exec.
+    """
+    bin_dir = Path(venv_dir) / "bin"
+    if not bin_dir.is_dir():
+        return
+    target = str(Path(export_root) / SANDBOX_VENV_DIR / "bin" / "python")
+    stale_prefix = str(Path(state_dir) / "exports").rstrip("/\\") + "/"
+    for entry in sorted(bin_dir.iterdir()):
+        if entry.is_symlink() or not entry.is_file():
+            continue
+        try:
+            with entry.open("rb") as fh:
+                first = fh.readline(256)
+        except OSError:
+            continue
+        if not first.startswith(b"#!"):
+            continue
+        line = first.decode("utf-8", errors="replace").rstrip("\n").rstrip("\r")
+        interpreter = line[2:].strip()
+        if not interpreter or interpreter == target:
+            continue
+        if not interpreter.startswith(stale_prefix):
+            continue
+        _rewrite_shebang(entry, target)
+
+
+def _rewrite_shebang(path: Path, target: str) -> None:
+    """Replace only the first line of a regular file, preserving the rest."""
+    data = path.read_bytes()
+    nl = data.find(b"\n")
+    if nl == -1:
+        return
+    body = data[nl + 1:]
+    path.write_bytes(f"#!{target}\n".encode("utf-8") + body)
+
+
 def host_user_flag() -> str | None:
     """The ``docker --user`` value binding the sandbox to the host user.
 
@@ -759,7 +790,8 @@ class DockerBackend(Sandbox):
                  network: bool = False, sandbox_venv_dir: str | None = None,
                  seccomp_profile: str | None = None,
                  export_root: str | None = None,
-                 cache_mounts: list[tuple[str, str, str]] | None = None):
+                 cache_mounts: list[tuple[str, str, str]] | None = None,
+                 sync_excludes: list[str] | None = None):
         self._image = image
         self._workspace = workspace
         self._iso_state_dir = Path(iso_state_dir)  # host-only (audit)
@@ -783,6 +815,9 @@ class DockerBackend(Sandbox):
             for _source, target, _mode in self._cache_mounts:
                 self._cache_paths.append(
                     os.path.relpath(target, export_root).replace("\\", "/"))
+        # 028: run-wide sync-back excludes (scratch paths - skipped from both
+        # the export copy and every snapshot).
+        self._sync_excludes = list(sync_excludes or ())
         self._baseline: dict[str, str] = {}
         # The profile-keyed pool (D-1/BR-10): profile key -> running container.
         self._pool: dict[tuple[str, bool], _ProfileContainer] = {}
@@ -889,7 +924,8 @@ class DockerBackend(Sandbox):
         self._started = True
         if not self._baseline:
             self._baseline = _snapshot(Path(self._export_root),
-                                       self._cache_paths)
+                                       self._cache_paths,
+                                       self._sync_excludes)
 
     def provision(self, setup_cmd: str, stamp_key: str, stamp_dir: str,
                   force: bool) -> None:
@@ -1043,14 +1079,15 @@ class DockerBackend(Sandbox):
         report: SyncBackReport = sync_back(
             self._export_root, self._workspace, list(mount_set.rw_paths()),
             baseline=self._baseline, step_id=None,
-            cache_paths=self._cache_paths)
+            cache_paths=self._cache_paths, excludes=self._sync_excludes)
         if report.conflicts:
             raise SandboxError(
                 f"AE-SBX-016: sync-back conflict in "
                 f"{', '.join(report.conflicts)} - the real repo changed "
                 f"underneath; resolve before retrying (BR-4.4)")
         self._baseline = _snapshot(Path(self._export_root),
-                                   self._cache_paths)
+                                   self._cache_paths,
+                                   self._sync_excludes)
         append_audit_record(self._iso_state_dir, {
             "timestamp": datetime.now(timezone.utc).isoformat(),
             "event": "sync_back",
@@ -1295,18 +1332,34 @@ def startup_sandbox(cfg: PipelineConfig, *, workspace: Path,
         cfg.isolation.sandbox_venv_dir if cfg.isolation else None, workspace)
 
     export_root = str(Path(state_dir) / "exports" / uuid.uuid4().hex)
-    cache_paths = discover_cache_paths(workspace, sandbox_venv_dir)
+    # 028: cache paths are pipeline-author data (``caches:``), plus the engine's
+    # own sandbox venv when it is not relocated (016/022 behaviour - the venv
+    # is a cache only once it exists). Declared-but-missing caches are
+    # auto-created host-side (uid-owned, empty) before export planning, so the
+    # missing-cache guard in plan_step_workspace stays a race guard only.
+    cache_paths = list(cfg.caches)
+    if sandbox_venv_dir is None and (workspace / SANDBOX_VENV_DIR).is_dir():
+        if SANDBOX_VENV_DIR not in cache_paths:
+            cache_paths.append(SANDBOX_VENV_DIR)
+    for cache in cfg.caches:
+        (workspace / cache).mkdir(parents=True, exist_ok=True)
     ws = StepWorkspace.materialise(
         workspace, cache_paths, sys.platform, export_root,
-        state_dir=str(state_dir))
+        state_dir=str(state_dir), excludes=list(cfg.sync_excludes))
     export_root = str(ws.export_root)
     cache_mounts = ws.mount_points()[1:]  # skip the export root itself
+    # Repair console-script shebangs that bake a previous run's dead export
+    # path (028): a venv built by export A must execute its ``bin/*`` scripts
+    # when mounted into export B.
+    venv_dir = Path(sandbox_venv_dir) if sandbox_venv_dir else workspace / SANDBOX_VENV_DIR
+    repair_venv_shebangs(venv_dir, state_dir=state_dir, export_root=export_root)
 
     backend = DockerBackend(
         image=image, workspace=str(workspace), iso_state_dir=str(iso_state_dir),
         profile=profile, runner=runner, network=needs_network,
         sandbox_venv_dir=sandbox_venv_dir, seccomp_profile=seccomp_profile,
-        export_root=export_root, cache_mounts=cache_mounts)
+        export_root=export_root, cache_mounts=cache_mounts,
+        sync_excludes=list(cfg.sync_excludes))
     backend.ensure_image()
     backend.create_execution_container()
     if refresh is None:

{agentic_dev_loop-1.0.0a20 → agentic_dev_loop-1.0.0a21}/src/agentic_dev_loop/engine/presets.py

@@ -2,26 +2,15 @@
 
 Preset data, never mechanism (D-2): one ``package-registries`` preset serves
 every toolchain, so the restore step stays toolchain-agnostic. Adding a
-toolchain adds a target here plus a cache declaration - no per-toolchain
-egress code exists.
+toolchain adds a target here plus a ``caches:`` entry in the pipeline - no
+per-toolchain egress code exists. Toolchain cache dirs are pipeline author
+data (``caches:``), never engine preset data (028).
 """
 
 from __future__ import annotations
 
 from agentic_dev_loop.core.config import KNOWN_EGRESS_PRESETS
 
-# The per-toolchain cache dirs (BR-9.3, BR-3.1): in-workspace paths that are
-# bind-mounted rw into the export rather than copied. Cache declarations are
-# preset data (D-2) - adding a toolchain adds a path here, never mechanism.
-CACHE_DIRS: tuple[str, ...] = (
-    ".venv-sandbox",
-    "node_modules",
-    "qa/node_modules",
-    "qa/.browsers",
-    ".nuget-packages",
-    "target",
-)
-
 
 # The package registries every toolchain's locked restore touches (BR-9.1):
 # pypi, npm, NuGet, cargo, plus the VCS/source-install hosts shared by all.

{agentic_dev_loop-1.0.0a20 → agentic_dev_loop-1.0.0a21}/src/agentic_dev_loop/engine/step_workspace.py

@@ -14,6 +14,8 @@ import shutil
 from dataclasses import dataclass
 from pathlib import Path
 
+from agentic_dev_loop.core.paths import dir_excluded, path_excluded
+
 from .sync_back import SyncBackReport, _snapshot, sync_back
 
 # Host-only dirs never copied into the export (022). ``.git`` is excluded by
@@ -48,16 +50,19 @@ def _relative_parts(path: str) -> tuple[str, ...]:
 
 def plan_step_workspace(repo: str | Path, cache_paths: list[str],
                         platform: str, export_root: str | Path,
-                        state_dir: str | None = None) -> StepWorkspacePlan:
+                        state_dir: str | None = None,
+                        excludes: list[str] | None = None) -> StepWorkspacePlan:
     """Plan the export (BR-2/BR-3): copy every workspace file except
-    ``.git``/host-only dirs/cache paths/``state_dir``; bind-mount each
-    declared cache path rw. A missing declared cache path is a loud failure
-    (BR-3.2, pillar 5). Pure over platform facts - deterministic given the
-    repo state."""
+    ``.git``/host-only dirs/cache paths/``state_dir``/sync-excludes; bind-mount
+    each declared cache path rw. A missing declared cache path is a loud
+    failure (BR-3.2, pillar 5) - kept as a race guard; startup pre-creates the
+    dirs host-side (028). Excluded paths are scratch: skipped at copy time with
+    no mount. Pure over platform facts - deterministic given the repo state."""
     repo = Path(repo)
     export_root = Path(export_root)
     cache_rels = [_relative_parts(c) for c in cache_paths]
     state_dir_rel = _relative_parts(state_dir) if state_dir else None
+    excludes = list(excludes or ())
 
     for cache in cache_paths:
         if not (repo / cache).exists():
@@ -73,11 +78,14 @@ def plan_step_workspace(repo: str | Path, cache_paths: list[str],
             d for d in dirnames
             if d not in _EXCLUDED_DIRS
             and not _excluded(rel_dir_parts + (d,), cache_rels, state_dir_rel)
+            and not dir_excluded((rel_dir / d).as_posix(), excludes)
         ]
         for name in filenames:
             parts = rel_dir_parts + (name,)
             if _excluded(parts, cache_rels, state_dir_rel):
                 continue
+            if path_excluded("/".join(parts), excludes):
+                continue
             copy_paths.append("/".join(parts))
 
     cache_mounts = tuple(
@@ -122,16 +130,19 @@ class StepWorkspace:
     @classmethod
     def materialise(cls, repo: str | Path, cache_paths: list[str],
                     platform: str, export_root: str | Path,
-                    state_dir: str | None = None) -> "StepWorkspace":
+                    state_dir: str | None = None,
+                    excludes: list[str] | None = None) -> "StepWorkspace":
         """Copy the workspace into the export, excluding ``.git``/host-only
-        dirs/caches/``state_dir``; pre-create the cache mount targets so the
-        rw bind-mounts have uid-owned destinations (the AE-SBX-009 class)."""
+        dirs/caches/``state_dir``/sync-excludes; pre-create the cache mount
+        targets so the rw bind-mounts have uid-owned destinations (the
+        AE-SBX-009 class)."""
         plan = plan_step_workspace(repo, cache_paths, platform, export_root,
-                                   state_dir=state_dir)
+                                   state_dir=state_dir, excludes=excludes)
         ws = cls(plan, real_repo=repo)
         ws._copy(repo)
         ws._baseline = _snapshot(
-            ws._export_root, cache_paths=[c.relative for c in plan.cache_mounts])
+            ws._export_root, cache_paths=[c.relative for c in plan.cache_mounts],
+            excludes=list(excludes or ()))
         return ws
 
     def _copy(self, repo: Path) -> None:
@@ -154,10 +165,12 @@ class StepWorkspace:
             points.append((cache.source, f"{root}/{cache.relative}", "rw"))
         return points
 
-    def sync_back(self, declared_rw: list[str]) -> SyncBackReport:
+    def sync_back(self, declared_rw: list[str],
+                  excludes: list[str] | None = None) -> SyncBackReport:
         """Git-aware diff-copy of declared-rw changes back to the real repo
         (BR-4). Delegates to ``sync_back``; conflicts are loud."""
         return sync_back(
             self._export_root, self._real_repo, declared_rw,
             baseline=getattr(self, "_baseline", None),
-            cache_paths=[c.relative for c in self._plan.cache_mounts])
+            cache_paths=[c.relative for c in self._plan.cache_mounts],
+            excludes=list(excludes or ()))