comodor 1.1.0__tar.gz → 1.1.2__tar.gz

{comodor-1.1.0 → comodor-1.1.2}/.gitignore

@@ -51,3 +51,22 @@ PROJECT.md
 # Editor and agent settings that are this machine, not this project.
 .claude/
 *-in-git.png
+
+# Whatever a machine that runs the benchmark keeps locally: the credentials
+# it needs, its run logs, and the script that drives it.
+#
+# None of that is in this repository on purpose. Publishing the runner would
+# publish where a key is kept and what is reachable from the machine holding
+# it, on a repository anybody can read — so it lives only on the machine that
+# uses it, inside a clone, and these rules keep it from being committed back
+# by accident. A key that reaches a public repository has to be revoked, not
+# deleted.
+bench/on-a-server/
+
+# The capability map: what exists, where it lives, and which parts answered
+# when they were last run. Generated by `tools/capability-map.py`, which is
+# committed — the map itself is not, because it is a photograph of one
+# machine at one moment: the "does it run" table records this desk's state,
+# and a committed copy would go stale the day after and be believed anyway.
+# Anybody can rebuild it in ten seconds.
+CAPABILITIES.md

{comodor-1.1.0 → comodor-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: comodor
-Version: 1.1.0
+Version: 1.1.2
 Summary: Comodor — a self-improving terminal coding agent with a Rich TUI
 Project-URL: Homepage, https://comodor.ai
 Project-URL: Repository, https://github.com/ifekri/Comodor
@@ -24,6 +24,7 @@ Classifier: Topic :: Software Development :: Code Generators
 Requires-Python: >=3.9
 Requires-Dist: rich>=13.7
 Provides-Extra: dev
+Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: pyyaml>=6.0; extra == 'dev'
 Requires-Dist: ruff>=0.14; extra == 'dev'

{comodor-1.1.0 → comodor-1.1.2}/docs/README.md

@@ -36,6 +36,7 @@ ends with the agent doing something useful.
 | [In your editor](acp.md) | Drive Comodor from Zed or any Agent Client Protocol client |
 | [In Docker](docker.md) | One command, in a container |
 | [MCP servers](mcp.md) | Tools from the Model Context Protocol |
+| [Repositories on GitHub](github.md) | Read and change repositories that are not checked out here |
 
 ### Understand it
 

{comodor-1.1.0 → comodor-1.1.2}/pyproject.toml

@@ -40,7 +40,10 @@ Changelog = "https://github.com/ifekri/Comodor/blob/main/CHANGELOG.md"
 # travel with it. PyYAML is here so the tests can read `docker-compose.yml` and
 # the workflows as documents rather than as strings; asserting on the text of a
 # YAML file is how a test ends up agreeing with a broken one.
-dev = ["pytest>=8.0", "ruff>=0.14", "pyyaml>=6.0"]
+# pytest-xdist because the suite is mostly waiting: sockets, subprocesses
+# and deliberate timeouts, none of which compete for a CPU. Serially it
+# ran for an hour on every CI job; the work itself was minutes.
+dev = ["pytest>=8.0", "pytest-xdist>=3.5", "ruff>=0.14", "pyyaml>=6.0"]
 
 [project.scripts]
 comodor = "comodor.cli:main"
@@ -95,3 +98,17 @@ include = ["src/comodor", "tests", "pyproject.toml", "README.md", "LICENSE"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["src"]
+# One process per core, and each test file kept whole on one worker. The
+# grouping matters: several files build a real server or a browser in a
+# module-scoped fixture, and splitting a file across workers would build it
+# once per worker rather than once.
+addopts = "-n auto --dist loadfile -m 'not performance'"
+markers = [
+    # Anything whose assertion is about elapsed time: a ceiling, a deadline
+    # for a background job, or an ordering that comes from one thing being
+    # deliberately slower than another. Under `-n auto` these measure a
+    # machine with fifteen other workers on it, and fail in a different file
+    # on a different platform every few runs. Run alone instead, in the same
+    # CI step, with the budgets untouched.
+    "performance: measures wall-clock time, so it runs alone. `pytest -m performance -n 0`; the CI job does.",
+]

{comodor-1.1.0 → comodor-1.1.2}/src/comodor/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.1.0'
-__version_tuple__ = version_tuple = (1, 1, 0)
+__version__ = version = '1.1.2'
+__version_tuple__ = version_tuple = (1, 1, 2)
 
 __commit_id__ = commit_id = None

{comodor-1.1.0 → comodor-1.1.2}/src/comodor/agent/verify.py

@@ -32,6 +32,7 @@ switch off.
 from __future__ import annotations
 
 import os
+import signal
 import subprocess
 from dataclasses import dataclass
 from pathlib import Path
@@ -56,6 +57,38 @@ class Outcome:
     #: Set when the command could not be run at all, as opposed to failing.
     unusable: str = ""
 
+def _end_the_group(child: "subprocess.Popen") -> None:
+    """Kill the check and everything it started. Never raises.
+
+    `pytest` starting workers, `npm` starting a bundler: killing only the
+    shell leaves those behind, running against the user's project after the
+    turn that started them has been abandoned.
+    """
+    try:
+        if hasattr(os, "killpg"):
+            group = os.getpgid(child.pid)
+            # Only a group the check has to itself. `start_new_session` above
+            # gives it one, but if that ever stops happening the child shares
+            # ours, and killing that group would end the agent along with the
+            # command it was running. The signal cannot be taken back, so the
+            # condition is checked rather than trusted.
+            if group != os.getpgid(0):
+                os.killpg(group, signal.SIGKILL)
+                return
+    except (OSError, AttributeError, ProcessLookupError):
+        pass
+    try:
+        # Windows: taskkill walks the tree, which Popen.kill does not.
+        subprocess.run(["taskkill", "/F", "/T", "/PID", str(child.pid)],
+                       capture_output=True, timeout=10)
+    except (OSError, ValueError, subprocess.SubprocessError):
+        pass
+    try:
+        child.kill()
+    except OSError:
+        pass
+
+
 def run(command: str, cwd: Path, patience: float = PATIENCE) -> Outcome:
     """Run the project's check and say what happened. Never raises."""
     if not command.strip():
@@ -65,18 +98,47 @@ def run(command: str, cwd: Path, patience: float = PATIENCE) -> Outcome:
     # A check that shells out to the agent would be a loop with a bill on it.
     environment["COMODOR_VERIFYING"] = "1"
 
+    # `shell=True` means the process started here is a shell, and the check is
+    # its child. Killing the shell on a timeout leaves that child running and
+    # holding the pipes open, so the read below goes on blocking — `patience`
+    # was a ceiling on nothing, and the message said "no result within 2s"
+    # after waiting twenty. The whole group has to go, which needs the platform
+    # to have been told to make one.
+    # Written out rather than gathered into a dict and splatted: this argument
+    # is the difference between ending the check and ending the agent, and it
+    # should be readable as such at the call — by a person, and by anything
+    # checking that every `Popen` beside a `killpg` has one.
     try:
-        finished = subprocess.run(
+        child = subprocess.Popen(
             command, shell=True, cwd=str(cwd), env=environment,
-            capture_output=True, text=True, encoding="utf-8",
-            errors="replace", timeout=patience)
+            stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
+            encoding="utf-8", errors="replace",
+            start_new_session=(os.name != "nt"),
+            creationflags=(subprocess.CREATE_NEW_PROCESS_GROUP
+                           if os.name == "nt" else 0))
+    except (OSError, ValueError) as problem:
+        return Outcome(ran=False, passed=True, output="",
+                       unusable=f"{type(problem).__name__}: {problem}")
+
+    try:
+        finished_out, finished_err = child.communicate(timeout=patience)
     except subprocess.TimeoutExpired:
+        _end_the_group(child)
+        # Drained after the group is gone, so nothing is still writing into a
+        # pipe nobody will read. It cannot block now: every writer is dead.
+        try:
+            child.communicate(timeout=10)
+        except Exception:
+            pass
         return Outcome(ran=True, passed=False,
                        output=f"(no result within {patience:.0f}s)")
     except (OSError, ValueError) as problem:
+        _end_the_group(child)
         return Outcome(ran=False, passed=True, output="",
                        unusable=f"{type(problem).__name__}: {problem}")
 
+    finished = subprocess.CompletedProcess(
+        command, child.returncode, finished_out, finished_err)
     output = ((finished.stdout or "") + (finished.stderr or "")).strip()
     if len(output) > MOST:
         output = "…\n" + output[-MOST:]

{comodor-1.1.0 → comodor-1.1.2}/src/comodor/browser/launch.py

@@ -16,8 +16,10 @@ performs on purpose survives, and obviously separate from the browser they use.
 
 from __future__ import annotations
 
+import atexit
 import os
 import shutil
+import signal
 import socket
 import subprocess
 import sys
@@ -140,6 +142,33 @@ def _first_line(output: str) -> str:
     return f" It said: {first.strip()[:300]}"
 
 
+#: Every browser started and not yet stopped. A `finally` covers the ordinary
+#: path, and nothing covers the one that actually leaks: a run interrupted —
+#: Ctrl-C, a test-runner timeout, a session killed — never reaches its cleanup,
+#: and Chrome is a dozen processes that outlive the Python that started them.
+#: They hold their profile directory and their share of a gigabyte, and nothing
+#: in a later run knows to clean up an earlier one's. They accumulate for days
+#: until somebody notices their machine is full of browsers nobody opened.
+_LIVE: "set[Browser]" = set()
+
+
+def _remember(browser: "Browser") -> None:
+    _LIVE.add(browser)
+
+
+def _stop_everything_still_open() -> None:
+    """Registered with `atexit`, so an abandoned browser still goes away."""
+    for browser in list(_LIVE):
+        try:
+            browser.stop()
+        except Exception:
+            pass
+    _LIVE.clear()
+
+
+atexit.register(_stop_everything_still_open)
+
+
 class Browser:
     """A browser process we started, and are responsible for stopping."""
 
@@ -209,6 +238,11 @@ class Browser:
                 stdin=subprocess.DEVNULL,
                 creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0)
                 if os.name == "nt" else 0,
+                # A group of its own, so ending the browser's group ends the
+                # browser. Without this the child inherits *our* group, and
+                # `killpg` on it kills whatever started us as well — the whole
+                # test run, the whole agent session.
+                start_new_session=(os.name != "nt"),
             )
         except OSError as error:
             complaints.close()
@@ -216,6 +250,7 @@ class Browser:
 
         browser = cls(binary, profile, port, headless, process,
                       sandboxed=sandboxed)
+        _remember(browser)
         try:
             browser._await_port()
         except BrowserError as error:
@@ -270,9 +305,28 @@ class Browser:
         info = version(self.port)
         return info.get("Browser") or Path(self.executable).stem or "browser"
 
+    def _forget(self) -> None:
+        _LIVE.discard(self)
+
     def stop(self) -> None:
+        """Close the browser and everything it started.
+
+        A browser is not one process. Chrome starts a renderer per tab, a GPU
+        process, a crashpad handler and more, and `terminate` on the one we
+        launched leaves every one of them running — holding its profile
+        directory, and its share of a gigabyte of memory. Eight strays per
+        run, and nothing in a later run cleans up an earlier one's: they
+        accumulate until somebody notices their machine is full of browsers
+        nobody opened.
+        """
         if not self.ours or self.process is None:
             return
+
+        # The tree first, while the parent is still alive to name it. Killing
+        # the parent before asking leaves orphans whose parent id points at
+        # nothing, and then there is no tree left to walk.
+        self._end_the_tree()
+
         try:
             self.process.terminate()
             self.process.wait(timeout=8)
@@ -282,3 +336,30 @@ class Browser:
             except OSError:
                 pass
         self.process = None
+        self._forget()
+
+    def _end_the_tree(self) -> None:
+        """The browser and every process it started. Never raises."""
+        pid = getattr(self.process, "pid", None)
+        if pid is None:
+            return
+        try:
+            if hasattr(os, "killpg"):
+                group = os.getpgid(pid)
+                # Only ever a group the browser has to itself. A child started
+                # without `start_new_session` inherits ours, and killing that
+                # group kills whoever started us — the test run, the agent, the
+                # shell. Checked rather than trusted: this signal cannot be
+                # taken back, and the cost of being wrong is the whole session.
+                if group != os.getpgid(0):
+                    os.killpg(group, signal.SIGKILL)
+                    return
+        except (OSError, AttributeError, ProcessLookupError):
+            pass
+        try:
+            # `taskkill /T` walks the tree from a living parent; `Popen.kill`
+            # only ever ends the one process.
+            subprocess.run(["taskkill", "/F", "/T", "/PID", str(pid)],
+                           capture_output=True, timeout=15)
+        except (OSError, ValueError, subprocess.SubprocessError):
+            pass

{comodor-1.1.0 → comodor-1.1.2}/src/comodor/channels/settings.py

@@ -158,6 +158,12 @@ def hold_the_line(config: Any, section: str, talk: Any) -> bool:
     settings = getattr(config, section, None)
     if settings is None or getattr(settings, "allow_writes", False):
         return False
+    # A conversation that was granted Act by its own approval keeps it. The
+    # channel-wide flag being off is the normal state for those chats — it is
+    # what makes the approval prompt appear in the first place — so treating
+    # it as a revocation would end the grant on the very next message.
+    if getattr(talk, "may_write", False):
+        return False
     session = getattr(talk, "session", None)
     if session is None:
         return False

{comodor-1.1.0 → comodor-1.1.2}/src/comodor/cli.py

@@ -122,6 +122,7 @@ def build_parser() -> argparse.ArgumentParser:
     from .acp.commands import register as register_acp
     from .cron.commands import register as register_cron
     from .discord.commands import register as register_discord
+    from .github.commands import register as register_github
     from .learning.commands import register as register_curator
     from .learning.journey_commands import register as register_journey
     from .learning.providers.commands import register as register_memory_provider
@@ -143,6 +144,7 @@ def build_parser() -> argparse.ArgumentParser:
     register_whatsapp(sub)
     register_slack(sub)
     register_discord(sub)
+    register_github(sub)
     register_skills(sub)
     register_web(sub)
     register_webhook(sub)
@@ -1058,6 +1060,11 @@ def main(argv: list[str] | None = None) -> int:
         from .slack.commands import run as run_slack
 
         return run_slack(config, args)
+    if args.command == "github":
+        from .github.commands import run as run_github
+
+        return run_github(config, args)
+
     if args.command == "discord":
         from .discord.commands import run as run_discord
 

{comodor-1.1.0 → comodor-1.1.2}/src/comodor/config.py

@@ -23,6 +23,7 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import stat
 from dataclasses import dataclass, field, fields, is_dataclass
 from pathlib import Path
@@ -636,6 +637,212 @@ class DiscordConfig:
         return bool(user_id) and int(user_id) in {int(x) for x in self.allowed}
 
 
+#: The grant format this agent can use.
+#:
+#: Version 1 grants said which key owned which installation and nothing more,
+#: so an endpoint holding one could not tell whether the person who made the
+#: connection still had access to it. Version 2 names them. There is no
+#: upgrade path - the missing field is not something either side can look up -
+#: so an old grant is reported as needing a reconnection rather than tried.
+GRANT_FORMAT = "g2"
+
+
+@dataclass
+class GitHubInstallation:
+    """One GitHub App installation, as this machine knows it.
+
+    An installation is the unit GitHub actually grants against: somebody
+    installs the app onto an account — their own or an organisation's — and
+    chooses which repositories it may see. One person can have several, and a
+    repository belongs to exactly one, so `github_connected = true` would be a
+    lie about a shape that is genuinely plural.
+
+    What is *not* here is any credential. An installation access token lasts an
+    hour and is minted from the app's private key when it is needed; writing
+    one to a config file would leave a working key on disk long after the
+    session that fetched it, for no gain over asking again.
+
+    The grant is not a credential either, and that is worth being precise
+    about because it looks like one. It is a signed statement that this
+    installation belongs to a particular public key, and it is useless without
+    the private half - which is not in this file, and is not in any file this
+    one links to. Somebody who copies their config into a gist has published
+    nothing that can be used.
+    """
+
+    installation_id: int = 0
+    #: The account it was installed on, and what kind. Kept because it is what
+    #: a person recognises — "ifekri" or "comodor-ai" — where the id is not.
+    account_id: int = 0
+    account_login: str = ""
+    account_type: str = ""              # "User" or "Organization"
+    #: "all" or "selected", as GitHub reports it. Worth storing: it is the
+    #: difference between "this will see the next repository you make" and
+    #: "it will not", which somebody deciding whether to widen it needs.
+    repository_selection: str = ""
+    #: What the app was granted, verbatim from GitHub. A capability check
+    #: reads this rather than assuming, so a narrowed permission is a clear
+    #: refusal instead of a 403 from the middle of an operation.
+    permissions: dict[str, str] = field(default_factory=dict)
+    #: Seconds since the epoch. Two timestamps rather than one because
+    #: "connected in March, last confirmed yesterday" and "connected in March,
+    #: never seen since" are different situations.
+    created_at: float = 0.0
+    updated_at: float = 0.0
+    #: The Worker's signed statement that this installation belongs to this
+    #: machine's key for it, and to the person who connected it. Sent with
+    #: every request that could do something, and the only place the
+    #: installation id is read from - a request that merely names an id proves
+    #: nothing, which is what an earlier version of this got wrong.
+    #:
+    #: It is not a licence. The endpoint asks GitHub whether the person named
+    #: in it is *still* entitled before it hands anything over, so a grant kept
+    #: after somebody loses access stops working rather than outliving it.
+    grant: str = ""
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "installation_id": int(self.installation_id),
+            "account_id": int(self.account_id),
+            "account_login": self.account_login,
+            "account_type": self.account_type,
+            "repository_selection": self.repository_selection,
+            "permissions": dict(self.permissions),
+            "created_at": float(self.created_at),
+            "updated_at": float(self.updated_at),
+            "grant": self.grant,
+        }
+
+    @property
+    def usable(self) -> bool:
+        """Whether this connection can still do anything.
+
+        Two ways it cannot. No grant at all is a leftover from a version that
+        did not have them, or a connection whose key was lost. A `g1.` grant is
+        from before the grant named the person it was issued to, which means
+        the endpoint has no way to re-check whether that person still has
+        access - so it refuses them, and reconnecting is the fix.
+
+        Both read as connected and fail at the first request, which is why
+        `status` says so up front instead.
+        """
+        return bool(self.installation_id and self.grant
+                    and self.grant.startswith(f"{GRANT_FORMAT}."))
+
+    def may(self, permission: str, level: str = "read") -> bool:
+        """Whether this installation was granted `permission` at `level`.
+
+        GitHub reports "read" or "write"; write implies read. Asked before an
+        operation so a missing grant is a sentence naming what to change,
+        rather than a 403 from four calls into a sequence.
+        """
+        granted = str(self.permissions.get(permission, "")).lower()
+        if not granted:
+            return False
+        return granted == "write" or level == "read"
+
+
+@dataclass
+class GitHubConfig:
+    """Repositories on GitHub, reached through a GitHub App.
+
+    A provider like any other, and deliberately not load-bearing: everything
+    Comodor does to a local checkout works with none of this configured. What
+    it adds is the ability to open a pull request on a repository this machine
+    has never cloned.
+
+    No token lives here. The app holds a private key on the server that mints
+    short-lived installation tokens, and this file holds only which
+    installations exist and what they cover. Nothing in it is a secret, which
+    is why it can sit in a config file people read and paste from.
+    """
+
+    enabled: bool = False
+    #: The installations this machine has connected, newest last. Plural
+    #: because a person with a personal account and two organisations has
+    #: three, and a repository resolves to exactly one of them.
+    installations: list[GitHubInstallation] = field(default_factory=list)
+    #: Where the installation flow is served. Overridable for a self-hosted
+    #: deployment; the default is the one this project runs.
+    endpoint: str = "https://comodor.ai"
+    #: What a branch the agent opens is called. The kind is appended:
+    #: `comodor/fix-...`, `comodor/feature-...`.
+    branch_prefix: str = "comodor/"
+    #: Whether a turn may write to a repository at all. Off until somebody
+    #: says otherwise, for the same reason the channels are: a pull request
+    #: opened by mistake is public and cannot be unseen.
+    allow_writes: bool = False
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "enabled": self.enabled,
+            "installations": [one.to_json() for one in self.installations],
+            "endpoint": self.endpoint,
+            "branch_prefix": self.branch_prefix,
+            "allow_writes": self.allow_writes,
+        }
+
+    def find(self, owner: str) -> GitHubInstallation | None:
+        """The installation covering `owner`, or None.
+
+        By login rather than by id because that is what a person types and
+        what a repository string carries: `ifekri/Comodor` names the owner in
+        the half before the slash.
+        """
+        wanted = (owner or "").strip().lower()
+        for one in self.installations:
+            if one.account_login.lower() == wanted:
+                return one
+        return None
+
+    def find_by_id(self, installation_id: int) -> GitHubInstallation | None:
+        """The installation with this id, or None.
+
+        By id rather than by login, because this is what the signing path
+        needs: it is handed an id and has to find the grant that goes with it.
+        Returning None means there is no grant, which means no request, rather
+        than a request that would be refused.
+        """
+        try:
+            wanted = int(installation_id)
+        except (TypeError, ValueError):
+            return None
+        for one in self.installations:
+            if one.installation_id == wanted:
+                return one
+        return None
+
+    def remember(self, installation: GitHubInstallation) -> None:
+        """Add or replace one installation, keyed by its id.
+
+        Replacing matters: reinstalling, or widening the repository
+        selection, produces the same installation id with different contents,
+        and appending would leave the old permissions to be found first.
+        """
+        for index, existing in enumerate(self.installations):
+            if existing.installation_id == installation.installation_id:
+                installation.created_at = (existing.created_at
+                                           or installation.created_at)
+                # The grant is carried over only when the new record has none
+                # - a `verify` refreshes permissions and has no grant to give,
+                # and dropping it there would break the connection it just
+                # confirmed. A `connect` brings its own, newer, and matching a
+                # key that has just replaced the old one on disk, so it wins.
+                if not installation.grant:
+                    installation.grant = existing.grant
+                self.installations[index] = installation
+                return
+        self.installations.append(installation)
+
+    def forget(self, installation_id: int) -> bool:
+        """Drop one. True if it was there — a revocation nobody had is not an
+        error, but it is worth being able to say so."""
+        before = len(self.installations)
+        self.installations = [one for one in self.installations
+                              if one.installation_id != int(installation_id)]
+        return len(self.installations) != before
+
+
 @dataclass
 class MCPConfig:
     """Servers, and the master switch over all of them."""
@@ -957,7 +1164,7 @@ DEFAULT_DENY: tuple[str, ...] = (
 SECTIONS = ("ui", "agent", "gateway", "learning", "curator", "skills", "safety",
             "browser", "computer", "telegram", "whatsapp", "slack", "discord",
             "cron", "media", "voice", "delegation", "shell", "api", "webhook",
-            "image_gen")
+            "image_gen", "github")
 
 
 @dataclass
@@ -976,6 +1183,7 @@ class Config:
     whatsapp: WhatsAppConfig = field(default_factory=WhatsAppConfig)
     slack: SlackConfig = field(default_factory=SlackConfig)
     discord: DiscordConfig = field(default_factory=DiscordConfig)
+    github: GitHubConfig = field(default_factory=GitHubConfig)
     mcp: MCPConfig = field(default_factory=MCPConfig)
     cron: CronConfig = field(default_factory=CronConfig)
     media: MediaConfig = field(default_factory=MediaConfig)
@@ -1370,6 +1578,43 @@ def _coerce(key: str, value: Any, current: Any) -> tuple[bool, Any, str]:
         return False, None, "must be an object"
     return True, value, ""
 
+def _list_of_dataclasses(field_info: Any, value: Any) -> list[Any] | None:
+    """Rebuild `list[SomeDataclass]` from the dicts JSON gives back.
+
+    `_apply` understood a nested dataclass and a list of scalars, and a list of
+    dataclasses fell between them: the dicts were stored as dicts, and the
+    first attribute access on one raised `AttributeError` from wherever it
+    happened to be read. Nothing had this shape until now, which is why the
+    gap survived.
+
+    Returns None when the field is not that shape, so the caller falls through
+    to the ordinary coercion.
+    """
+    if not isinstance(value, list):
+        return None
+
+    annotation = field_info.type
+    # `from __future__ import annotations` makes these strings, so the type is
+    # read from the text rather than from the object.
+    text = annotation if isinstance(annotation, str) else str(annotation)
+    match = re.fullmatch(r"list\[([A-Za-z_][A-Za-z0-9_]*)\]", text.strip())
+    if not match:
+        return None
+
+    kind = globals().get(match.group(1))
+    if not (isinstance(kind, type) and is_dataclass(kind)):
+        return None
+
+    rebuilt = []
+    for entry in value:
+        if not isinstance(entry, dict):
+            continue                     # a malformed row is dropped, not fatal
+        made = kind()
+        _apply(made, entry)
+        rebuilt.append(made)
+    return rebuilt
+
+
 def _apply(section: Any, values: dict[str, Any], where: str = "",
            complaints: list[str] | None = None) -> None:
     """Copy known keys onto a dataclass, ignoring unknown ones.
@@ -1384,6 +1629,7 @@ def _apply(section: Any, values: dict[str, Any], where: str = "",
     as a string that is true.
     """
     valid = {f.name for f in fields(section)}
+    annotated = {f.name: f for f in fields(section)}
     for key, value in values.items():
         if key not in valid:
             continue
@@ -1391,6 +1637,10 @@ def _apply(section: Any, values: dict[str, Any], where: str = "",
         if is_dataclass(current) and isinstance(value, dict):
             _apply(current, value, f"{where}{key}.", complaints)
             continue
+        rebuilt = _list_of_dataclasses(annotated[key], value)
+        if rebuilt is not None:
+            setattr(section, key, rebuilt)
+            continue
         ok, coerced, why = _coerce(key, value, current)
         if not ok:
             if complaints is not None: