flexlock 0.8.2__tar.gz → 0.9.0__tar.gz

flexlock-0.9.0/.github/scripts/check_version.py

@@ -0,0 +1,35 @@
+"""Check that the version declarations agree (and match the tag, if given).
+
+The wheel version comes from ``flexlock/__init__.py`` (hatch dynamic version);
+the conda package version from ``[tool.pixi.package] version`` in
+pyproject.toml. Usage: ``python .github/scripts/check_version.py [vX.Y.Z]``.
+"""
+
+import re
+import sys
+import tomllib
+from pathlib import Path
+
+root = Path(__file__).resolve().parents[2]
+init = (root / "flexlock" / "__init__.py").read_text()
+m = re.search(r'^__version__\s*=\s*"([^"]+)"', init, re.M)
+if not m:
+    sys.exit("could not find __version__ in flexlock/__init__.py")
+py_version = m.group(1)
+
+pixi_version = tomllib.loads((root / "pyproject.toml").read_text())["tool"]["pixi"]["package"]["version"]
+
+errors = []
+if py_version != pixi_version:
+    errors.append(
+        f"flexlock/__init__.py __version__={py_version!r} != "
+        f"[tool.pixi.package] version={pixi_version!r}"
+    )
+if len(sys.argv) > 1:
+    tag = sys.argv[1].removeprefix("refs/tags/")
+    if tag != f"v{py_version}":
+        errors.append(f"tag {tag!r} does not match package version v{py_version}")
+
+if errors:
+    sys.exit("\n".join(errors))
+print(f"version OK: {py_version}")

flexlock-0.9.0/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  tests:
+    name: tests (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0  # git_utils / snapshot tests inspect history
+
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          activate-environment: true
+
+      - name: Install package and test deps
+        # Mirrors [tool.pixi.feature.test]; attrs is needed by test_utils.
+        run: uv pip install -e . "pytest>=8.3.2,<9" "pytest-mock>=3.14.0,<4" ipython attrs
+
+      - name: Git identity (tests create repos and commits)
+        run: |
+          git config --global user.name "flexlock-ci"
+          git config --global user.email "flexlock-ci@users.noreply.github.com"
+
+      - name: Run tests
+        run: pytest -q
+
+  build:
+    name: build sdist/wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.11"
+
+      - name: Check version declarations agree
+        run: python .github/scripts/check_version.py
+
+      - run: uv build
+
+      - name: Wheel installs into a clean venv and imports
+        run: |
+          uv venv /tmp/wheelcheck
+          uv pip install --python /tmp/wheelcheck/bin/python dist/*.whl
+          cd /tmp && /tmp/wheelcheck/bin/python -c "import flexlock; print(flexlock.__version__)"
+          /tmp/wheelcheck/bin/flexlock --help > /dev/null

flexlock-0.9.0/.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: Docs
+
+# Builds the Sphinx docs on every PR; deploys to GitHub Pages
+# (https://quentinf00.github.io/flexlock/) on pushes to main.
+# Requires Settings > Pages > Source = "GitHub Actions".
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.11"
+          activate-environment: true
+
+      - name: Install docs deps
+        # Mirrors [tool.pixi.feature.docs]; conf.py imports flexlock.
+        run: uv pip install . sphinx myst-parser sphinx-rtd-theme
+
+      - name: Build HTML
+        run: |
+          sphinx-build -b html docs docs/_build/html
+          touch docs/_build/html/.nojekyll
+
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: docs/_build/html
+
+  deploy:
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

flexlock-0.9.0/.github/workflows/release.yml

@@ -0,0 +1,93 @@
+name: Release
+
+# Push a tag vX.Y.Z (matching flexlock/__init__.py and [tool.pixi.package]
+# version) to build and publish the PyPI and conda packages.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build-dist:
+    name: build sdist/wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.11"
+
+      - name: Tag matches package versions
+        run: python .github/scripts/check_version.py "${GITHUB_REF_NAME}"
+
+      - run: uv build
+
+      - name: Wheel installs into a clean venv and imports
+        run: |
+          uv venv /tmp/wheelcheck
+          uv pip install --python /tmp/wheelcheck/bin/python dist/*.whl
+          cd /tmp && /tmp/wheelcheck/bin/python -c "import flexlock; print(flexlock.__version__)"
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    # Enable this repository variable after configuring the corresponding
+    # trusted publisher on PyPI. Local twine publishing works independently.
+    if: vars.PYPI_TRUSTED_PUBLISHING == 'true'
+    name: publish to PyPI (trusted publishing)
+    needs: build-dist
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/flexlock
+    permissions:
+      id-token: write  # OIDC token for PyPI trusted publishing; no stored secret
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  conda:
+    name: build + upload conda package (anaconda.org/quentinf00)
+    runs-on: ubuntu-latest
+    env:
+      ANACONDA_API_TOKEN: ${{ secrets.ANACONDA_API_TOKEN }}
+    environment:
+      name: anaconda
+      url: https://anaconda.org/quentinf00/flexlock
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Tag matches package versions
+        run: python3 .github/scripts/check_version.py "${GITHUB_REF_NAME}"
+
+      - uses: prefix-dev/setup-pixi@d3f436a425481402e6a95a1d1fc10331c708cd9e # v0.10.2
+        with:
+          pixi-version: v0.73.0
+          run-install: false
+
+      - name: Build conda package ([tool.pixi.package], pixi-build-python)
+        run: pixi build --output-dir conda-out
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: conda-package
+          path: conda-out/*.conda
+          if-no-files-found: error
+
+      - name: Upload to anaconda.org
+        if: env.ANACONDA_API_TOKEN != ''
+        run: |
+          pixi exec --spec "anaconda-client>=1.14" -- \
+            anaconda -s api.anaconda.org -t "$ANACONDA_API_TOKEN" \
+            upload --user quentinf00 --label main conda-out/*.conda

flexlock-0.9.0/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+## 0.9.0 (2026-10-02)
+
+### Added
+- Composite pipelines across sweeps, local/HPC workers, and enqueue/dequeue.
+- Full per-stage run records in directories or the task DB, including upstream
+  references, code provenance, and code-drift detection.
+- Environment lockfiles in run fingerprints.
+- Preset tracking and `flexlock runs` / `flexlock presets`.
+- `${run:...}` references to completed preset runs and `key=@name` config swaps.
+
+### Fixed
+- Composite task snapshots retain every executed stage instead of overwriting
+  earlier stage records. Exports include each stage's inherited code and environment.
+
+### Release infrastructure
+- CI on Python 3.11–3.13, wheel/sdist checks, tag-driven PyPI and conda publishing,
+  and GitHub Pages documentation.
+
+The unreleased 0.8.3 fixes below are included in this release.
+
+## 0.8.3 (unreleased)
+
+### Fixed
+- **Single HPC / `isolated=True` runs now get a full `run.lock`.** They used to
+  keep the submit-time placeholder (`config` = `save_dir` + `_snapshot_` only)
+  because the worker stored the real snapshot only in `run.lock.tasks.db`. That
+  broke `${run_lock:...}` (`KeyError`), made `flexlock-run -c run.lock` a
+  silent no-op, showed empty configs in `show`/`diff`/`ls`, linked no commits
+  on `tag`, and let `gc` delete the upstreams of a tagged run. The worker now
+  writes the full snapshot (config, fingerprint, git state, `note`) atomically
+  when its task owns the master dir. Sweep roots keep their placeholder.
+- Readers (`${run_lock:...}`, `show`/`graph`/`why`/`report`, `flexlock-diff`,
+  `ls`/`gc`/`tag`, `load_stage`, lineage, `flexlock-run -c run.lock`) fall back
+  to the task-DB snapshot for placeholder `run.lock`s written by older versions.
+- The worker refreshes `run.lock.tasks` when its queue drains, so it is no
+  longer left at `[]` after a `wait=False` submit.
+- `force=True` on a single HPC / isolated submission deleted `run.complete` but
+  ran nothing: the old `done` row in the task DB was kept by `INSERT OR IGNORE`.
+  The task DB is now reset and the task re-executes. The reset also drops the
+  cached sqlite connection, which kept writing to the deleted DB file.
+- Slurm backend: forkserver compatibility fix.
+- `docs/hpc_integration.md`: the task DB lives inside `save_dir`, not in its
+  parent. The overview section, clobbered by an earlier edit, is restored.
+
+### Added
+- `flexlock.run_record.load_lock_data(run_dir)`: side-effect-free effective
+  `run.lock` (placeholder → task-DB snapshot).
+- `flexlock.run_record.materialize_lock(run_dir)`: one-off rewrite of a
+  placeholder `run.lock` (keeps `run.lock.placeholder.bak`).
+- `flexlock repair-locks <root> [-n]`: runs `materialize_lock` over a results tree.
+- `flexlock.taskdb.reset_db(db_path)`.

flexlock-0.8.2/.claude/worktrees/dedup-deps/README.md → flexlock-0.9.0/PKG-INFO

@@ -1,3 +1,19 @@
+Metadata-Version: 2.5
+Name: flexlock
+Version: 0.9.0
+Summary: A lightweight and painless SciOps library
+Author-email: Quentin Febvre <quentin.febvre@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: cloudpickle<4,>=3.0.0
+Requires-Dist: gitpython<4,>=3.1.46
+Requires-Dist: joblib<2,>=1.5.2
+Requires-Dist: loguru<0.8,>=0.7.3
+Requires-Dist: omegaconf<3,>=2.3.0
+Requires-Dist: pandas<3,>=2.3.0
+Requires-Dist: xxhash<4,>=3.5.0
+Description-Content-Type: text/markdown
+
 # FlexLock
 
 **Reproducible, Composable, and Scalable Computational Experiments**
@@ -292,14 +308,24 @@ pip install -e .
 
 ## Comparison with Other Tools
 
-| Feature | FlexLock | Hydra | MLflow | DVC |
-|---------|----------|-------|--------|-----|
-| **Configuration** | Python + YAML | YAML | Code | YAML |
-| **Reproducibility** | Automatic | Manual | Partial | Partial |
-| **Smart Caching** | ✅ | ❌ | ❌ | ✅ |
-| **Multi-stage Pipelines** | ✅ | ❌ | ❌ | ✅ |
-| **Parallel Sweeps** | ✅ | ✅ | ❌ | ❌ |
-| **Learning Curve** | Low | Medium | Low | High |
+FlexLock combines Hydra-style configuration (overrides, sweeps, callables as
+config) with DVC-style provenance (runs traceable to code, config and data,
+and skipped when unchanged). It grew out of
+[ZenDag](https://github.com/quentinf00/zendag), which generated DVC pipelines
+from Hydra configs. The key difference: the cache key belongs to each run,
+not to a workspace lockfile, so sweeps and HPC jobs need no shared state
+beyond the filesystem.
+
+| | FlexLock | Hydra | DVC | redun | Snakemake |
+|---|---|---|---|---|---|
+| Overrides and sweeps | ✅ | ✅ | ✅ `dvc exp` | ❌ | ❌ |
+| Skips unchanged runs | ✅ per run | ❌ | ✅ per stage | ✅ per call | ✅ per rule |
+| Code identity in cache key | git tree of `_target_` modules | ❌ | listed deps | task source | rule code |
+| Slurm / PBS | ✅ | ✅ submitit | ❌ | ❌ cloud only | ✅ |
+| Remote output storage | ❌ | ❌ | ✅ | ✅ | ✅ |
+
+See [Philosophy & Design](docs/philosophy.md#comparison-with-other-tools) for
+the full comparison and when to pick another tool.
 
 ## Contributing
 

flexlock-0.8.2/PKG-INFO → flexlock-0.9.0/README.md

@@ -1,19 +1,3 @@
-Metadata-Version: 2.4
-Name: flexlock
-Version: 0.8.2
-Summary: A lightweight and painless SciOps library
-Author-email: Quentin Febvre <quentin.febvre@gmail.com>
-License-Expression: MIT
-Requires-Python: >=3.11
-Requires-Dist: cloudpickle<4,>=3.0.0
-Requires-Dist: gitpython<4,>=3.1.45
-Requires-Dist: joblib<2,>=1.5.2
-Requires-Dist: loguru<0.8,>=0.7.3
-Requires-Dist: omegaconf<3,>=2.3.0
-Requires-Dist: pandas<3,>=2.3.2
-Requires-Dist: xxhash<4,>=3.5.0
-Description-Content-Type: text/markdown
-
 # FlexLock
 
 **Reproducible, Composable, and Scalable Computational Experiments**
@@ -308,14 +292,24 @@ pip install -e .
 
 ## Comparison with Other Tools
 
-| Feature | FlexLock | Hydra | MLflow | DVC |
-|---------|----------|-------|--------|-----|
-| **Configuration** | Python + YAML | YAML | Code | YAML |
-| **Reproducibility** | Automatic | Manual | Partial | Partial |
-| **Smart Caching** | ✅ | ❌ | ❌ | ✅ |
-| **Multi-stage Pipelines** | ✅ | ❌ | ❌ | ✅ |
-| **Parallel Sweeps** | ✅ | ✅ | ❌ | ❌ |
-| **Learning Curve** | Low | Medium | Low | High |
+FlexLock combines Hydra-style configuration (overrides, sweeps, callables as
+config) with DVC-style provenance (runs traceable to code, config and data,
+and skipped when unchanged). It grew out of
+[ZenDag](https://github.com/quentinf00/zendag), which generated DVC pipelines
+from Hydra configs. The key difference: the cache key belongs to each run,
+not to a workspace lockfile, so sweeps and HPC jobs need no shared state
+beyond the filesystem.
+
+| | FlexLock | Hydra | DVC | redun | Snakemake |
+|---|---|---|---|---|---|
+| Overrides and sweeps | ✅ | ✅ | ✅ `dvc exp` | ❌ | ❌ |
+| Skips unchanged runs | ✅ per run | ❌ | ✅ per stage | ✅ per call | ✅ per rule |
+| Code identity in cache key | git tree of `_target_` modules | ❌ | listed deps | task source | rule code |
+| Slurm / PBS | ✅ | ✅ submitit | ❌ | ❌ cloud only | ✅ |
+| Remote output storage | ❌ | ❌ | ✅ | ✅ | ✅ |
+
+See [Philosophy & Design](docs/philosophy.md#comparison-with-other-tools) for
+the full comparison and when to pick another tool.
 
 ## Contributing
 

{flexlock-0.8.2/.claude/worktrees/dedup-deps → flexlock-0.9.0}/docs/api.rst

@@ -111,6 +111,11 @@ FlexLock API Reference
    :undoc-members:
    :show-inheritance:
 
+.. automodule:: flexlock.run_record
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 .. automodule:: flexlock.taskdb
    :members:
    :undoc-members:

flexlock-0.9.0/docs/changelog.md

@@ -0,0 +1,2 @@
+```{include} ../CHANGELOG.md
+```

{flexlock-0.8.2/.claude/worktrees/dedup-deps → flexlock-0.9.0}/docs/cli_reference.md

@@ -88,6 +88,22 @@ flexlock gc results/ -f --refs
 
 ---
 
+### `flexlock repair-locks` — Rewrite Placeholder run.locks
+
+Single HPC/isolated runs submitted with FlexLock < 0.8.3 kept their real
+snapshot only in `run.lock.tasks.db`; their `run.lock` is a placeholder. The
+readers fall back to the DB automatically. This command rewrites those files
+once (see [HPC Integration](hpc_integration.md#runlock-of-a-single-hpc-run)).
+
+```bash
+flexlock repair-locks results/ -n   # dry run: list the dirs that would change
+flexlock repair-locks results/      # rewrite; keeps run.lock.placeholder.bak
+```
+
+Sweep roots are left alone (they have no single config).
+
+---
+
 ### `flexlock show` — Inspect One Run
 
 Machine-readable status, metadata, lineage, and config for a single run. The
@@ -153,6 +169,35 @@ DEF=myproject.pipeline.cfg
 flexlock-run -d "$DEF" -s "$(flexlock stages -d "$DEF" --format keys | fzf)"
 ```
 
+### `flexlock runs` — Runs of a Preset
+
+List the complete runs of a preset (the `-d` target + `-s` key they were
+launched with), newest first. See the usage guide, §7 "Presets".
+
+```bash
+flexlock runs xps_glob.train_small_cloud_gap_compact          # suffix match
+flexlock runs pkg.starter.xps_glob:train_x -s main --limit 5
+flexlock runs train_x --strict        # only runs made with no -o/-O/-m/-M
+flexlock runs train_x --format json   # {path, preset, select, completed, note, overrides}
+flexlock runs train_x --root results_old   # also search results_old/.flexlock
+```
+
+Searched: the `.flexlock/` serving the current directory, any `.flexlock/` up
+to two levels below it, and `--root` dirs. Links to deleted runs are pruned.
+
+### `flexlock presets` — Catalogue of a Config Module
+
+List the attributes of a config module that hold runnable stages, with the
+comment block above each definition, the `-s` keys, and run counts.
+
+```bash
+flexlock presets sst_ml_mapping.starter.xps_glob               # text
+flexlock presets sst_ml_mapping.starter.xps_glob --format md   # a generated index
+flexlock presets configs/defaults.py --format json
+```
+
+The module is imported, as `flexlock-run -d` would.
+
 ### `flexlock report` — Static HTML Report
 
 Render a self-contained, offline-openable HTML report (no CDN) of a results tree.
@@ -281,8 +326,23 @@ flexlock-run -d myproject.defaults -s train
 
 # Select nested node
 flexlock-run -d myproject.defaults -s experiments.baseline
+
+# Multi-stage: run several stages in order as a pipeline (space- or
+# comma-separated). Each sweep item becomes one composite pipeline task.
+flexlock-run -d myproject.defaults -s train linear_probe -o pipeline_dir=results/xp
+flexlock-run -d myproject.defaults -s train,linear_probe \
+    --sweep-target pipeline_dir --sweep results/xp1,results/xp2 --n_jobs 2
 ```
 
+**Multi-stage (`-s` with more than one stage)** runs the stages sequentially as
+a pipeline (a downstream stage sees the upstream stage's artifacts on disk). It
+composes with `--sweep*`, `--slurm-config`/`--pbs-config`, and `--enqueue`:
+each sweep item is merged into the root config before selection, then becomes
+one composite `{_stages_: [...]}` task whose stages run in order on one worker,
+while parallelism / array workers fan out across items. It is only incompatible
+with `-O`/`-M` and `-e` (they target a single selected node). See usage guide
+§14g. All stages of an item share one scheduler job (no per-stage HPC resources).
+
 **Works with:**
 - Python configs (dict keys)
 - YAML configs (nested keys)
@@ -320,6 +380,11 @@ flexlock-run -d defaults -o base_dir=outputs seed=42
 - Primitive types: `param=1`, `flag=true`, `name=model`
 - Nested paths: `model.layers=12`
 - Lists: `devices=[0,1,2]`
+- Swaps: `model=@big_model` **replaces** the node with the config
+  `big_model` from the `-d` module (or `@pkg.module.attr`); `@@x` is the
+  literal `@x`. Overrides apply in order, so `model=@big_model model.width=16`
+  tweaks the swapped model. Also valid for `-O` and in `--sweep` values. See
+  the usage guide, "Swapping a subtree".
 
 ---
 
@@ -515,9 +580,30 @@ perturb caching or diffs. It surfaces in `flexlock show`/`graph`/`report`.
 flexlock-run -d defaults -s train --note "baseline before lr sweep"
 ```
 
-For sweeps the note lands on the **master** `run.lock` only; sweep items inherit
-it for display via their `.flexlock_marker` → master lookup. For a multi-stage
-`-s a b` run, the same note is applied to each stage.
+For sweeps the note lands on the **master** `run.lock`; sweep items inherit it
+(copied into each task's `run.lock` with `--task-record dir`, looked up through
+the master otherwise). For a multi-stage `-s a b` run, the same note is applied
+to each stage.
+
+---
+
+### `--task-record {dir,db}`
+Where each sweep task's record (config, code tree, env, fingerprint) is kept.
+
+- `dir` (default, or `$FLEXLOCK_TASK_RECORD`): a full `run.lock` in the task's
+  `save_dir`, like a serial run. The directory describes itself.
+- `db`: only in the task DB (`<sweep_root>/run.lock.tasks.db`), with a
+  `.flexlock_marker` pointer in the task dir. Use it for sweeps over thousands
+  of items (e.g. `--sweep-file paths.txt`) to avoid one more file per item.
+
+Either way `flexlock diff`/`show`/`graph`/`why`, `${run_lock:}`, lineage and the
+cache find the record. Single runs, including Slurm/PBS ones, always get a
+`run.lock`. Sweep items that share one `save_dir` can't each have a
+`run.lock`; the first task keeps the file and the others stay in the DB.
+
+```bash
+flexlock-run -d configs.defaults -s extract --sweep-file paths.txt --task-record db
+```
 
 ---
 
@@ -572,8 +658,18 @@ flexlock-run -d defaults -s train --sweep-file queue.yaml --slurm-config slurm.y
   save_dir: results/exp
 ```
 
+**With a sweep** (`--sweep`/`--sweep-key`/`--sweep-file`), `--enqueue` appends
+**one entry per sweep item** — each merged at `--sweep-target` and frozen —
+instead of a single config. Previously the sweep was silently dropped.
+
+**With multi-stage** (`-s` with more than one stage), `--enqueue` appends **one
+composite `{_stages_: [...]}` entry per sweep item** (or one for a no-sweep
+pipeline). Composite entries in a `--sweep-file` run as-is; plain entries in the
+same file are merged into the compiled node config and run as single-stage
+pipelines.
+
 **Notes:**
-- The enqueued config is stored with interpolations **unresolved** so that resolvers like `${vinc:}` fire at run time and each task gets its own unique directory.
+- The enqueued config is stored with interpolations **unresolved** so that resolvers like `${vinc:}`/`${run_lock:}`/`${latest:}` fire at run time and each task gets its own unique directory.
 - Writes are atomic (temp-file + rename) so concurrent `--enqueue` calls from different terminals are safe.
 - Re-running `--sweep-file queue.yaml` after adding new items is safe: tasks already completed are skipped via the `INSERT OR IGNORE` logic in the task DB.