calkit-python 0.47.8__py3-none-any.whl → 0.47.9__py3-none-any.whl

calkit/agent_skills/conventions/SKILL.md

@@ -25,6 +25,8 @@ is `calkit.yaml`, the project's metadata database.
 - `environments`—computational environments (Python venvs, Conda, Docker,
   R, Julia, MATLAB, etc.)
 - `pipeline.stages`—the reproducible pipeline
+- `questions`—research questions, hypotheses, and answers backed by
+  evidence the pipeline produces
 - `notebooks`—registered Jupyter notebooks
 - `datasets`, `figures`, `publications`—versioned project outputs
 - `procedures`, `calculations`, `references`—supporting metadata
@@ -209,6 +211,9 @@ DVC handles:
 | `calkit add <file>`             | Add a file to version control                        |
 | `calkit check env --name <env>` | Verify an environment matches its spec               |
 | `calkit new`                    | Create new project objects (notebook, dataset, etc.) |
+| `calkit new question "<text>"`  | Record a research question                           |
+| `calkit list questions`         | Show questions with answers rendered from evidence   |
+| `calkit check questions`        | Check answers against current evidence               |
 
 ## `calkit xr`: The fastest path to a reproducible stage
 
@@ -233,6 +238,27 @@ calkit xr scripts/run.py --environment main
 calkit xr scripts/run.py --dry-run    # see what would happen without running
 ```
 
+## Questions and answers
+
+Research in a Calkit project is organized around the `questions` list in
+`calkit.yaml`. Follow this workflow:
+
+1. Before starting an analysis, make sure the question it answers is
+   recorded, e.g., with `calkit new question`. If the user hasn't stated
+   one, ask them for it rather than inventing it. Add a `hypothesis` if
+   they have one.
+2. Produce evidence with pipeline stages, never by hand, so every figure,
+   table, and number traces back to data and code.
+3. Write the `answer` citing that evidence. Read numbers out of results
+   files and put them in the prose with `{name}` placeholders instead of
+   typing them in, either one per `kind: value` entry, or several from one
+   file with a `kind: result` entry's `values` mapping of names to keys.
+4. After a pipeline run changes results, run `calkit check questions`,
+   then use the `check-questions` skill to judge whether each answer's
+   wording still follows from its evidence.
+
+See the Calkit docs on questions for the full evidence schema.
+
 ## Version control conventions
 
 - Source code and small outputs: tracked with Git

calkit/cli/config.py

@@ -12,7 +12,7 @@ import typer
 from typing_extensions import Annotated
 
 import calkit
-from calkit.cli.core import raise_error
+from calkit.cli.core import raise_error, warn
 
 config_app = typer.Typer(no_args_is_help=True)
 
@@ -189,9 +189,17 @@ def setup_remote(
 ):
     """Set up the Calkit hub as the default DVC remote and store a token
     in the local config.
+
+    Deprecated: this configures the project, not Calkit itself, which is
+    what the rest of this app is for.
     """
     from git.exc import InvalidGitRepositoryError
 
+    warn(
+        "'calkit config remote' is deprecated; use 'calkit update hub', "
+        "which also creates the project on the hub if it isn't there"
+    )
+
     from calkit.dvc import configure_remote, set_remote_auth
 
     try:

calkit/cli/latex.py

@@ -137,6 +137,20 @@ def from_json(
             json2latex.dump(cmd_name, formatted, f)
 
 
+def _tex_env_vars(source_date_epoch: str | None) -> dict[str, str]:
+    r"""The environmental variables a TeX command needs, beyond the ambient.
+
+    ``FORCE_SOURCE_DATE`` is what makes pdfTeX apply the date to
+    ``\pdfcreationdate`` and friends, not only to the trailer ID.
+    """
+    if source_date_epoch is None:
+        return {}
+    return {
+        "SOURCE_DATE_EPOCH": source_date_epoch,
+        "FORCE_SOURCE_DATE": "1",
+    }
+
+
 @latex_app.command(name="from-questions")
 def from_questions(
     output_fpaths: Annotated[
@@ -180,6 +194,7 @@ def _tex_cmd(
     no_check: bool,
     verbose: bool,
     dep: str,
+    env_vars: dict[str, str] | None = None,
 ) -> list[str]:
     """Wrap a TeX command so it runs wherever the project's TeX lives.
 
@@ -189,31 +204,162 @@ def _tex_cmd(
     inside the project -- which is why the diff builds its copy of the
     base revision there rather than in a temp directory.
     """
+    env_vars = env_vars or {}
     if environment is not None:
         cmd = (
             ["calkit", "xenv", "--name", environment]
             + (["--no-check"] if no_check else [])
+            # Named rather than inherited: the environment may run in a
+            # container, which inherits nothing from here
+            + [f"--env-var={k}={v}" for k, v in env_vars.items()]
             + ["--"]
             + tex_cmd
         )
     elif calkit.check_dep_exists(dep):
         cmd = tex_cmd
     else:
+        # Pulled deliberately, since docker run's implicit pull of an
+        # image that isn't there can stall rather than report it
+        try:
+            calkit.docker.ensure_image_available(
+                calkit.latex.DEFAULT_LATEX_IMAGE
+            )
+        except ValueError as e:
+            raise_error(str(e))
+        # Packages fetched at run time go to the project's cache, which
+        # the working directory mount already covers, rather than over
+        # the image's own tree, which would hide the distribution entirely
+        os.makedirs(calkit.latex.get_texmf_cache_dir(), exist_ok=True)
         cmd = [
             "docker",
             "run",
             "--rm",
             "-v",
             f"{os.getcwd()}:/work",
+            "-e",
+            f"TEXMFHOME={calkit.latex.CONTAINER_TEXMF_DIR}",
             "-w",
             "/work",
-            "texlive/texlive:latest-full",
-        ] + tex_cmd
+        ]
+        # As the user, so a PDF doesn't come back owned by root
+        try:
+            cmd += ["--user", f"{os.getuid()}:{os.getgid()}"]
+        except AttributeError:
+            # Windows has no UID to map
+            pass
+        # The container gets its own environment, so anything the command
+        # needs has to be handed to it rather than inherited
+        for key, value in env_vars.items():
+            cmd += ["-e", f"{key}={value}"]
+        cmd += [calkit.latex.DEFAULT_LATEX_IMAGE] + tex_cmd
     if verbose:
         typer.echo(f"Running command: {cmd}")
     return cmd
 
 
+def _run_latexmk(
+    cmd: list[str],
+    env: dict[str, str] | None,
+    log_path: str,
+    fdb_path: str,
+    environment: str | None,
+    verbose: bool,
+) -> int:
+    """Run latexmk, fetching the TeX packages it's missing and retrying.
+
+    Only where what's fetched is kept with the project, i.e., Calkit's
+    LaTeX image, run directly or as a Docker environment built on it. A
+    system TeX is the user's to manage, and anything installed in another
+    container is gone when it exits. Returns latexmk's exit status.
+    """
+    import shlex
+
+    def in_tex(tex_cmd: list[str]) -> list[str]:
+        # Where the build runs, so what's installed is what it sees
+        return _tex_cmd(
+            tex_cmd,
+            environment=environment,
+            no_check=True,
+            verbose=verbose,
+            dep="latexmk",
+        )
+
+    def can_fetch() -> bool:
+        if environment is None:
+            return not calkit.check_dep_exists("latexmk")
+        envs = calkit.load_calkit_info().get("environments", {})
+        if envs.get(environment, {}).get("kind") != "docker":
+            return False
+        # The image switches to the project's cache when it's there
+        os.makedirs(calkit.latex.get_texmf_cache_dir(), exist_ok=True)
+        out = subprocess.run(
+            in_tex(["printenv", "TEXMFHOME"]), capture_output=True, text=True
+        ).stdout.strip()
+        return out.endswith("/.calkit/local/texmf")
+
+    fetched: set[str] = set()
+    fetchable = None
+    while True:
+        try:
+            subprocess.check_call(cmd, env=env)
+            return 0
+        except subprocess.CalledProcessError as e:
+            status = e.returncode
+        try:
+            with open(log_path, encoding="utf-8", errors="replace") as f:
+                log = f.read()
+        except OSError:
+            return status
+        # A file still missing after fetching it is one fetching can't fix
+        missing = [
+            f
+            for f in calkit.latex.find_missing_tex_files(log)
+            if f not in fetched
+        ]
+        if not missing:
+            return status
+        if fetchable is None:
+            fetchable = can_fetch()
+        if not fetchable:
+            return status
+        packages = []
+        for name in missing:
+            out = subprocess.run(
+                in_tex(["tlmgr", "search", "--global", "--file", f"/{name}"]),
+                capture_output=True,
+                text=True,
+            ).stdout
+            # Package names end with a colon; the paths under them are
+            # indented, and the first one ending in the file is its owner
+            owner = None
+            for line in out.splitlines():
+                if line.endswith(":") and not line.startswith((" ", "\t")):
+                    owner = line[:-1]
+                elif owner and line.strip().endswith(f"/{name}"):
+                    packages.append(owner)
+                    break
+        packages = list(dict.fromkeys(packages))
+        if not packages:
+            return status
+        typer.echo(
+            f"Fetching TeX packages for {', '.join(missing)}: "
+            f"{', '.join(packages)}"
+        )
+        install = in_tex(["tlmgr", "--usermode", "install", *packages])
+        if verbose:
+            typer.echo(f"Running command: {shlex.join(install)}")
+        # A font's install fails at its last step, updating the font map,
+        # which user mode can't do in this image, with the files already in
+        # place and usable. Whether it worked is the retry's to say.
+        if subprocess.run(install, capture_output=not verbose).returncode:
+            if verbose:
+                warn(f"tlmgr reported an error installing {packages}")
+        fetched.update(missing)
+        # Otherwise latexmk remembers the failure and won't try again
+        if os.path.isfile(fdb_path):
+            os.remove(fdb_path)
+
+
 @latex_app.command(name="build")
 def build(
     tex_file: Annotated[str, typer.Argument(help="The .tex file to compile.")],
@@ -300,6 +446,21 @@ def build(
     system environment if available. If not available, a TeX Live Docker
     container will be used.
     """
+    # latexmk records a failed run in its file database and then refuses
+    # to try again, reporting "Nothing to do" and exiting non-zero with no
+    # PDF. Running it again is the first thing anyone does after a
+    # failure, so the record is cleared when there is no PDF to show for
+    # it, which makes a retry a real retry.
+    tex_dir = os.path.dirname(tex_file) or "."
+    stem = Path(tex_file).stem
+    pdf_dir = output_dir if output_dir is not None else tex_dir
+    if not os.path.isfile(os.path.join(pdf_dir, stem + ".pdf")):
+        fdb_dir = aux_dir if aux_dir is not None else tex_dir
+        fdb_fpath = os.path.join(fdb_dir, stem + ".fdb_latexmk")
+        if os.path.isfile(fdb_fpath):
+            if verbose:
+                typer.echo(f"Removing {fdb_fpath} so latexmk will retry")
+            os.remove(fdb_fpath)
     # Now formulate the command
     latexmk_cmd = ["latexmk", "-pdf", "-cd"]
     if latexmk_rc_path is not None:
@@ -313,7 +474,6 @@ def build(
     # latexmk runs with -cd, so its -outdir/-auxdir are relative to the .tex
     # file's directory; convert the (current-directory-relative) Calkit paths
     # into that frame.
-    tex_dir = os.path.dirname(tex_file) or "."
     if output_dir is not None:
         rel = Path(os.path.relpath(output_dir, tex_dir)).as_posix()
         latexmk_cmd.append(f"-outdir={rel}")
@@ -324,16 +484,24 @@ def build(
     # User pass-through args come last so they can override Calkit's defaults.
     latexmk_cmd += latexmk_args
     latexmk_cmd.append(tex_file)
+    tex_env_vars = _tex_env_vars(calkit.latex.get_source_date_epoch(tex_file))
     cmd = _tex_cmd(
         latexmk_cmd,
         environment=environment,
         no_check=no_check,
         verbose=verbose,
         dep="latexmk",
+        env_vars=tex_env_vars,
     )
-    try:
-        subprocess.check_call(cmd)
-    except subprocess.CalledProcessError:
+    log_dir = aux_dir or output_dir or tex_dir
+    if _run_latexmk(
+        cmd,
+        env=(os.environ | tex_env_vars) if tex_env_vars else None,
+        log_path=os.path.join(log_dir, stem + ".log"),
+        fdb_path=os.path.join(log_dir, stem + ".fdb_latexmk"),
+        environment=environment,
+        verbose=verbose,
+    ):
         raise_error("latexmk failed")
 
 
@@ -1064,16 +1232,29 @@ def _build_diff(
         # defaults
         latexmk_cmd += latexmk_args
         latexmk_cmd.append(diff_tex_fpath)
+        tex_env_vars = _tex_env_vars(
+            calkit.latex.get_source_date_epoch(tex_file_fpath)
+        )
         cmd = _tex_cmd(
             latexmk_cmd,
             environment=environment,
             no_check=no_check,
             verbose=verbose,
             dep="latexmk",
+            env_vars=tex_env_vars,
         )
         typer.echo("Building the marked-up document")
         try:
-            subprocess.check_call(cmd)
+            status = _run_latexmk(
+                cmd,
+                env=(os.environ | tex_env_vars) if tex_env_vars else None,
+                log_path=os.path.join(aux_dir, f"{stem}-diff.log"),
+                fdb_path=os.path.join(aux_dir, f"{stem}-diff.fdb_latexmk"),
+                environment=environment,
+                verbose=verbose,
+            )
+            if status:
+                raise subprocess.CalledProcessError(status, cmd)
         except subprocess.CalledProcessError as e:
             # -silent hides why, so show the errors LaTeX logged
             log_path = Path(aux_dir, f"{stem}-diff.log")

calkit/cli/main/core.py

@@ -545,7 +545,7 @@ def get_status(
                     raise subprocess.CalledProcessError(result, "dvc init")
             except subprocess.CalledProcessError as e:
                 raise_error(f"Failed to initialize DVC repository: {e}")
-    valid_categories = ["project", "git", "dvc", "pipeline"]
+    valid_categories = ["project", "questions", "git", "dvc", "pipeline"]
     if categories is not None:
         for category in categories:
             if category not in valid_categories:
@@ -580,6 +580,37 @@ def get_status(
                 "Failed pipeline environment checks for: "
                 + ", ".join(pipeline_status.failed_environment_checks)
             )
+    # Checking questions needs to know which stages are stale, which is the
+    # expensive part of the pipeline status computed above, so reuse that
+    # rather than asking DVC a second time
+    questions_status = None
+    if "questions" in categories and ck_info.get("questions"):
+        from calkit.pipeline import frozen_tainted_stage_names
+        from calkit.questions import check_questions
+
+        stale_stages = None
+        frozen_stages = None
+        # A pipeline status that bailed out, e.g., on a failed environment
+        # check, has no staleness in it; let the check work it out itself
+        # rather than reporting evidence as current because nothing was
+        # computed
+        if (
+            pipeline_status is not None
+            and not pipeline_status.errors
+            and not pipeline_status.failed_environment_checks
+        ):
+            stale_stages = {
+                n.split("@")[0] for n in pipeline_status.stale_stage_names
+            }
+            try:
+                frozen_stages = frozen_tainted_stage_names(ck_info=ck_info)
+            except Exception:
+                frozen_stages = set()
+        questions_status = check_questions(
+            ck_info=ck_info,
+            stale_stages=stale_stages,
+            frozen_stages=frozen_stages,
+        )
     if as_json:
         status_dict: dict[str, Any] = {}
         if "project" in categories:
@@ -593,6 +624,8 @@ def get_status(
                     "timestamp": status.timestamp.isoformat(),
                 }
             )
+        if questions_status is not None:
+            status_dict["questions"] = questions_status.model_dump(mode="json")
         if "git" in categories:
             try:
                 repo = calkit.git.get_repo()
@@ -675,6 +708,16 @@ def get_status(
                 'Project status not set. Use "calkit new status" to update.'
             )
         typer.echo()
+    if questions_status is not None:
+        from calkit.questions import format_summary
+
+        print_sep("Questions")
+        # The summary can carry a check mark, which a Windows console
+        # can't encode
+        calkit.echo(format_summary(questions_status))
+        if not questions_status.ok:
+            typer.echo("Run 'calkit check questions' for detail.")
+        typer.echo()
     if "git" in categories:
         print_sep("Git")
         git_cmd = ["git", "status"]
@@ -861,7 +904,27 @@ def add(
     """
     import dvc.repo
     from dvc.exceptions import NotDvcRepoError
-    from git.exc import InvalidGitRepositoryError
+    from git.exc import GitCommandError, InvalidGitRepositoryError
+
+    def git_add(*paths_to_add: str) -> None:
+        """Stage paths, saying why rather than stopping if Git refuses.
+
+        Git refuses for reasons that don't make the rest of what was asked
+        for wrong, e.g., a path a .gitignore excludes, and this used to
+        shell out and ignore the exit status entirely. Paths are relative
+        to the working directory, which is what someone running this from
+        a subdirectory means.
+        """
+        try:
+            # Resolved here, since GitPython runs Git from the repo's root
+            # while these paths are relative to the working directory
+            repo.git.add(*[os.path.abspath(p) for p in paths_to_add])
+        except GitCommandError as e:
+            # GitPython labels and quotes what Git wrote; what it wrote is
+            # the part worth reading
+            reason = (e.stderr or str(e)).strip()
+            reason = reason.removeprefix("stderr: ").strip("'")
+            warn(f"Failed to add {', '.join(paths_to_add)} to Git: {reason}")
 
     if dry_run:
         typer.echo("Dry run: No files will be added")
@@ -944,7 +1007,7 @@ def add(
             for path in paths:
                 typer.echo(f"Would add {path} to {to}")
         elif to == "git":
-            subprocess.call(["git", "add"] + paths)
+            git_add(*paths)
         elif to == "dvc":
             for path in paths:
                 calkit.git.ensure_dvc_pointer_is_not_ignored(repo, path)
@@ -1040,6 +1103,8 @@ def add(
                 paths.append(changed_file)
         zip_path_map = calkit.dvc.zip.get_zip_path_map()
         pipeline_output_storage = calkit.pipeline.get_output_storage_map()
+        lock_out_paths = calkit.dvc.get_lock_out_paths()
+        dvc_scm = None
         for path in paths:
             # Check if this path is already registered as a zip
             posix_path = Path(path).as_posix()
@@ -1061,7 +1126,7 @@ def add(
                     typer.echo(
                         f"Adding {path} to Git since it's already in the repo"
                     )
-                    subprocess.call(["git", "add", path])
+                    git_add(path)
             elif path in dvc_paths:
                 if dry_run:
                     typer.echo(
@@ -1087,7 +1152,7 @@ def add(
                         typer.echo(
                             f"Adding {path} to Git per pipeline output storage"
                         )
-                        subprocess.call(["git", "add", path])
+                        git_add(path)
                 elif pipeline_storage == "dvc-zip":
                     if dry_run:
                         typer.echo(
@@ -1111,7 +1176,38 @@ def add(
                             f"Adding dvc.lock to Git "
                             f"({path} is a DVC pipeline output)"
                         )
-                        subprocess.call(["git", "add", "dvc.lock"])
+                        git_add("dvc.lock")
+            elif (
+                locked_out := next(
+                    (
+                        out
+                        for out in lock_out_paths
+                        if posix_path == out
+                        or posix_path.startswith(out + "/")
+                    ),
+                    None,
+                )
+            ) is not None:
+                # DVC already caches this, and it's only showing up at all
+                # because its ignore entry went missing, e.g., DVC removes
+                # every entry a failed repro added, including those for the
+                # stages that succeeded. Sized up like a new file, a small
+                # one would go to Git alongside DVC's copy.
+                if dry_run:
+                    typer.echo(
+                        f"Would ignore {path} ({path} is a DVC pipeline output)"
+                    )
+                else:
+                    typer.echo(
+                        f"Ignoring {path} since it's a DVC pipeline output"
+                    )
+                    # Where and how DVC itself would have written the entry
+                    if dvc_scm is None:
+                        dvc_scm = calkit.dvc.get_dvc_repo().scm
+                    gitignore = dvc_scm.ignore(os.path.abspath(locked_out))
+                    if gitignore:
+                        repo.git.add(gitignore)
+                    repo.git.add("dvc.lock")
             elif os.path.splitext(path)[-1] in DVC_EXTENSIONS:
                 if dry_run:
                     typer.echo(f"Would add {path} to DVC (per extension)")
@@ -1145,10 +1241,17 @@ def add(
                     typer.echo(f"Would add {path} to Git")
                 else:
                     typer.echo(f"Adding {path} to Git")
-                    subprocess.call(["git", "add", path])
+                    git_add(path)
     if not dry_run:
         if commit_message is not None:
-            subprocess.call(["git", "commit", "-m", commit_message])
+            try:
+                repo.git.commit("-m", commit_message)
+            except GitCommandError as e:
+                # Nothing staged is a normal outcome here, e.g., when what
+                # was asked for was already committed
+                output = f"{e.stdout or ''}{e.stderr or ''}"
+                if "nothing to commit" not in output:
+                    warn(f"Failed to commit: {output.strip() or e}")
         if push_commit:
             push()
     else:
@@ -1390,6 +1493,10 @@ def save(
     """
     if not paths and not save_all:
         raise_error("Paths must be provided if not using --all")
+    # Asked before anything else runs: the Git and DVC commands below read
+    # from the terminal too, and would take an answer typed ahead
+    if not no_push and not _has_somewhere_to_push():
+        no_push = not _offer_to_connect()
     if paths is not None:
         add(paths, to=to)
     elif save_all:
@@ -1603,6 +1710,9 @@ def push(
         if excluded:
             selected.discard(target)
     _warn_on_hub_mismatch()
+    if selected & {"git", "dvc"} and not _has_somewhere_to_push():
+        if not _offer_to_connect():
+            return
     if "dvc" in selected:
         remotes = calkit.dvc.get_remotes()
         if not no_check_auth:
@@ -1692,6 +1802,51 @@ def push(
     _tell_hub_we_pushed(sorted(selected), git_args)
 
 
+def _offer_to_connect() -> bool:
+    """Offer to connect a project that has nowhere to push to a hub.
+
+    Pushing it would fail on a Git remote that isn't there, which says
+    nothing about what to do next. What it needs is a hub, so offer one
+    rather than reporting the symptom. True if it can be pushed now.
+    """
+    from calkit.cli.update import update_hub
+    from calkit.dependencies import _is_interactive
+
+    typer.echo(
+        "This project isn't connected to a hub, so there's nowhere to "
+        "push its code and data."
+    )
+    if not _is_interactive():
+        warn("Skipping push; run 'calkit update hub' to connect")
+        return False
+    answer = typer.prompt(
+        "Connect it now? [Y/n]", default="y", show_default=False
+    )
+    if answer.strip().lower() not in ("", "y", "yes"):
+        warn("Skipping push; run 'calkit update hub' when you want to")
+        return False
+    update_hub()
+    return True
+
+
+def _has_somewhere_to_push() -> bool:
+    """Whether a push has anywhere at all to go.
+
+    Any remote counts, not only a hub's. Plenty of projects push to a Git
+    remote they set up themselves and keep their data elsewhere, and a
+    push for them works exactly as it always did.
+    """
+    try:
+        if calkit.git.get_repo().remotes:
+            return True
+    except Exception:
+        pass
+    try:
+        return bool(calkit.dvc.get_remotes())
+    except Exception:
+        return False
+
+
 def _is_connected_to_a_hub() -> bool:
     """Whether this project belongs to a hub at all.
 
@@ -3117,6 +3272,10 @@ def run(
     # last run's status stays inspectable; it is gitignored.
     os.environ.pop("CALKIT_PIPELINE_RUNNING", None)
     if failed:
+        try:
+            calkit.dvc.restore_output_ignores()
+        except Exception as e:
+            warn(f"Failed to re-ignore pipeline outputs: {e}")
         raise_error("Pipeline failed")
     else:
         calkit.echo("Pipeline completed successfully ✅")
@@ -3270,6 +3429,18 @@ def run_in_env(
             ),
         ),
     ] = None,
+    env_var: Annotated[
+        list[str],
+        typer.Option(
+            "--env-var",
+            help=(
+                "Environmental variable to set for the command, as "
+                "KEY=VALUE. Can be given multiple times. Set in the "
+                "process the command runs in, and passed into a container "
+                "for an environment that runs in one."
+            ),
+        ),
+    ] = [],
     verbose: Annotated[
         bool, typer.Option("--verbose", "-v", help="Print verbose output.")
     ] = False,
@@ -3316,6 +3487,15 @@ def run_in_env(
             "--setup only applies to a 'system' environment, and "
             f"'{env_name}' is of kind '{env.get('kind')}'"
         )
+    # Set here rather than per kind: a container is handed them below,
+    # and everything else runs as a child of this process
+    extra_env_vars = {}
+    for item in env_var:
+        key, sep, value = item.partition("=")
+        if not sep or not key:
+            raise_error(f"Invalid --env-var '{item}'; write it as KEY=VALUE")
+        extra_env_vars[key] = value
+        os.environ[key] = value
     docker_wdir = env.get("wdir", "/work")
     docker_wdir_mount = docker_wdir
     if wdir is not None:
@@ -3445,6 +3625,10 @@ def run_in_env(
                 if isinstance(value, str):
                     value = os.path.expandvars(value)
                 docker_cmd += ["-e", f"{key}={value}"]
+        # A container inherits nothing from here, so what --env-var asked
+        # for has to be handed to it
+        for key, value in extra_env_vars.items():
+            docker_cmd += ["-e", f"{key}={value}"]
         if (gpus := env.get("gpus")) is not None:
             docker_cmd += ["--gpus", gpus]
         if ports := env.get("ports"):