dotagents-cli 0.8.0__tar.gz → 0.8.2__tar.gz

{dotagents_cli-0.8.0 → dotagents_cli-0.8.2}/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.8.2] - 2026-10-25
+
+### Fixed
+
+- `findings` (and `init` / `overlays`) run from inside a project's `.agents`, such as
+  `<project>/.agents/findings`, target that project. They used to write a second
+  `.agents` inside the store. Deeper than a top-level directory of the user store,
+  where no project can be named, they refuse instead of writing there.
+- `findings` keeps a hand-written `INDEX.md`: before the first regeneration it is
+  copied to `INDEX.md.handwritten`, with a warning.
+- The routing note above overlay paths no longer suggests `dotagents env` for
+  reading an overlay root (it prints the whole environment, secrets included); it
+  says to read just the variable.
+
+- The `sh` wrapper `init` writes into `<store>/bin/dotagents` works from another
+  system that shares the store, such as WSL reading a Windows store. It ran the
+  interpreter recorded by `init`, a Windows path there; where that interpreter
+  does not run it now takes the store's agents' venv for that OS and machine
+  (`.pyvenv/<version>-<os>-<arch>`), else `python3`, and converts a recorded
+  `C:/...` pyz path with `wslpath`.
+
+## [0.8.1] - 2026-10-21
+
+### Added
+
+- Overlay commands get a launcher on `PATH`: each top-level `bin/<name>.py`, and
+  each `[scripts]` entry in `overlay.toml` (`name = "path"` adds or replaces one,
+  `name = false` opts a `bin/<name>.py` out). The launchers live in the agents'
+  venv, in `<venv>/overlays/`: `<name>.exe` on Windows, made with distlib's
+  `ScriptMaker` so no command interpreter parses the arguments, and a `/bin/sh`
+  script elsewhere. They run the script through `$<NAME>_OVERLAY_ROOT` when they
+  run, so only a new interpreter needs them made again. `init` and `overlays add` /
+  `sync` / `remove` keep them current and delete those no overlay has; two
+  overlays with one script name is an error naming both.
+- `dotagents env` puts the launcher directory of the venv `AGENTS_PYTHON` names
+  first on `PATH`, ahead of the levels' `bin` dirs, and takes any other venv's
+  off it.
+- A project gets its own venv when one of its overlays has scripts.
+- New dependency: `distlib>=0.4.0,<0.5`, vendored in the `.pyz`.
+
 ## [0.8.0] - 2026-10-16
 
 ### Added
@@ -1527,7 +1567,9 @@ Patch release: the PATH/POSIX-conversion fix above (the only change since 0.3.0)
   affected module sources (`dotagents.cli`, `duho.presets`) to extracted temp files
   before dispatch; a no-op for a plain install.
 
-[Unreleased]: https://github.com/jose-pr/dotagents/compare/v0.8.0...HEAD
+[Unreleased]: https://github.com/jose-pr/dotagents/compare/v0.8.2...HEAD
+[0.8.2]: https://github.com/jose-pr/dotagents/compare/v0.8.1...v0.8.2
+[0.8.1]: https://github.com/jose-pr/dotagents/compare/v0.8.0...v0.8.1
 [0.8.0]: https://github.com/jose-pr/dotagents/compare/v0.7.6...v0.8.0
 [0.7.6]: https://github.com/jose-pr/dotagents/compare/v0.7.5...v0.7.6
 [0.7.5]: https://github.com/jose-pr/dotagents/compare/v0.7.4...v0.7.5

{dotagents_cli-0.8.0 → dotagents_cli-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dotagents-cli
-Version: 0.8.0
+Version: 0.8.2
 Summary: The dotagents CLI: install and manage a portable ~/.agents config for AI coding agents
 Project-URL: Homepage, https://github.com/jose-pr/dotagents/
 Project-URL: Repository, https://github.com/jose-pr/dotagents
@@ -23,6 +23,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.9
+Requires-Dist: distlib<0.5,>=0.4.0
 Requires-Dist: duho<0.8,>=0.7.5
 Requires-Dist: pathapi<0.2,>=0.1.0
 Requires-Dist: tomli>=1.1.0; python_version < '3.11'

{dotagents_cli-0.8.0 → dotagents_cli-0.8.2}/docs/guide/authoring.md

@@ -72,12 +72,41 @@ dotagents starts with the libs in place whatever shell it runs from. A `lib/` mo
 comes before site-packages and the standard library: do not reuse a package name you
 do not mean to replace.
 
-A `bin/` launcher can also be run outside a `dotagents env` session (from cmd.exe or
-a PowerShell prompt, say), so it sets `PYTHONPATH` itself before starting Python:
-its own `lib/`, then `$AGENTS_PYTHONPATH`, then the caller's, leaving empty parts
-out (an empty entry means the current directory). The net overlay's `bin/curl` and
-`bin/curl.cmd` are the pattern: POSIX sh with no external commands, and a `.cmd`
-that uses `setlocal` so the caller's cmd session is not changed.
+## Commands on PATH: `bin/*.py` and `[scripts]`
+
+A Python command needs no launcher of your own. Every top-level `bin/<name>.py`
+gets one named `<name>`: `<name>.exe` on Windows (distlib's `ScriptMaker`, the
+launcher pip gives console scripts) and a `/bin/sh` script elsewhere, made in the
+agents' venv, in `<venv>/overlays/`, whenever `overlays add` / `sync` / `remove` or
+`init` brings the venv up to date. `dotagents env` puts that directory first on
+`PATH` for the venv `$AGENTS_PYTHON` names, so `bin/curl.py` answers to `curl`
+ahead of the system's, and drops any other venv's.
+
+The launcher runs your script under the venv's interpreter, as `python
+bin/<name>.py` would, found when it runs through `$<NAME>_OVERLAY_ROOT`: editing
+the script or moving the store needs nothing regenerated, only a new interpreter
+does. Unset, or with the script missing, it exits 2 and says so. A file whose name
+starts with `_` is not a command. Name other scripts, rename one, or opt one out
+in `overlay.toml`:
+
+```toml
+[scripts]
+tool = "lib/tool/main.py"   # a launcher `tool` for another path
+helper = false              # none for bin/helper.py
+```
+
+Two overlays with one script name is an error naming both. A launcher no overlay
+has any more is deleted at the next sync.
+
+**Never ship a `.cmd` or `.bat` that takes arguments.** cmd.exe parses its command
+line before the first line runs, so an argument's `&`, `|`, `>` or `%VAR%` acts:
+from PowerShell, `curl "http://h/?a=1|hostname"` would run `hostname`. The `.exe`
+above hands the arguments over as passed.
+
+Your script may run outside a `dotagents env` session too, so set `PYTHONPATH`
+for what it starts, if anything needs the libs: its own `lib/`, then
+`$AGENTS_PYTHONPATH`, then the caller's, leaving empty parts out (an empty entry
+means the current directory). The net overlay's `bin/curl.py` does this.
 
 ## Setup scripts
 

{dotagents_cli-0.8.0 → dotagents_cli-0.8.2}/docs/guide/overlays.md

@@ -48,7 +48,7 @@ or `--repo <checkout>/overlays` for a local checkout of the branch.
 | `python`, `node`, `rust` | Per-language `kb/` conventions + manifest templates + CI workflow templates. |
 | `release` | A host-agnostic release helper: an agent-driven commit-plan loop plus tag/CI monitoring across GitHub (`gh`) and GitLab. |
 | `private-sync` | The one-private-repo, per-project `.agents` model (`kb/PRIVATE_SYNC.md` + cloud hooks) — see [Private sync](private-sync.md). |
-| `net` | Dependency-free HTTP tooling (a drop-in `curl` shim, an OS-trust-store `certifi` shim, an `httplib` session toolkit reading `AGENTS_PROXY`). |
+| `net` | HTTP tooling: a drop-in `curl` launcher (curlike), an OS-trust-store `certifi` shim, and syshttp (the system proxy and the OS verifier by default), both packages installed from the overlay's `requirements.txt`; settings are `AGENTS_*` (`AGENTS_PROXY` and kin). |
 | `recovery` | A config-recovery playbook for reconstructing a lost `~/.agents`. |
 
 ## Managing overlays
@@ -182,7 +182,9 @@ dotagents overlays sync -g                                                   # r
 
 Nothing in an overlay has to set up its own paths. For every installed overlay,
 `dotagents env` prepends `bin/` to `PATH` and an existing `lib/` to `PYTHONPATH`
-(listing the libs in `AGENTS_PYTHONPATH` too), and exports **`$<NAME>_OVERLAY_ROOT`** — the overlay's
+(listing the libs in `AGENTS_PYTHONPATH` too), puts the launchers of its scripts
+(`bin/*.py` and `[scripts]`, in `<venv>/overlays/` of the agents' venv) first on
+`PATH`, and exports **`$<NAME>_OVERLAY_ROOT`** — the overlay's
 installed directory (`NAME` is the overlay's name upper-cased, `-` → `_`:
 `private-sync` → `PRIVATE_SYNC_OVERLAY_ROOT`).
 That variable is how overlay content refers to itself and to other overlays: a
@@ -214,6 +216,7 @@ small built-in reader that covers these keys. Keys:
 | `rules` | Overlay-relative markdown paths whose rule bullets append to "Always-on rules". |
 | `priority` | Merge order (lower sorts earlier; unprioritized default is 500). |
 | `setup_timeout` | Seconds the setup script may run before it is stopped (default 300; `0` = no limit). |
+| `[scripts]` | Launchers on `PATH`: `name = "path/in/overlay.py"` adds or replaces one, `name = false` drops the one for a `bin/<name>.py`. See [Authoring → Commands on PATH](authoring.md#commands-on-path-binpy-and-scripts). |
 
 `overlay.toml` is the only manifest. A leading `---` frontmatter block in a
 `CONTEXT.md` (the `priority:` / `scope:` / `dependencies:` an older overlay format

{dotagents_cli-0.8.0 → dotagents_cli-0.8.2}/docs/guide/private-sync.md

@@ -11,13 +11,19 @@ overlay is what makes them exist; a plain dotagents has no private-sync surface
 
 ## The idea
 
-Your global config store **is** a private git repo. Its root is the per-user config;
-a `projects/<name>/` tree inside it holds each project's private payload. For a
-checked-out project, its `.agents` directory is a **symlink** into the store (the
-project's `.gitignore` already excludes `.agents` per the Leakage rule, so the link
+Your global config store **is** a private git repo, and its `main` branch is the
+per-user config. Each project's private payload is a **branch** of it, named after
+the project, and the project's `.agents` directory is a git worktree on that branch
+(the project's `.gitignore` already excludes `.agents` per the Leakage rule, so it
 never lands in the public repo). `<name>` defaults to the project's basename, so a
-local checkout and a cloud checkout of the same project resolve to the same store
-entry.
+local checkout and a cloud checkout of the same project resolve to the same branch.
+
+That branch can live elsewhere: `link-project --store-repo self` keeps it on the
+project's own repository (branch `agents`), and `--store-repo <url>` on any other,
+such as a team account's (cloned into `.agents`); `--store-branch` names the branch.
+The choice is recorded in the config repo, so every machine links the project the
+same way. A store kept as a `projects/<name>/` directory, symlinked into the
+project, still works and is kept by a project that already has one.
 
 The store's installed overlays can travel two ways:
 
@@ -39,11 +45,12 @@ dotagents overlays add private-sync -g \
   --repo "https://github.com/jose-pr/dotagents.git@repo#overlays"   # commands + kb + hooks
 
 # link-project / sync-project come FROM that overlay -- run `overlays add` first.
-dotagents link-project .   # symlink this project's .agents into its store
+dotagents link-project .   # check this project's store branch out at .agents
                            #   (an existing real .agents/ is adopted on the
-                           #    first link; --copy mirrors it as a real dir
-                           #    for no-symlink systems)
-dotagents sync-project -m "msg"   # git pull --rebase / commit / push the store
+                           #    first link)
+dotagents link-project . --store-repo self             # ...on the project's own repo
+dotagents link-project . --store-repo <team-repo-url>  # ...on another repo
+dotagents sync-project --project . -m "msg"   # commit / push the project's branch, then the config
 dotagents sync-project --remote <url> -m init   # one-command bootstrap
 ```
 

{dotagents_cli-0.8.0 → dotagents_cli-0.8.2}/pyproject.toml

@@ -37,6 +37,8 @@ classifiers = [
 dependencies = [
     "duho>=0.7.5,<0.8",
     "pathapi>=0.1.0,<0.2",
+    # The launchers of overlays' [scripts]: ScriptMaker writes the Windows .exe.
+    "distlib>=0.4.0,<0.5",
     # overlay.toml manifests and TOML registries; tomllib is stdlib from 3.11.
     'tomli>=1.1.0; python_version < "3.11"',
 ]

{dotagents_cli-0.8.0 → dotagents_cli-0.8.2}/src/dotagents/AGENTS.md

@@ -239,8 +239,10 @@ returns the exit code.
   otherwise; `0` from either means no limit.
 - `parse_manifest_text(text, origin="overlay.toml") -> Optional[dict]` — the TOML
   document via `tomllib` / `tomli`, else a built-in reader (top-level strings,
-  string arrays including multi-line strings, an integer); `None` plus one warning
-  when it is not valid TOML.
+  string arrays including multi-line strings, an integer, and the `[scripts]` table
+  of strings and booleans); `None` plus one warning when it is not valid TOML.
+- `SCRIPT_NAME_RE` — a script (launcher) name: a letter or digit, then letters,
+  digits, `.`, `_`, `-`; never ending in `.exe` nor a Windows device name.
 - `class InstallResult` — what `install_to` did: `written`, `unchanged`,
   `replaced` (edited here, replaced by the source's file), `removed` (not in the
   source, or cleared by `prune`), `backed_up`, `lines`; property `skipped`
@@ -270,8 +272,16 @@ returns the exit code.
     (the later copy shadows it).
   - `Overlay.sort_by_priority(overlays) -> list[Overlay]` — sorted by `sort_key`.
   - `read_manifest() -> dict` — keys `name`, `description`, `routing`, `rules`,
-    `requires` (valid names only, normalized, de-duplicated), `priority`; a missing
-    or invalid manifest gives empty contributions.
+    `requires` (valid names only, normalized, de-duplicated), `priority`,
+    `setup_timeout`, `scripts` (the `[scripts]` table as written: name -> path
+    relative to the overlay, `/`-separated, plain file-name characters, no `..`,
+    or `false`; any other entry is dropped with a warning); a missing or invalid
+    manifest gives empty contributions.
+  - `scripts() -> dict[str, str]` — the scripts that get a launcher
+    (`dotagents._launchers`): each top-level `bin/<name>.py` whose stem is a
+    `SCRIPT_NAME_RE` name (so not `_private.py`, not `__init__.py`), then
+    `[scripts]`, which adds or replaces a path by name, or drops a detected one
+    with `false`.
   - `find_setup_script() -> Optional[Path]`.
   - `setup_timeout(override=None) -> int` — `override`, else the manifest's
     `setup_timeout` (a non-negative int; anything else is ignored with a warning),
@@ -307,6 +317,35 @@ returns the exit code.
   `sort_key` order; creates the file when absent; content outside the markers kept;
   returns whether it changed (`False` and a warning when the file has no block).
 
+## `dotagents._launchers`
+
+Launchers for overlays' scripts (`Overlay.scripts()`), in `<venv>/overlays/` of a
+dotagents venv; `_pyvenv.sync_venvs` brings them up to date on every sync, and
+`_env.get_environment` puts that dir first on `PATH` for the venv `AGENTS_PYTHON`
+names. A launcher runs `$<NAME>_OVERLAY_ROOT/<script>` under the venv's
+interpreter, resolved when it runs (argv[0] the script, its dir first on
+`sys.path`, run as `__main__`); with the variable unset or the script missing it
+exits 2 naming both. Windows: `<name>.exe`, distlib's `ScriptMaker` launcher (no
+command interpreter parses its arguments). POSIX: `<name>`, mode 0755, a `/bin/sh`
+script that `exec`s the interpreter.
+
+- `DIR = "overlays"`, `MANIFEST = ".dotagents-launchers.json"` (in that dir:
+  `{name: overlay name}` of the launchers dotagents wrote).
+- `class LauncherError(SystemExit)` — two overlays with one script name; the
+  message names both.
+- `launcher_dir(venv) -> Path`. `file_name(name) -> str` (`.exe` added on Windows).
+  `is_launcher_dir(path) -> bool` — the shape `<store>/.pyvenv/<triplet>/overlays`,
+  no filesystem access.
+- `declared(overlays) -> dict[str, tuple[Overlay, str]]` — every script by name;
+  raises `LauncherError` on a name two overlays have.
+- `render(name, var, script, python) -> bytes` — one launcher's bytes; equal
+  inputs give equal bytes (the `.exe`'s archive carries a fixed time).
+- `sync(venv, python, overlays, *, dry_run=False, logger=None) -> list[str]` —
+  writes each launcher whose bytes differ (atomic replace), deletes those
+  `MANIFEST` lists that no overlay has any more (other files there are left
+  alone), rewrites `MANIFEST`; returns the names written or deleted. Raises
+  `LauncherError` before any write.
+
 ## `dotagents._sources`
 
 Spec grammar: `[git+]<location>[@<ref>][#<path>]`. A location ending `.git`, starting
@@ -383,7 +422,12 @@ a directory of overlays or a registry file (default: the root); for a **source**
 
 Assembly order (`get_environment`): identity (`stamp_identity`), then the roots,
 then `PATH`, then `PYTHONPATH` / `AGENTS_PYTHONPATH`, then the env files, then the
-proxy model.
+proxy model. `PATH`: every level's `bin` prepended, then, first of all, the active
+venv's launcher dir (`<venv>/overlays`, `_launchers`) when `AGENTS_PYTHON` is that
+venv's interpreter and the dir exists; every other dotagents venv's launcher dir is
+taken out. First even before the `bin` dirs: cmd.exe and PowerShell try every
+`PATHEXT` extension in a directory before the next one, so a `bin/<name>.py` (with
+`.PY` in `PATHEXT`) or a `.cmd` there would otherwise win.
 
 - Roots: `AGENTS_HOME` and `AGENTS_PROJECT_ROOT` name the stores walked, absolute —
   an inherited value naming the same directory holds, another is replaced; in a
@@ -678,8 +722,11 @@ objects `{"matcher"?: str, "hooks": [{"type": "command", "command": str, ...}]}`
 
 ## `dotagents._wrappers`
 
-- `POSIX_TEMPLATE`, `POSIX_TEMPLATE_REL` (pyz path relative to the wrapper),
-  `POSIX_TEMPLATE_MODULE` (`"<python>" -m dotagents`) — the `sh` wrapper bodies.
+- `POSIX_TEMPLATE` — the `sh` wrapper body, for a `.pyz` (absolute, or relative
+  to the wrapper) or `-m dotagents`. It runs the recorded interpreter; where that
+  does not run (a Windows store read from WSL) it takes the store's agents' venv
+  for this OS and machine (`.pyvenv/*-<os>-<arch>/bin/python`), else `python3`,
+  and turns a recorded `C:/...` pyz path into a local one with `wslpath`.
 - `write_wrappers(bin_dir, pyz_path, python=None, *, relative=False) -> list[Path]` —
   `dotagents` (sh) and `dotagents.cmd`, both always, running the `.pyz`.
 - `write_module_wrappers(bin_dir, python=None) -> list[Path]` — both forms running
@@ -706,10 +753,16 @@ code. `AGENTS_NO_PYVENV=1` (or `true`/`yes`/`on`) turns it all off.
   when the requirements' digest changed, in one `pip install -r ... -r ...` per
   venv, with `--find-links` from `AGENTS_PIP_SOURCE`. The `.pth` is rewritten when
   it differs: the store's own libs, then each lower store's venv site-packages and
-  libs, then `runtime_entry()`. Raises `VenvError` (a `SystemExit`) on failure.
+  libs, then `runtime_entry()`. Each venv's launchers (`_launchers.sync`) serve its
+  store's overlays and every lower store's; a project venv a sync made that is no
+  longer wanted keeps its launchers current too. With `AGENTS_NO_PYVENV` it logs
+  which scripts get no launcher. Raises `VenvError` or `LauncherError` (both
+  `SystemExit`) on failure.
 - `wants_venv(scope, level, store, libs) -> bool` — always for `user`; for `project`
-  when it has overlay requirements or libs; never for `system` (a venv an
+  when it has overlay requirements, libs or scripts; never for `system` (a venv an
   administrator made there is still layered).
+- `store_overlays(scope, stores) -> list[Overlay]` — the overlays in play
+  installed in any of `stores`.
 - `ensure_venv(target, python=None, *, with_pip=None, dry_run=False, logger=None)
   -> Optional[Path]` — the venv's interpreter, created when missing; `with_pip=None`
   tries ensurepip and falls back to `--without-pip`, `False` never uses it.
@@ -802,6 +855,8 @@ proxy vars, plus whatever the env files set. `AGENTS_AGENT` is never emitted.
 Set for an overlay's `setup.py`: `AGENTS_HOME` (user store), `AGENTS_SCOPE_ROOT`,
 `AGENTS_SCOPE`, `AGENTS_OVERLAY_DIR`.
 
+Read by a script launcher (`_launchers`): its overlay's `<NAME>_OVERLAY_ROOT`.
+
 ## Gotchas
 
 - **Python 3.9 floor.** Runtime-evaluated annotations need `from __future__ import

{dotagents_cli-0.8.0 → dotagents_cli-0.8.2}/src/dotagents/__init__.py

@@ -1,3 +1,3 @@
 """dotagents: installable CLI for the dotagents agent-config payload."""
 
-__version__ = "0.8.0"
+__version__ = "0.8.2"

{dotagents_cli-0.8.0 → dotagents_cli-0.8.2}/src/dotagents/_env.py

@@ -4,7 +4,8 @@ Contract B, the exact sequence :func:`get_environment` performs:
 
   1. **Bins onto PATH FIRST**, before any env eval. Each level's ``bin`` dir
      (contract-A precedence order, *except* project-root) is prepended to
-     ``PATH`` so env scripts can call overlay helpers by name. **Libs go on
+     ``PATH`` so env scripts can call overlay helpers by name, and ahead of
+     them the active venv's launcher dir (:func:`_launcher_path`). **Libs go on
      ``PYTHONPATH`` the same way**: each level's ``lib`` dir that EXISTS
      (:func:`get_lib_paths`) is prepended to ``PYTHONPATH`` and listed,
      ``os.pathsep``-joined, in ``AGENTS_PYTHONPATH`` -- so an ``env.py``, a
@@ -852,6 +853,25 @@ def _anchored(entry: str) -> bool:
     return bool(entry) and (os.path.isabs(entry) or entry[0] in "/\\")
 
 
+def _launcher_path(path: str, venv: "Optional[Path]") -> "Optional[str]":
+    """``PATH`` with ``venv``'s launcher dir (``<venv>/overlays``, the
+    overlays' ``[scripts]``: :mod:`dotagents._launchers`) first when it
+    exists, and every other dotagents venv's taken out: a launcher names its
+    own venv's interpreter. ``None`` if nothing changes.
+
+    First, ahead of the levels' ``bin`` dirs too: cmd.exe and PowerShell try
+    every ``PATHEXT`` extension in one directory before the next, so a
+    ``bin`` holding the script itself (``curl.py``, with ``.PY`` in
+    ``PATHEXT``) or a ``.cmd`` of the same name would otherwise win."""
+    from dotagents import _launchers
+
+    entries = [e for e in path.split(os.pathsep) if not (e and _launchers.is_launcher_dir(e))] if path else []
+    if venv is not None and _launchers.launcher_dir(venv).is_dir():
+        entries.insert(0, str(_launchers.launcher_dir(venv)))
+    updated = os.pathsep.join(entries)
+    return updated if updated != path else None
+
+
 def _prepended_path_var(osenv: "dict[str, str]", var: str, entries: "list[str]") -> "Optional[str]":
     """The new value of an ``os.pathsep``-joined path var with ``entries``
     prepended (:func:`_prepend_missing` order), or ``None`` if nothing changes.
@@ -1106,6 +1126,10 @@ def get_environment(
     updated = _prepended_path_var(osenv, "PATH", bin_paths)
     if updated is not None:
         _apply({"PATH": updated})
+    updated = _launcher_path(osenv.get("PATH", ""), venv if venv is not None
+                             and osenv.get("AGENTS_PYTHON") == str(_pyvenv.venv_python(venv)) else None)
+    if updated is not None:
+        _apply({"PATH": updated})
 
     # --- Libs: on PYTHONPATH, and published as AGENTS_PYTHONPATH, same moment.
     # Everything an overlay starts -- a skill script the agent runs, a `bin`

dotagents_cli-0.8.2/src/dotagents/_launchers.py

@@ -0,0 +1,241 @@
+"""Launchers for overlays' scripts: each top-level ``bin/<name>.py``, plus
+what ``overlay.toml`` declares (``Overlay.scripts``)::
+
+    [scripts]
+    tool = "lib/tool/main.py"   # another path, or another name
+    helper = false              # no launcher for bin/helper.py
+
+Each becomes an executable named after the key in ``<venv>/overlays/`` of a
+dotagents venv (:mod:`dotagents._pyvenv`), which ``env`` puts first on
+``PATH`` for the venv ``AGENTS_PYTHON`` names. A launcher runs the script
+under that venv's interpreter, found at RUN time through the overlay's
+``<NAME>_OVERLAY_ROOT``, so moving a store or syncing an overlay never
+strands it; only a new interpreter needs a new launcher. With the variable
+unset or the script missing it exits 2, saying so.
+
+* Windows: ``<name>.exe``, made by distlib's ``ScriptMaker`` (pip's console
+  script launcher) around a short Python bootstrap. A native program: no
+  command interpreter parses its arguments, as cmd.exe would a ``.cmd``'s.
+* POSIX: ``<name>``, a ``/bin/sh`` script that ``exec``s the interpreter.
+
+:data:`MANIFEST` in the directory records which overlay made which launcher,
+so one no overlay declares any more is deleted; files it does not list are
+left alone. Writes are atomic and happen only when the bytes differ.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+#: ``<venv>/overlays``: the launchers, and nothing of the venv's own.
+DIR = "overlays"
+MANIFEST = ".dotagents-launchers.json"
+#: The time stamped on the bootstrap in an ``.exe``'s archive (1980-01-01, the
+#: earliest a ZIP can hold): fixed, so equal inputs give equal bytes.
+_EPOCH = "315532800"
+
+
+class LauncherError(SystemExit):
+    """Two overlays declare the same script name."""
+
+
+def launcher_dir(venv: "str | os.PathLike[str]") -> Path:
+    return Path(venv) / DIR
+
+
+def is_launcher_dir(path: str) -> bool:
+    """Whether ``path`` has the shape of any dotagents venv's launcher dir
+    (``<store>/.pyvenv/<triplet>/overlays``); the filesystem is not consulted."""
+    from dotagents._pyvenv import PYVENV_DIR
+
+    parts = Path(os.path.normpath(path)).parts
+    fold = (lambda s: s.lower()) if os.name == "nt" else (lambda s: s)
+    return len(parts) >= 3 and fold(parts[-1]) == fold(DIR) and fold(parts[-3]) == fold(PYVENV_DIR)
+
+
+def file_name(name: str) -> str:
+    return name + ".exe" if os.name == "nt" else name
+
+
+def declared(overlays) -> "dict[str, tuple]":
+    """``{name: (overlay, script)}`` over ``overlays``; a name two overlays
+    declare is a :class:`LauncherError` naming both."""
+    out: "dict[str, tuple]" = {}
+    seen: "dict[str, str]" = {}
+    for overlay in overlays:
+        for name, script in overlay.scripts().items():
+            key = name.lower() if os.name == "nt" else name
+            if key in seen and out[seen[key]][0].path != overlay.path:
+                raise LauncherError(
+                    "error: overlays %s and %s both declare the script %r"
+                    % (out[seen[key]][0].name, overlay.name, name)
+                )
+            seen[key] = name
+            out[name] = (overlay, script)
+    return out
+
+
+def _bootstrap(name: str, var: str, script: str) -> str:
+    """The Python an ``.exe`` runs: the script as ``__main__``, as
+    ``python <script>`` would."""
+    return "\n".join([
+        "#!python",
+        "import os",
+        "import runpy",
+        "import sys",
+        "",
+        "root = os.environ.get(%r, '')" % var,
+        "script = os.path.join(root, *%r)" % (script.split("/"),),
+        "if not root or not os.path.isfile(script):",
+        "    sys.stderr.write(%r %% root)" % (
+            "%s: %s=%%s has no %s: run it in a `dotagents env` session\n" % (name, var, script)),
+        "    sys.exit(2)",
+        "sys.argv[0] = script",
+        "sys.path[0] = os.path.dirname(script)",
+        "runpy.run_path(script, run_name='__main__')",
+        "",
+    ])
+
+
+def _sh_quote(text: str) -> str:
+    return "'%s'" % text.replace("'", "'\\''")
+
+
+def _shell(name: str, var: str, script: str, python: str) -> bytes:
+    message = "%s: %s=${%s:-} has no %s: run it in a dotagents env session" % (name, var, var, script)
+    path = '"$%s"%s' % (var, _sh_quote("/" + script))
+    return "\n".join([
+        "#!/bin/sh",
+        "# Made by dotagents from overlay.toml [scripts]; regenerated on overlays sync.",
+        'if [ -z "${%s:-}" ] || [ ! -f %s ]; then' % (var, path),
+        '    echo "%s" >&2' % message,
+        "    exit 2",
+        "fi",
+        "exec %s %s \"$@\"" % (_sh_quote(python), path),
+        "",
+    ]).encode("utf-8")
+
+
+def _exe(name: str, var: str, script: str, python: str, work: str) -> bytes:
+    from distlib.scripts import ScriptMaker
+
+    source = os.path.join(work, "source")
+    out = os.path.join(work, "out")
+    os.mkdir(source)
+    os.mkdir(out)
+    with open(os.path.join(source, name + ".py"), "w", encoding="utf-8", newline="\n") as handle:
+        handle.write(_bootstrap(name, var, script))
+    maker = ScriptMaker(source, out, add_launchers=True)
+    maker.executable = python
+    maker.variants = {""}
+    saved = os.environ.get("SOURCE_DATE_EPOCH")
+    os.environ["SOURCE_DATE_EPOCH"] = _EPOCH
+    try:
+        maker.make(name + ".py")
+    finally:
+        if saved is None:
+            del os.environ["SOURCE_DATE_EPOCH"]
+        else:
+            os.environ["SOURCE_DATE_EPOCH"] = saved
+    with open(os.path.join(out, name + ".exe"), "rb") as handle:
+        return handle.read()
+
+
+def render(name: str, var: str, script: str, python: str) -> bytes:
+    """The bytes of launcher ``name`` for this platform."""
+    if os.name != "nt":
+        return _shell(name, var, script, python)
+    work = tempfile.mkdtemp(prefix="dotagents-launcher-")
+    try:
+        return _exe(name, var, script, python, work)
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+
+
+def _read(path: Path) -> "Optional[bytes]":
+    try:
+        with open(str(path), "rb") as handle:
+            return handle.read()
+    except OSError:
+        return None
+
+
+def _write(path: Path, data: bytes, mode: "Optional[int]") -> None:
+    partial = path.with_name(".%s.new" % path.name)
+    with open(str(partial), "wb") as handle:
+        handle.write(data)
+    if mode is not None:
+        os.chmod(str(partial), mode)
+    try:
+        os.replace(str(partial), str(path))
+    except OSError:
+        os.unlink(str(partial))
+        raise
+
+
+def sync(venv: Path, python: Path, overlays, *, dry_run: bool = False, logger=None) -> "list[str]":
+    """Make ``<venv>/overlays`` hold exactly the launchers ``overlays``
+    declare (interpreter ``python``), deleting those :data:`MANIFEST` lists
+    that no overlay declares any more. Returns the launcher names written or
+    deleted. A name declared twice is a :class:`LauncherError`, before any
+    write."""
+    wanted = declared(overlays)
+    target = launcher_dir(venv)
+    manifest_path = target / MANIFEST
+    try:
+        recorded = json.loads((_read(manifest_path) or b"{}").decode("utf-8"))
+    except ValueError:
+        recorded = {}
+    if not isinstance(recorded, dict):
+        recorded = {}
+    changed: "list[str]" = []
+    for name in sorted(set(recorded) - set(wanted)):
+        path = target / file_name(name)
+        if path.exists():
+            _log(logger, "info", "launcher %s: removed (no overlay declares it)%s", path, _dry(dry_run))
+            if not dry_run:
+                path.unlink()
+        changed.append(name)
+    for name, (overlay, script) in sorted(wanted.items()):
+        if not (overlay.path / script).is_file():
+            _log(logger, "warning", "overlay %s: script %s (%s) not found; its launcher exits 2 until it is",
+                 overlay.name, name, script)
+        data = render(name, overlay.root_var, script, str(python))
+        path = target / file_name(name)
+        if _read(path) == data:
+            continue
+        _log(logger, "info", "launcher %s: %s (%s)%s", path, "updated" if path.exists() else "created",
+             overlay.name, _dry(dry_run))
+        changed.append(name)
+        if not dry_run:
+            target.mkdir(parents=True, exist_ok=True)
+            _write(path, data, None if os.name == "nt" else 0o755)
+    record = {name: overlay.name for name, (overlay, _script) in wanted.items()}
+    if not dry_run and record != recorded:
+        if record:
+            target.mkdir(parents=True, exist_ok=True)
+            _write(manifest_path, (json.dumps(record, indent=1, sort_keys=True) + "\n").encode("utf-8"), None)
+        elif manifest_path.exists():
+            manifest_path.unlink()
+            try:
+                target.rmdir()
+            except OSError:
+                pass  # something else lives there: left alone
+    return changed
+
+
+def _dry(dry_run: bool) -> str:
+    return " [dry-run]" if dry_run else ""
+
+
+def _log(logger, level: str, message: str, *args) -> None:
+    if logger is not None:
+        getattr(logger, level)(message, *args)
+    elif level == "warning":
+        sys.stderr.write("warning: " + (message % args) + "\n")