docker-mcp-server 1.9.2__tar.gz → 2.0.0__tar.gz

{docker_mcp_server-1.9.2 → docker_mcp_server-2.0.0}/.claude/commands/docker-sdk.md

@@ -32,7 +32,7 @@ The project structure maps SDK domains to tool files one-to-one:
 
 | docker_mcp/tools/ file | tests/ file | Docker SDK domain |
 |-------------|-------------|-------------------|
-| `docker_mcp/tools/client.py` | `tests/test_client.py` | `DockerClient` |
+| `docker_mcp/tools/system.py` | `tests/test_system.py` | `DockerClient` |
 | `docker_mcp/tools/containers.py` | `tests/test_containers.py` | Containers |
 | `docker_mcp/tools/images.py` | `tests/test_images.py` | Images |
 | `docker_mcp/tools/networks.py` | `tests/test_networks.py` | Networks |

docker_mcp_server-2.0.0/.github/actions/file-failure-issue/action.yaml

@@ -0,0 +1,75 @@
+name: 'File failure issue'
+description: >
+  Opens — or comments on — a deduplicated GitHub issue describing a failed automation run.
+  Dedupe key: an open issue carrying BOTH the shared `ci-failure` label and this workflow's
+  stream label (e.g. `wf:release`), so repeated failures of the same pipeline collect in one
+  thread instead of spawning duplicates. The issue body is written to be actionable by the
+  scheduled Claude responder routine that polls `ci-failure` issues (as well as by a human):
+  it names the failed jobs, links the run, and states how to re-run. The calling job needs
+  `issues: write` permission and must pass `github.token`.
+
+inputs:
+  label:
+    description: 'Per-workflow stream label, e.g. wf:release or wf:canary'
+    required: true
+  title:
+    description: 'Issue title used when no open issue exists for this stream'
+    required: true
+  token:
+    description: 'GitHub token with issues: write (pass github.token)'
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: File or update the failure issue
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        LABEL: ${{ inputs.label }}
+        TITLE: ${{ inputs.title }}
+      run: |
+        set -euo pipefail
+
+        # Ensure the labels exist (idempotent; --force updates color/description if they do).
+        gh label create ci-failure -R "$GITHUB_REPOSITORY" --force \
+          --color B60205 --description "Automated failure report from a workflow run"
+        gh label create "$LABEL" -R "$GITHUB_REPOSITORY" --force \
+          --color D93F0B --description "Failure stream: $LABEL"
+
+        run_url="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
+
+        # The failed jobs have already completed by the time this (if: failure()) job runs.
+        failed_jobs="$(gh api "repos/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}/jobs" --paginate \
+          --jq '.jobs[] | select(.conclusion == "failure") | "- \(.name)"' || true)"
+        if [ -z "$failed_jobs" ]; then
+          failed_jobs="- (could not list failed jobs — see the run)"
+        fi
+
+        body="$(cat <<EOF
+        An automated run of the **${GITHUB_WORKFLOW}** workflow failed.
+
+        - Run: ${run_url}
+        - Failed jobs:
+        ${failed_jobs}
+
+        To re-run after fixing: Actions → ${GITHUB_WORKFLOW} → Run workflow (the Release
+        workflow takes the release tag as input; re-runs are idempotent).
+
+        <!-- filed by .github/actions/file-failure-issue -->
+        EOF
+        )"
+
+        # Dedupe on the open issue carrying both labels: comment there instead of opening a
+        # duplicate, keeping one thread per failure stream.
+        existing="$(gh issue list -R "$GITHUB_REPOSITORY" --state open \
+          --label ci-failure --label "$LABEL" --json number --jq '.[0].number // empty')"
+        if [ -n "$existing" ]; then
+          echo "Open issue #$existing exists for $LABEL — commenting instead of duplicating."
+          gh issue comment "$existing" -R "$GITHUB_REPOSITORY" --body "$body"
+        else
+          gh issue create -R "$GITHUB_REPOSITORY" \
+            --title "$TITLE" \
+            --label ci-failure --label "$LABEL" \
+            --body "$body"
+        fi

{docker_mcp_server-1.9.2 → docker_mcp_server-2.0.0}/.github/copilot-instructions.md

@@ -4,9 +4,9 @@ This file provides guidance to GitHub Copilot when working with code in this rep
 
 ## Project
 
-`docker-mcp` is a Python MCP (Model Context Protocol) server that exposes the Docker SDK for Python — plus selected docker CLI features (Compose, Context, Buildx, Scout) and direct OCI-registry HTTPS access — as MCP tools. It requires Python >=3.14 and is managed with `uv`. It is published to PyPI as **`docker-mcp-server`** and as a container image to GHCR (`ghcr.io/gavinlucas/docker-mcp-server`), mirrored to Docker Hub (`gavinlucas/docker-mcp-server`) when the opt-in `DOCKERHUB_*` release secrets are configured (the import package stays `docker_mcp`, the repo stays `…/docker-mcp`); two console scripts — `docker-mcp` and `docker-mcp-server` — both target `docker_mcp:main`. A third distribution channel packages the server as a **Claude Desktop Extension (`.mcpb`)** attached to each GitHub Release (see "Desktop Extension (MCPB)" below).
+`docker-mcp` is a Python MCP (Model Context Protocol) server that exposes the Docker SDK for Python — plus selected docker CLI features (Compose, Context, Buildx, Scout) and direct OCI-registry HTTPS access — as MCP tools. It requires Python >=3.14 and is managed with `uv`. It is published to PyPI as **`docker-mcp-server`** and as a container image to GHCR (`ghcr.io/gavinlucas/docker-mcp-server`), mirrored to Docker Hub (`gavinlucas/docker-mcp-server`) when the opt-in `DOCKERHUB_*` release secrets are configured (the import package stays `docker_mcp`, the repo stays `…/docker-mcp`); two console scripts — `docker-mcp` and `docker-mcp-server` — both target `docker_mcp:main`. A third distribution channel packages the server as a **Claude Desktop Extension (`.mcpb`)** attached to each GitHub Release (see "Desktop Extension (MCPB)" below). A fourth channel (**Homebrew tap**) exists in `gavinlucas/homebrew-tap` but is currently **paused** — see "Homebrew tap" below.
 
-The `docker` dep uses the `[ssh]` extra (paramiko), so `DOCKER_HOST=ssh://…` works via a pure-Python transport (no system `ssh` binary; works in the container images). docker-py auto-selects paramiko for `ssh://`, so there's no transport code — only the `ssh://` branch in `client._connection_help`. CLI-backed tools (Compose, Buildx, Context, Scout) shell out to `docker`, which would otherwise need the system `ssh` client — instead, `_cli.py:run_docker` detects `DOCKER_HOST=ssh://…` and routes the subprocess through a per-call local TCP proxy (`docker_mcp/tools/_ssh_proxy.py`) that opens its own paramiko connection and runs `docker system dial-stdio` over it, so the CLI authenticates the same way the docker-py-backed tools do, with no system `ssh` binary involved (except a `ProxyCommand` in `~/.ssh/config` for bastion/jump-host setups, which paramiko runs as an external command — commonly `ssh -W %h:%p ...` — for both tool families alike).
+The `docker` dep uses the `[ssh]` extra (paramiko), so `DOCKER_HOST=ssh://…` works via a pure-Python transport (no system `ssh` binary; works in the container images). docker-py auto-selects paramiko for `ssh://`, so there's no transport code — only the `ssh://` branch in `system._connection_help`. CLI-backed tools (Compose, Buildx, Context, Scout) shell out to `docker`, which would otherwise need the system `ssh` client — instead, `_cli.py:run_docker` detects `DOCKER_HOST=ssh://…` and routes the subprocess through a per-call local TCP proxy (`docker_mcp/tools/_ssh_proxy.py`) that opens its own paramiko connection and runs `docker system dial-stdio` over it, so the CLI authenticates the same way the docker-py-backed tools do, with no system `ssh` binary involved (except a `ProxyCommand` in `~/.ssh/config` for bastion/jump-host setups, which paramiko runs as an external command — commonly `ssh -W %h:%p ...` — for both tool families alike).
 
 ## Architecture
 
@@ -26,7 +26,7 @@ from docker_mcp.server import prompt    # prompt modules (with domain=...)
 from docker_mcp.server import mcp       # resource modules only
 ```
 
-`server.py` also owns **`TOOL_CATEGORIES`**, the central map classifying every tool as `READ_ONLY` / `MUTATING` / `DESTRUCTIVE`. The `@tool()` decorator uses it to attach MCP `ToolAnnotations` and to skip registration under the env switches `DOCKER_MCP_SERVER_READONLY` (register only read-only tools) and `DOCKER_MCP_SERVER_NO_DESTRUCTIVE` (register everything except destructive). It also records each tool's **domain** (its defining module's leaf, e.g. `containers`) so the orthogonal `DOCKER_MCP_SERVER_DISABLE=<domains>` switch can drop whole feature areas — including that domain's **prompts** (via the `prompt(domain=...)` helper) and its **doc-resource sections** (via `_SECTION_DOMAINS` in `resources.py`), not just its tools; the live snapshot is the `docker-mcp://tool-catalog` resource (`server.tool_catalog()`). **Every new tool needs a `TOOL_CATEGORIES` entry** — `tests/test_server.py` fails the build if the map drifts from the registered set. The decorator also runs `_slim_schema` on the advertised `inputSchema` to drop three information-free patterns (~18% of schema tokens): pydantic `title` annotations, the `{"type":"null"}` branch of a nullable `anyOf` (gated on a sibling `default`), and redundant `additionalProperties: true`; it's display-only (validation runs off `fn_metadata`), and `tests/test_server.py` asserts none survive. All server tunables are namespaced `DOCKER_MCP_SERVER_*`; read them through `docker_mcp/_env.py` (`read_env` / `env_flag`), which still honors the pre-rename `DOCKER_MCP_*` spellings as deprecated aliases and warns once to stderr.
+`server.py` also owns **`TOOL_CATEGORIES`**, the central map classifying every tool as `READ_ONLY` / `MUTATING` / `DESTRUCTIVE`. The `@tool()` decorator uses it to attach MCP `ToolAnnotations` and to skip registration under the env switches `DOCKER_MCP_SERVER_READONLY` (register only read-only tools) and `DOCKER_MCP_SERVER_NO_DESTRUCTIVE` (register everything except destructive). It also records each tool's **domain** (its defining module's leaf, e.g. `containers`) so the orthogonal `DOCKER_MCP_SERVER_DISABLE=<domains>` switch can drop whole feature areas — including that domain's **prompts** (via the `prompt(domain=...)` helper) and its **doc-resource sections** (via `_SECTION_DOMAINS` in `resources.py`), not just its tools; the live snapshot is the `docker-mcp://tool-catalog` resource (`server.tool_catalog()`). **Every new tool needs a `TOOL_CATEGORIES` entry** — `tests/test_server.py` fails the build if the map drifts from the registered set. The decorator also runs `_slim_schema` on the advertised `inputSchema` to drop three information-free patterns (~18% of schema tokens): pydantic `title` annotations, the `{"type":"null"}` branch of a nullable `anyOf` (gated on a sibling `default`), and redundant `additionalProperties: true`; it's display-only (validation runs off `fn_metadata`), and `tests/test_server.py` asserts none survive. All server tunables are namespaced `DOCKER_MCP_SERVER_*`; read them through `docker_mcp/_env.py` (`read_env` / `env_flag`). The pre-rename `DOCKER_MCP_*` alias spellings were removed in 2.0; the alias-fallback mechanism remains for any future rename.
 
 `server.py` also builds the FastMCP **`instructions`** string — pre-loaded into a client's context with the server name and tool names, *before* any per-tool schema, so for a lazy-loading client (e.g. Claude Code, which fetches tool schemas on demand) it's the main always-in-context surface. It's written as a **router** (per-domain keyword one-liners + a few tool-selection caveats), not docs, and does not enumerate tools (that's `docker-mcp://tool-catalog`). `build_instructions()` renders it from `_DOMAIN_BLURBS`, emitting a domain's line **only when that domain has a registered tool**, so `DOCKER_MCP_SERVER_DISABLE` / `_READONLY` / `_NO_DESTRUCTIVE` are honored via the one registration flag. `finalize_instructions()` (called from `docker_mcp/__init__.py` after all tools import) writes it through to `mcp._mcp_server.instructions` (FastMCP's `instructions` is a read-only property read at `run()` time, so a late write propagates; the reach-in is guarded). **A new tool domain needs a `_DOMAIN_BLURBS` entry** or the router silently omits it.
 
@@ -36,9 +36,9 @@ from docker_mcp.server import mcp       # resource modules only
 
 - **Grammar.** No `=` in the value → bare single-host shorthand (`ssh://ops@prod(ro)`, `auto`, `local`, empty → `auto`); with `=` → comma-separated `label=endpoint` list. `endpoint` is the keyword `auto`/`local` or a `unix://`/`tcp://`/`ssh://`/`npipe://` URL, with combinable trailing markers `(ro)` (read-only) and `(tls=<dir>)` (a tcp+TLS cert dir; **`ca.pem` is required** — the daemon is always verified against it — and `cert.pem`+`key.pem` are optional, present together for mutual TLS or absent for verify-the-daemon-only, e.g. a self-signed daemon pinned via `ca.pem`). **Fail-fast** (`HostConfigError` → stderr + non-zero exit) on duplicate/empty/invalid labels, a missing `=`, an unknown marker, `(tls=)` on a non-tcp endpoint, a missing `ca.pem` or a lone `cert.pem`/`key.pem`, or an unrecognized scheme.
 - **`auto`/`local`/`default` are resolved to concrete URLs by us and pinned at `load()` (startup)** so the docker-py SDK and the CLI shell-out target the *same* daemon for a label (auditable) and a mid-session `docker context use` can't silently move a label. `default` = the first registry entry = the omitted-`host` fallback, and is **not** a selectable label. `load()` runs in `docker_mcp/__init__.py` before the tools import (the `@tool()` decorator and resources read `is_multi()`/`labels()` at registration) and scrubs whole-value `${...}` placeholders first.
-- **Per-call host selection (no modal active-host state).** Every daemon-targeting tool declares `host: str | None = None` and threads it to `_get_client(host)` / `run_docker(..., host=host)`. The `@tool()` decorator does **display-only schema surgery** (`_apply_host_schema`, like `_slim_schema`, gated on `_hosts.is_multi()`) — strip `host` in single-host mode (footprint-neutral), or constrain it to an `enum` of the labels and mark it required for writes in multi-host mode — and wraps the tool with `_enforce_host_guard` (multi-host: writes require an explicit `host`, unknown labels rejected, writes to an `(ro)` host refused; read-only tools and the `_CONNECTION_CONTROL` set `close`/`reconnect`/`login`/`logout` may omit `host`). The guard is wrapped on when `_host_guard_needed()` — multi-host **or a single host flagged `(ro)`**: a lone `(ro)` host has its `host` param stripped (footprint-neutral) but its writes are still refused, so the per-host `(ro)` marker is honored even in single-host mode (distinct from `DOCKER_MCP_SERVER_READONLY`, which drops write tools entirely); a single *writable* host wires no guard. **Excluded** (no `host` param): `registry`/`hub_*` (HTTPS, no daemon) and `context` (manages the host's CLI contexts).
-- **Client / CLI.** `client.py` keeps a lazy pool `_clients` keyed by label with tiered per-host TLS (`(tls=)` dir → global `DOCKER_CERT_PATH`/`DOCKER_TLS_VERIFY` → plaintext); the legacy single host still uses `_build_default_client`/`from_env` unchanged. **`reconnect(host=None)` is rebuild-only** — it can't retarget to an arbitrary URL (edit the registry + restart), closing a trust-expansion hole. `close(host=None)` closes all/one. `startup_preflight` pings the default host but detects self-id against the *self host* (first local-transport entry, which can differ from a remote default); `guard_not_self(container, host=)` only fires on the self host. `_cli.py:_apply_host_env` injects the resolved `DOCKER_HOST` + per-host TLS into the child env for an explicit host.
-- **Surfaces.** `list_hosts` tool + `docker-mcp://hosts` resource expose the resolved registry; the router gains a multi-host caveat; the container observability resources go host-aware (empty-authority `docker:///…` for the default + `docker://{host}/…` variants); a `prompt(multi_host=True)` gate plus the `survey_hosts` prompt register only with 2+ hosts.
+- **Per-call host selection (no modal active-host state).** Every daemon-targeting tool declares `host: str | None = None` and threads it to `_get_client(host)` / `run_docker(..., host=host)`. The `@tool()` decorator does **display-only schema surgery** (`_apply_host_schema`, like `_slim_schema`, gated on `_hosts.is_multi()`) — strip `host` in single-host mode (footprint-neutral), or constrain it to an `enum` of the labels and mark it required for writes in multi-host mode — and wraps the tool with `_enforce_host_guard` (multi-host: writes require an explicit `host`, unknown labels rejected, writes to an `(ro)` host refused; read-only tools and the `_CONNECTION_CONTROL` set `system_close`/`system_reconnect`/`system_login`/`system_logout` may omit `host`). The guard is wrapped on when `_host_guard_needed()` — multi-host **or a single host flagged `(ro)`**: a lone `(ro)` host has its `host` param stripped (footprint-neutral) but its writes are still refused, so the per-host `(ro)` marker is honored even in single-host mode (distinct from `DOCKER_MCP_SERVER_READONLY`, which drops write tools entirely); a single *writable* host wires no guard. **Excluded** (no `host` param): `registry`/`hub_*` (HTTPS, no daemon) and `context` (manages the host's CLI contexts).
+- **Client / CLI.** `system.py` keeps a lazy pool `_clients` keyed by label with tiered per-host TLS (`(tls=)` dir → global `DOCKER_CERT_PATH`/`DOCKER_TLS_VERIFY` → plaintext); the legacy single host still uses `_build_default_client`/`from_env` unchanged. **`system_reconnect(host=None)` is rebuild-only** — it can't retarget to an arbitrary URL (edit the registry + restart), closing a trust-expansion hole. `system_close(host=None)` closes all/one. `startup_preflight` pings the default host but detects self-id against the *self host* (first local-transport entry, which can differ from a remote default); `guard_not_self(container, host=)` only fires on the self host. `_cli.py:_apply_host_env` injects the resolved `DOCKER_HOST` + per-host TLS into the child env for an explicit host.
+- **Surfaces.** `host_list` tool + `docker-mcp://hosts` resource expose the resolved registry; the router gains a multi-host caveat; the container observability resources go host-aware (empty-authority `docker:///…` for the default + `docker://{host}/…` variants); a `prompt(multi_host=True)` gate plus the `survey_hosts` prompt register only with 2+ hosts.
 
 **When reviewing a PR that changes the host grammar, env precedence, or the per-tool/resource/prompt host surface, this section is the spec.**
 
@@ -51,7 +51,7 @@ Each file maps to one Docker SDK domain or one CLI/registry feature area. Unders
 | `_ssh_proxy.py` | Per-call paramiko proxy letting CLI-backed tools dial `ssh://` daemons without a system `ssh` binary (private) | — |
 | `_utils.py` | Shared helpers: `drop_none`, `join_bounded`, `stream_to_file`, `close_stream_quietly`, `MAX_PAYLOAD_BYTES`, plus the container guards `in_container` / `assert_host_writable` / `host_read_path` / `classify_host_kernel` (private) | — |
 | `_labels.py` | Provenance labels stamped on created resources: `with_provenance` / `managed_filter` / `provenance_labels` (private) | — |
-| `client.py` | `DockerClient` — connection, lifecycle, `login`/`logout`, `reconnect` | docker-py |
+| `system.py` | `DockerClient` — connection, lifecycle, `system_login`/`system_logout`, `system_reconnect` | docker-py |
 | `containers.py` | Container lifecycle and management | docker-py |
 | `images.py` | Image pull, build, push, inspect, save/load | docker-py |
 | `networks.py` | Network create, connect, inspect | docker-py |
@@ -74,25 +74,46 @@ Each file maps to one Docker SDK domain or one CLI/registry feature area. Unders
 `docker_mcp/tools/__init__.py` star-imports all public modules so `docker_mcp/__init__.py` only needs `from docker_mcp import tools`.
 
 ### Tests (`tests/`)
-Each `docker_mcp/tools/<module>.py` has a corresponding `tests/test_<module>.py`; `tests/test_server.py` covers the classification/registration machinery. Tests use pytest with mocks. `tests/integration/` holds tests that need a real Docker daemon — excluded by default, run with `uv run pytest -m integration`. `tests/conftest.py` clears the `DOCKER_MCP_*` env switches so the suite is hermetic.
+Each `docker_mcp/tools/<module>.py` has a corresponding `tests/test_<module>.py`; `tests/test_server.py` covers the classification/registration machinery. Tests use pytest with mocks. `tests/integration/` holds tests that need a real Docker daemon — excluded by default, run with `uv run pytest -m integration`. `tests/conftest.py` clears the `DOCKER_MCP_SERVER_*` env switches so the suite is hermetic.
+
+CI (`.github/workflows/premerge.yaml`) enforces `pytest`, `ruff check`, `ruff format --check`, and `pyright` on every PR and push to main — all via `uv run`, so the dev-group pins in `pyproject.toml` (bumped by Dependabot's monthly uv pass) are the single tool-version source; the pre-commit hooks are local hooks running `uv run ruff …` for the same reason. CI installs with `uv sync --locked`, which fails if `uv.lock` disagrees with `pyproject.toml` instead of silently re-locking — so when reviewing a PR that touches only `uv.lock`, check its recorded `requires-dist` specifiers still match pyproject (a Dependabot lock rewrite once raised the cryptography cap in the lock alone). A non-required `Check docs mirror` job flags a PR that edits `CLAUDE.md` or `.github/copilot-instructions.md` without the other (the MIRROR RULE) — when reviewing such a PR, check whether the one-sided edit was intentional.
+
+A **weekly canary** (`.github/workflows/canary.yaml`, Mondays + dispatch) hunts platform/ecosystem drift premerge CI can't see: wheels-only (`--only-binary :all:`) dependency resolution for Intel macOS / ARM macOS / Windows against both the repo `pyproject.toml` and the latest published PyPI release (the check that would have caught cryptography 49 dropping its x86_64-macOS wheel), plus real install smokes of the published package on `macos-latest`, `macos-15-intel` (Intel runner label retires Aug 2027), and `windows-latest` — `import docker_mcp` and `uvx docker-mcp-server --version`. PRs into main also run the repo-pyproject resolution leg (the only part exercising PR content); the published-package legs and issue filing stay schedule/dispatch-only. Failures on unattended runs file a deduplicated `ci-failure` + `wf:canary` issue via `.github/actions/file-failure-issue`. `main()` handles `--version` (print the installed version, exit) before any daemon/network contact — the canary's entry-point smoke depends on it.
 
 ### Container image (`Dockerfile`)
 
-An additional distribution channel alongside the uvx-from-git install (unchanged). One ARG-gated multi-stage `Dockerfile` builds `full` (docker CLI + compose + buildx + scout) and `no-scout` (sets `DOCKER_MCP_SERVER_DISABLE=scout` so absent-plugin scout tools don't register), published on each GitHub Release via `.github/workflows/publish-images.yaml` — always to GHCR, and mirrored to Docker Hub (plus a `DOCKERHUB.md`→Hub-description sync — a slim container-focused readme, as the full `README.md` exceeds Hub's 25 KB cap) when the opt-in `DOCKERHUB_USER`/`DOCKERHUB_TOKEN` secrets are set — the Hub token must have `read/write/delete` scope (build/measure on PRs/pushes is the separate `images.yaml`); `lite` (`INSTALL_CLI=0`) is buildable but not published. Two container-aware guards live behind `_utils.in_container()` (true when `/.dockerenv` exists or `DOCKER_MCP_SERVER_IN_CONTAINER=1`) and are **inert on the host install** — keep them in mind when editing `_utils.py` or the file-path tools:
+An additional distribution channel alongside the uvx-from-git install (unchanged). One ARG-gated multi-stage `Dockerfile` builds `full` (docker CLI + compose + buildx + scout) and `no-scout` (sets `DOCKER_MCP_SERVER_DISABLE=scout` so absent-plugin scout tools don't register), published on each GitHub Release via the `images` job in `.github/workflows/publish.yaml` (see "Release pipeline" below) — always to GHCR, and mirrored to Docker Hub (plus a `DOCKERHUB.md`→Hub-description sync — a slim container-focused readme, as the full `README.md` exceeds Hub's 25 KB cap) when the opt-in `DOCKERHUB_USER`/`DOCKERHUB_TOKEN` secrets are set — the Hub token must have `read/write/delete` scope (build/measure on PRs/pushes is the separate `images.yaml`); `lite` (`INSTALL_CLI=0`) is buildable but not published. Two container-aware guards live behind `_utils.in_container()` (true when `/.dockerenv` exists or `DOCKER_MCP_SERVER_IN_CONTAINER=1`) and are **inert on the host install** — keep them in mind when editing `_utils.py` or the file-path tools:
 
-- **Filesystem guard** — `assert_host_writable` (hooked into `stream_to_file`) refuses a `*_to_file` write to a path that isn't a host bind mount (it would be lost on `--rm`); `host_read_path` enriches the read-side "missing file" case.
-- **Self-termination guard** — `client.startup_preflight()` (called from `main()`) pins the server's own container id (detected against the *self host* — the first local-transport entry, which can differ from a remote default) and prints OS-aware socket hints to stderr; `client.guard_not_self(container, host=)` stops the destructive container-lifecycle tools (`remove`/`kill`/`stop`/`restart`/`pause_container`) from acting on the server's own container, **only when the call targets the self host** (override `DOCKER_MCP_SERVER_ALLOW_SELF_TERMINATE=1`).
+- **Filesystem guard** — `assert_host_writable` (hooked into `stream_to_file`) refuses a host-file write (`dest_path` / `container_archive_get_to_file`) to a path that isn't a host bind mount (it would be lost on `--rm`); `host_read_path` enriches the read-side "missing file" case.
+- **Self-termination guard** — `system.startup_preflight()` (called from `main()`) pins the server's own container id (detected against the *self host* — the first local-transport entry, which can differ from a remote default) and prints OS-aware socket hints to stderr; `system.guard_not_self(container, host=)` stops the destructive container-lifecycle tools (`container_remove`/`container_kill`/`container_stop`/`container_restart`/`container_pause`) from acting on the server's own container, **only when the call targets the self host** (override `DOCKER_MCP_SERVER_ALLOW_SELF_TERMINATE=1`).
 
 ### Desktop Extension (MCPB)
 
-A third distribution channel for one-click install in Claude Desktop. Repo-root sources: `manifest.json` (MCPB manifest, `manifest_version` 0.4, `server.type: "uv"`), `mcpb_run.py` (bundle entry point — `from docker_mcp import main; main()`, at the root so `import docker_mcp` resolves under the host's managed `uv`), `.mcpbignore` (trims the packed bundle to source + `pyproject.toml` + `uv.lock` + `README.md`/`LICENSE` + manifest/entry-point + `assets/`), and `assets/icon.png` (512×512). It's a `uv`-type bundle: the host resolves deps from `pyproject.toml` at install time (no vendored venv). `manifest.json`'s `user_config` maps install-dialog fields to env — `DOCKER_MCP_SERVER_HOSTS` (the single host field; `DOCKER_HOST` is **not** exposed — the bare-value shorthand keeps the one-daemon case a one-liner) and the `DOCKER_MCP_SERVER_READONLY` / `_NO_DESTRUCTIVE` / `_DISABLE` switches (the container-only `_ALLOW_SELF_TERMINATE` is intentionally omitted — the bundle never runs containerized). `.github/workflows/publish-mcpb.yaml` rewrites the manifest `version` from the release tag, packs the `.mcpb` via `npx @anthropic-ai/mcpb`, and attaches it (plus a `.sha256`) to each GitHub Release. `scripts/build-mcpb.sh` is the **developer-only** local equivalent of that pack step (version from `pyproject.toml`, auto-incrementing output in `dist/`, never mutates `manifest.json`) for smoke-testing in Claude Desktop — it is deliberately **not** used by CI. `PRIVACY.md` (no-telemetry statement) is referenced by the manifest's `privacy_policies`. Keep the manifest `version` aligned with `pyproject.toml`; update this section when the manifest's tool/env surface or the bundled file set changes.
+A third distribution channel for one-click install in Claude Desktop. Repo-root sources: `manifest.json` (MCPB manifest, `manifest_version` 0.4, `server.type: "uv"`), `mcpb_run.py` (bundle entry point — `from docker_mcp import main; main()`, at the root so `import docker_mcp` resolves under the host's managed `uv`), `.mcpbignore` (trims the packed bundle to source + `pyproject.toml` + `uv.lock` + `README.md`/`LICENSE` + manifest/entry-point + `assets/`), and `assets/icon.png` (512×512). It's a `uv`-type bundle: the host resolves deps from `pyproject.toml` at install time (no vendored venv). `manifest.json`'s `user_config` maps install-dialog fields to env — `DOCKER_MCP_SERVER_HOSTS` (the single host field; `DOCKER_HOST` is **not** exposed — the bare-value shorthand keeps the one-daemon case a one-liner) and the `DOCKER_MCP_SERVER_READONLY` / `_NO_DESTRUCTIVE` / `_DISABLE` switches (the container-only `_ALLOW_SELF_TERMINATE` is intentionally omitted — the bundle never runs containerized). The `mcpb` job in `.github/workflows/publish.yaml` rewrites the manifest `version` from the release tag, packs the `.mcpb` via `npx @anthropic-ai/mcpb`, and attaches it (plus a `.sha256` recording the bare filename, so `sha256sum -c` works on downloads) to each GitHub Release. `scripts/build-mcpb.sh` is the **developer-only** local equivalent of that pack step (version from `pyproject.toml`, auto-incrementing output in `dist/`, never mutates `manifest.json`) for smoke-testing in Claude Desktop — it is deliberately **not** used by CI. `PRIVACY.md` (no-telemetry statement) is referenced by the manifest's `privacy_policies`. Keep the manifest `version` aligned with `pyproject.toml`; update this section when the manifest's tool/env surface or the bundled file set changes.
+
+### Homebrew tap (`gavinlucas/homebrew-tap`) — PAUSED
+
+The infrastructure exists (`scripts/docker-mcp-server.rb.tpl`, `.github/workflows/publish-homebrew.yaml`, `GavinLucas/homebrew-tap`) but the **release trigger is disabled** pending resolution of a Homebrew dylib linkage issue: pre-built PyPI wheels for `pydantic_core` lack `-headerpad_max_install_names`, so Homebrew's post-install relocation step fails to rewrite the `@rpath` ID (the binary's Mach-O header has no room for the longer absolute path). The workflow is `workflow_dispatch`-only until a fix is found. The channel is not advertised in the README. To re-enable: add `release: types: [published]` back to `publish-homebrew.yaml`'s `on:` block and re-add the Homebrew section to the README.
 
 ### MCP Registry (`server.json`)
 
-A discovery listing in the official MCP Registry (`registry.modelcontextprotocol.io`), which stores only metadata pointing at the existing artifacts. `server.json` (repo root, name `io.github.GavinLucas/docker-mcp-server`) declares three package types — `pypi`, `oci` (GHCR image), `mcpb` (release `.mcpb`). `.github/workflows/publish-registry.yaml` runs on each Release: stamps the tag version + the published `.mcpb`'s `fileSha256` into `server.json`, authenticates via GitHub OIDC (`id-token: write`, no secret), and runs `mcp-publisher publish`. Ownership is verified per package against `server.json`'s `name`, so three markers must equal it: the `<!-- mcp-name: … -->` comment in `README.md` (PyPI), the `io.modelcontextprotocol.server.name` image label in `publish-images.yaml` (OCI), and the `.mcpb` URL + hash (MCPB). Keep them in sync with `server.json`'s `name`.
+A discovery listing in the official MCP Registry (`registry.modelcontextprotocol.io`), which stores only metadata pointing at the existing artifacts. `server.json` (repo root, name `io.github.GavinLucas/docker-mcp-server`) declares three package types — `pypi`, `oci` (GHCR image), `mcpb` (release `.mcpb`). The `registry` job in `.github/workflows/publish.yaml` stamps the tag version + the published `.mcpb`'s `fileSha256` into `server.json`, authenticates via GitHub OIDC (`id-token: write`, no secret), and runs `mcp-publisher publish`. Ownership is verified per package against `server.json`'s `name`, so three markers must equal it: the `<!-- mcp-name: … -->` comment in `README.md` (PyPI), the `io.modelcontextprotocol.server.name` image label in the `images` job (OCI), and the `.mcpb` URL + hash (MCPB). Keep them in sync with `server.json`'s `name`.
+
+### Release pipeline (`.github/workflows/publish.yaml`)
+
+All publishing runs through one workflow on each **published GitHub Release**: `preflight` → `pypi` ∥ `images`(→`dockerhub-description`) ∥ `mcpb` → `registry` → `verify`, plus a `notify` job on failure. `preflight` resolves the tag once (every job checks out **the tag ref**) and fails fast if the tag disagrees with the committed `pyproject.toml` / `manifest.json` / `uv.lock` self-entry versions — preventing a split-brain release where PyPI ships the pyproject version and everything else ships the tag version. `verify` confirms all channels serve the version (PyPI JSON API, both GHCR tags, `.mcpb` asset + checksum, registry listing). `notify` files a deduplicated `ci-failure` + `wf:release` issue via `.github/actions/file-failure-issue` (one open issue per failure stream; a scheduled Claude responder routine polls `ci-failure` issues). Re-runs go through `workflow_dispatch` with the tag and are idempotent end-to-end (`skip-existing` on PyPI, re-pushed image tags, `--clobber` on the `.mcpb`, duplicate-tolerant registry publish). **PyPI Trusted Publishing pins the workflow *filename* (`publish.yaml`)** — when reviewing a PR that renames or splits this workflow, flag that the PyPI trusted publisher must be updated first. `.github/release.yml` (GitHub's release-*notes* config — a different file) groups generated notes; `publish-homebrew.yaml` (paused, dispatch-only) stays separate. When reviewing changes to the pipeline's job graph, ownership markers, or re-run semantics, check this section stays accurate.
 
 ## Conventions
 
+- **Tool naming convention (2.0, permanent):** every tool is named `<management-command>_<verb>`, anchored
+  to the docker CLI's management-command structure (`docker container ls` → `container_list`), with
+  **long-form verbs** (`list`/`remove`/`inspect` — never `ls`/`rm`/`get`), applied uniformly even where the
+  CLI lacks the long alias. Singular prefixes (`container_`, not `containers_`); read-only fetches may be
+  noun-form (`container_logs`, `registry_tags`). Names never encode the backend (SDK vs CLI). Identifier
+  params use one rule: `id_or_name` (daemon objects addressable by either), `name`/`names` (name-only
+  resources: volumes, contexts, plugins, stacks, builders), `repository` (remote repo refs); durations are
+  `timeout_seconds`. `tests/test_naming.py` enforces all of this (approved prefixes, banned short forms and
+  1.x spellings, canonical shared-param descriptions) — a violating tool fails CI.
 - **MIRROR RULE:** this file mirrors `CLAUDE.md` and drives Copilot review of every PR. Any change to project structure, conventions, env vars, or the tool/prompt/resource surface must update **both** files in the same PR — flag a PR that updates one but not the other.
 - New Docker functionality goes in the matching `docker_mcp/tools/<domain>.py` — do not create new tool files without a corresponding entry in `docker_mcp/tools/__init__.py` and a matching test file.
 - Tool functions are decorated with `@tool()` (imported from `docker_mcp.server`) and **must have a `TOOL_CATEGORIES` entry** in `docker_mcp/server.py`. A new tool module is a new domain — also add a `_DOMAIN_BLURBS` entry so the `instructions` router advertises it.
@@ -104,7 +125,7 @@ A discovery listing in the official MCP Registry (`registry.modelcontextprotocol
 
 ### Provenance labels
 
-Resources this server **creates** are stamped with `docker-mcp-server.*` provenance labels (`.managed=true`, `.version`, `.tool`, `.created`) so the agent/operator can later enumerate that footprint (the `managed_only=True` arg on `list_containers` / `list_networks` / `list_volumes` / `list_services`, or `--filter label=docker-mcp-server.managed=true`; the `prune_managed` prompt removes only the managed footprint). On by default; opt out with `DOCKER_MCP_SERVER_NO_LABELS=1`. When adding a new create tool that accepts a `labels` dict, route it through `docker_mcp/tools/_labels.py:with_provenance(labels, "<tool_name>")` — it merges provenance without overwriting caller keys and returns `None` (drop it via `drop_none`) when stamping is disabled and the caller passed nothing. **Image builds are intentionally not stamped** (a build label changes the image digest).
+Resources this server **creates** are stamped with `docker-mcp-server.*` provenance labels (`.managed=true`, `.version`, `.tool`, `.created`) so the agent/operator can later enumerate that footprint (the `managed_only=True` arg on `container_list` / `network_list` / `volume_list` / `service_list`, or `--filter label=docker-mcp-server.managed=true`; the `prune_managed` prompt removes only the managed footprint). On by default; opt out with `DOCKER_MCP_SERVER_NO_LABELS=1`. When adding a new create tool that accepts a `labels` dict, route it through `docker_mcp/tools/_labels.py:with_provenance(labels, "<tool_name>")` — it merges provenance without overwriting caller keys and returns `None` (drop it via `drop_none`) when stamping is disabled and the caller passed nothing. **Image builds are intentionally not stamped** (a build label changes the image digest).
 
 ### CLI shell-out policy
 
@@ -112,7 +133,7 @@ Any tool wrapping a `docker` CLI feature MUST go through `docker_mcp/tools/_cli.
 
 - Wrap every user-supplied **positional** value in `safe_positional(value, "what")` — a value starting with `-` would otherwise be parsed by the docker CLI as a flag (argument injection). The only exception is an argv that is *meant* to be arbitrary (the trailing command of `compose_exec` / `compose_run`).
 - Always pass an explicit `timeout=` to `run_docker` (generous for build/pull, short for queries).
-- Error convention (intentional — do not "unify"): **action tools** return the raw `{"returncode", "stdout", "stderr", "truncated"}` dict and never raise on a non-zero exit; **parsed-query tools** (`context_ls`, `buildx_ls`/`du`, `compose_ls`) raise `RuntimeError` via `raise_on_cli_failure` because they cannot return a useful partial parse.
+- Error convention (intentional — do not "unify"): **action tools** return the raw `{"returncode", "stdout", "stderr", "truncated"}` dict and never raise on a non-zero exit; **parsed-query tools** (`context_list`, `buildx_list`/`du`, `compose_list`) raise `RuntimeError` via `raise_on_cli_failure` because they cannot return a useful partial parse; `compose_ps`/`compose_config` are the sanctioned hybrids (parsed view plus `raw`, never raise).
 
 ### Tool function format
 
@@ -139,8 +160,8 @@ def mcp_example(name: str):
 
 ### Bounding rules
 
-- Tools that buffer a daemon-side byte stream in memory must cap it with `join_bounded(stream, max_bytes, what)`; the in-band default is `MAX_PAYLOAD_BYTES` (32 MiB). Large payloads belong in the `*_to_file` / `*_from_file` variants, which stream via `stream_to_file` / an open file handle.
-- Tools that iterate a potentially endless stream (events, followed logs) must have a wall-clock bound — see the `threading.Timer` + `CancellableStream.close()` watchdog pattern in `client.py:events` and `containers.py:follow_container_logs`.
+- Tools that buffer a daemon-side byte stream in memory must cap it with `join_bounded(stream, max_bytes, what)`; the in-band default is `MAX_PAYLOAD_BYTES` (32 MiB). Large payloads belong in the file-path modes (`dest_path` / `from_file` params, or `container_archive_get_to_file`), which stream via `stream_to_file` / an open file handle.
+- Tools that iterate a potentially endless stream (events, followed logs) must have a wall-clock bound — see the `threading.Timer` + `CancellableStream.close()` watchdog pattern in `system.py:system_events` and `containers.py:container_logs` (follow mode).
 
 ### MCP resources
 
@@ -164,7 +185,7 @@ Docker SDK GitHub: https://github.com/docker/docker-py
 ### Review Notes
 
 There is a dependencies line in pyproject.toml: `"cryptography<49; platform_system == 'Darwin' and platform_machine == 'x86_64'"`
-Changing this line to a later version of cryptography can break installs on Intel (x86_64) macOS, which CI does not currently cover.
+Changing this line to a later version of cryptography can break installs on Intel (x86_64) macOS, which premerge CI does not cover (the canary workflow checks wheels-only resolution for x86_64 macOS — weekly and on PRs into main — and the pin guard in tests/test_pyproject_pins.py is the merge-time enforcement).
 From version 49, cryptography no longer ships a universal2 macOS wheel; on Intel macOS the resolver typically falls back to a source build that requires a newer Rust toolchain and may fail.
 Changing to a later version of cryptography for other platforms is fine, but this pin should remain for macOS x86_64.
 Do not change this line. If a PR touches this line, please add a strong comment and do not allow the change to be merged without a strong justification and approval from the repo owner.

docker_mcp_server-2.0.0/.github/release.yml

@@ -0,0 +1,13 @@
+# GitHub's auto-generated release-notes configuration ("Generate release notes" on the release
+# page groups merged PRs by these label-based categories). NOTE: this is .github/release.yml —
+# GitHub's release-NOTES config — distinct from .github/workflows/publish.yaml (the release
+# pipeline). Dependabot applies the `dependencies` label automatically; everything else lands in
+# the catch-all, and the hand-written release intro stays hand-written.
+changelog:
+  categories:
+    - title: Dependencies
+      labels:
+        - dependencies
+    - title: Changes
+      labels:
+        - "*"

docker_mcp_server-2.0.0/.github/workflows/canary.yaml

@@ -0,0 +1,132 @@
+name: Weekly canary
+
+# Proactive platform/ecosystem drift detection — the class of breakage premerge CI (ubuntu +
+# CPython 3.14 only) can't see. Two angles:
+#
+#   1. resolve-crossplatform (ubuntu, no mac/windows hardware needed): wheels-only dependency
+#      resolution for Intel macOS, Apple-silicon macOS, and Windows — against BOTH the repo's
+#      pyproject.toml (would the next release install?) and the latest published PyPI release
+#      (did an upstream dep pull its wheels out from under an already-shipped version?). This is
+#      exactly the check that would have caught cryptography 49 dropping its x86_64-macOS wheel.
+#   2. install-smoke (real runners): install the published package with uv and import/run it on
+#      macos-latest (arm64), macos-15-intel (x86_64), and windows-latest.
+#
+# On failure the notify job files (or comments on) a deduplicated issue labeled
+# ci-failure + wf:canary — one open issue per stream, so four red Mondays make one thread, which
+# the scheduled Claude responder routine (and the humans it defers to) works from.
+#
+# PRs into main also run the repo-pyproject resolution leg — the only part that exercises the
+# PR's own changes — so a dependency edit that breaks a platform is caught before merge, not the
+# following Monday. The published-package legs (PyPI-release resolution, install smokes) and the
+# issue filing stay schedule/dispatch-only: on a PR they would re-test the already-shipped
+# release and could block a merge on breakage the PR didn't cause.
+
+permissions:
+  contents: read
+
+on:
+  schedule:
+    - cron: '0 6 * * 1'  # Mondays 06:00 UTC
+  workflow_dispatch:
+  pull_request:
+    branches: [main]
+
+jobs:
+
+  resolve-crossplatform:
+    name: Cross-platform wheel resolution
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out source repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+
+      - name: Resolve runtime deps as wheels-only for each platform
+        # --only-binary :all: makes resolution fail if any dependency lacks a wheel for the
+        # target platform — a source-build fallback is exactly the breakage this hunts (users
+        # without a Rust/C toolchain). pyproject.toml resolution covers [project].dependencies
+        # only (the uvx install surface, not dev groups). If a deliberately sdist-only dep ever
+        # enters the tree, exempt it per-package rather than dropping :all:.
+        run: |
+          set -euo pipefail
+          if [ "$GITHUB_EVENT_NAME" != "pull_request" ]; then
+            latest="$(curl -fsSL https://pypi.org/pypi/docker-mcp-server/json | jq -r .info.version)"
+            echo "Latest published release: $latest"
+          fi
+          failed=0
+          for target in x86_64-apple-darwin aarch64-apple-darwin x86_64-pc-windows-msvc; do
+            echo "::group::$target (repo pyproject.toml)"
+            # stdout (the compiled lock) is discarded — only resolution success matters. Don't
+            # use `-o /dev/null`: uv writes output atomically via a sibling temp file, which
+            # fails inside /dev.
+            if ! uv pip compile pyproject.toml --python-platform "$target" --python-version 3.14 \
+                --only-binary :all: > /dev/null; then
+              echo "::error::wheels-only resolution FAILED for $target against the repo pyproject.toml — the next release would not install there"
+              failed=1
+            fi
+            echo "::endgroup::"
+            # The published-release leg tests what's already on PyPI, not this checkout — on a PR
+            # it can only fail for reasons the PR didn't cause, so it runs on schedule/dispatch only.
+            if [ "$GITHUB_EVENT_NAME" != "pull_request" ]; then
+              echo "::group::$target (published docker-mcp-server==$latest)"
+              if ! echo "docker-mcp-server==$latest" | uv pip compile - --python-platform "$target" \
+                  --python-version 3.14 --only-binary :all: > /dev/null; then
+                echo "::error::wheels-only resolution FAILED for $target against published $latest — an upstream dep dropped wheels under a shipped release"
+                failed=1
+              fi
+              echo "::endgroup::"
+            fi
+          done
+          exit "$failed"
+
+  install-smoke:
+    # Real install of the *published* package on each platform's actual runner.
+    # macos-15-intel is the last Intel-macOS hosted runner label; GitHub retires it August 2027.
+    # When the label disappears, drop that matrix leg — wheel resolution for x86_64-apple-darwin
+    # continues in the resolve-crossplatform job above, which needs no Intel hardware.
+    # Skipped on PRs: it installs the published release, so it never exercises PR content.
+    if: github.event_name != 'pull_request'
+    name: Install smoke (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, macos-15-intel, windows-latest]
+    steps:
+      - name: Set up uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          # This job deliberately has no checkout — it tests the *published* package, not the
+          # repo — so disable the repo-keyed cache and the empty-workdir warning it triggers.
+          enable-cache: false
+          ignore-empty-workdir: true
+
+      - name: Import smoke (full tool-registration path, no daemon needed)
+        run: uv run --no-project --python 3.14 --with docker-mcp-server python -c "import docker_mcp"
+
+      - name: Entry-point smoke (uvx console script)
+        # Requires the published package to have the --version flag (shipped in v1.9.3).
+        run: uvx --python 3.14 docker-mcp-server --version
+
+  notify:
+    name: File failure issue
+    runs-on: ubuntu-latest
+    needs: [resolve-crossplatform, install-smoke]
+    # PR failures are visible on the PR itself; the issue stream is for unattended runs.
+    if: failure() && github.event_name != 'pull_request'
+    permissions:
+      contents: read   # checkout, to use the local composite action
+      issues: write
+    steps:
+      - name: Check out source repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: File or update the failure issue
+        uses: ./.github/actions/file-failure-issue
+        with:
+          label: 'wf:canary'
+          title: 'Weekly canary failed'
+          token: ${{ github.token }}

{docker_mcp_server-1.9.2 → docker_mcp_server-2.0.0}/.github/workflows/images.yaml

@@ -21,6 +21,11 @@ on:
       - '.github/workflows/images.yaml'
   workflow_dispatch:
 
+# Cancel superseded runs on the same ref (image builds are the most expensive premerge jobs).
+concurrency:
+  group: images-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
 
   build-and-measure:

{docker_mcp_server-1.9.2 → docker_mcp_server-2.0.0}/.github/workflows/premerge.yaml

@@ -11,6 +11,12 @@ on:
   pull_request:
   workflow_dispatch:
 
+# Cancel superseded runs on the same ref (e.g. rapid pushes to a PR branch); a push to main
+# gets its own ref group so PR runs never cancel main's. Same shape codeql.yaml uses.
+concurrency:
+  group: premerge-${{ github.ref }}
+  cancel-in-progress: true
+
 # Jobs
 jobs:
 
@@ -22,7 +28,7 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Python environment
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
           python-version: "3.14"
 
@@ -30,13 +36,18 @@ jobs:
         uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
 
       - name: Install dependencies
-        run: uv sync --all-groups
+        # --locked fails if uv.lock disagrees with pyproject.toml instead of silently
+        # re-locking — catches a lockfile-only dependency change (e.g. a Dependabot lock
+        # rewrite that raises a cap pyproject still pins) that would otherwise pass CI.
+        run: uv sync --all-groups --locked
 
       - name: Run pytest
         run: uv run pytest -v
 
   ruff-run:
-    # Runs ruff lints
+    # Runs ruff lint + format checks. `uv run` (not `uvx`) so the ruff version is the
+    # dev-group pin resolved through uv.lock — the same version pre-commit hooks run
+    # locally — rather than a floating latest that can disagree with both.
 
     runs-on: [ubuntu-latest]
 
@@ -46,7 +57,7 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Python environment
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
           python-version: "3.14"
 
@@ -54,10 +65,70 @@ jobs:
         uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
 
       - name: Install dependencies
-        run: uv sync --all-groups
+        # --locked fails if uv.lock disagrees with pyproject.toml instead of silently
+        # re-locking — catches a lockfile-only dependency change (e.g. a Dependabot lock
+        # rewrite that raises a cap pyproject still pins) that would otherwise pass CI.
+        run: uv sync --all-groups --locked
+
+      - name: Run ruff lint
+        run: uv run ruff check .
+
+      - name: Run ruff format check
+        run: uv run ruff format --check .
+
+  pyright-run:
+    # Type-checks with the pyright pin from the dev group ([tool.pyright] config in
+    # pyproject.toml). Documented as a project convention; this job enforces it.
+    runs-on: [ubuntu-latest]
+    name: Run pyright
+    steps:
+      - name: Check out source repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Set up Python environment
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.14"
 
-      - name: Run ruff
-        run: uvx ruff check .
+      - name: Set up uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+
+      - name: Install dependencies
+        # --locked fails if uv.lock disagrees with pyproject.toml instead of silently
+        # re-locking — catches a lockfile-only dependency change (e.g. a Dependabot lock
+        # rewrite that raises a cap pyproject still pins) that would otherwise pass CI.
+        run: uv sync --all-groups --locked
+
+      - name: Run pyright
+        run: uv run pyright
+
+  mirror-check:
+    # CLAUDE.md and .github/copilot-instructions.md are mirrors (see the MIRROR RULE in
+    # CLAUDE.md); this flags a PR that edits one without the other. Deliberately NOT a
+    # required check — a one-sided edit can be legitimate (typo, wording) — so a red X
+    # here is a prompt to double-check, not a merge blocker. Fork-safe: read-only, no
+    # secrets, plain git diff (a PR-comment approach would need pull-requests:write,
+    # which fork PRs don't get).
+    runs-on: [ubuntu-latest]
+    name: Check docs mirror
+    if: github.event_name == 'pull_request'
+    steps:
+      - name: Check out source repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0  # need the merge-base with the PR base branch
+
+      - name: Compare CLAUDE.md and copilot-instructions.md changes
+        run: |
+          base="$(git merge-base "origin/${GITHUB_BASE_REF}" HEAD)"
+          changed="$(git diff --name-only "$base" HEAD)"
+          c=$(grep -cx 'CLAUDE.md' <<<"$changed" || true)
+          g=$(grep -cx '.github/copilot-instructions.md' <<<"$changed" || true)
+          if [ "$c" != "$g" ]; then
+            echo "::error::MIRROR RULE: this PR changes one of CLAUDE.md / .github/copilot-instructions.md but not the other. If the change is architectural, mirror it; if it's a legitimate one-sided edit (typo/wording), this warning can be ignored — the check is not required for merge."
+            exit 1
+          fi
+          echo "Docs mirror OK (both changed: $c)"
 
   integration-tests:
     # Runs the suite gated by `-m integration` against the Docker daemon that
@@ -82,7 +153,7 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Python environment
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
           python-version: "3.14"
 
@@ -90,7 +161,10 @@ jobs:
         uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
 
       - name: Install dependencies
-        run: uv sync --all-groups
+        # --locked fails if uv.lock disagrees with pyproject.toml instead of silently
+        # re-locking — catches a lockfile-only dependency change (e.g. a Dependabot lock
+        # rewrite that raises a cap pyproject still pins) that would otherwise pass CI.
+        run: uv sync --all-groups --locked
 
       - name: Verify Docker tooling on the runner
         # ubuntu-latest ships Docker Engine + docker CLI + compose v2 + buildx.