BEAM-local physical workspace snapshots for isolated Subagents.
This module is the snapshot half of ADR 0011's isolated child workspace contract. It
deliberately walks and copies with Elixir filesystem APIs instead of shelling out to
git, find, or another host process. That keeps Subagent fanout aligned with ADR
0027: BEAM coordination can scale broadly, while host-boundary crossings stay scarce
and explicit.
The first policy is intentionally conservative. It skips common dependency, build, cache, and Pixir runtime-state directories by basename at any depth, enforces copy limits, and returns string-keyed metadata/errors suitable for Tool results and Events.
The exclusion denylist is a policy carried in copier state: the built-in defaults
are always in effect, and callers may only extend them, never remove them, via
config :pixir, :subagents, snapshot_excluded_dir_names: [...] or the
:excluded_dir_names copy option (project-specific bulk like a benchmark outputs/
directory is the motivating case, #221). Names are directory basenames matched
byte-exactly at any depth: a regular file with an excluded name is still copied, and
on case-insensitive or normalization-insensitive filesystems a case or Unicode
variant of an excluded name is not matched (the failure mode is copying more, never
escaping the workspace). The effective list is confessed in the snapshot metadata;
when policy validation itself fails, no effective list is claimed. Symlinks are
lstat-skipped before the policy is consulted, so custom exclusions never introduce
traversal that follows them.
Summary
Functions
Copy a bounded, policy-filtered snapshot from src into existing directory dest.